Image Processing Commands

-1 Below are the image processing related commands. Most of these commands require the use of MaxIM DL/CCD and/or Pinpoint software.

The command maximon must be used before most image processing commands can be used.

maximon and maximoff
setcalibration
savecalibration
loadimagefile, saveimagefile, and closeimagefile

calibrate

batchcalibratefiles

kernelfilter

maximon

Syntax: maximon

This command initiates communication with MaxIm DL and is to be used before all image processing commands in this section. However, it is not necessary when using the CCD Imaging Commands that take real-time images with a CCD camera. If this operation is successful, the variable MAXIMCONNECTED is set to "true", otherwise the variable MAXIMERROR is set to "true".

maximoff

Syntax: maximoff

This command terminates communication with MaxIm DL and sets the variable MAXIMCONNECTED to "false".

setcalibration

Syntax: setcalibration bias.fit dark.fit flat.fit

This command sets the image files used by MaxIm DL to perform image calibrations. All three types (bias, dark, and flat) of image files must be specified. If the files specified are not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. Filenames can contain wildcard character (* or ?) to specify more than one file. The variable MAXIMERROR is set accordingly. This command must be used prior to using the calibrate and calibratefile commands.

savecalibration

Syntax: savecalibration bias.fit dark.fit flat.fit

This command creates and saves master bias, dark, and flat field images. It must be done after a setcalibration command and before any calibrations have been performed. The filenames are specified as parameters and if they are not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. The variable MAXIMERROR is set accordingly. Note that a bug/limitation in MaxIM DL (V4.53) exists that means that these files cannot be easily used for subsequent calibrations – they do not contain the appropriate FITS header entries (EXPTIME, CCDTEMP, etc.).

loadimagefile

Syntax: loadimagefile file.fit <calibrate>

This command loads into memory the image file "file.fit" so that it can be accessed by other commands below. Only one file can be loaded at a time so if a file is already loaded, it will be closed. If the filename specified is not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. If optional parameter "calibrate" is "true", the image is calibrated after it is loaded (this must be done after a setcalibration command). The variable MAXIMERROR is set accordingly.

saveimagefile

Syntax: saveimagefile file.fit <fitssize>

This command saves and closes the image file loaded by the loadimagefile command to the file "file.fit". If "fitssize" is not specified 16-bit FITS format is used. If "fitssize" is specified, the format used is as follows:

0 - 8 bit integer (1 byte per pixel, 256 levels)
1 - 16 bit integer (2 bytes per pixel, 65536 levels)
2 - 32 bit integer (4 bytes per pixel, more than four billion levels)
3 - 32 bit float (4 bytes per pixel in IEEE floating point format)

If the filename specified is not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. The variable MAXIMERROR is set accordingly.

closeimagefile

Syntax: closeimagefile

This command closes the image file loaded by the loadimagefile command without saving it. The variable MAXIMERROR is set accordingly.

calibrate

Syntax: calibrate

This command calibrates either the just-exposed CCD image or an image that has been loaded using the loadimagefile command using the calibration files specified by the setcalibration command. The FITS header key value "CALIBRAT" is set to "YES". If an image has been loaded with the loadimagefile command, it is calibrated even an CCD image has just been exposed. The variable MAXIMERROR is set to "true" if an error occurs from an image loaded by loadimagefile, otherwise CCDERROR is set to "true" if an error occurs from a just-exposed image.

batchcalibratefiles

Syntax: batchcalibratefiles infiles*.fit <outdirectory>

This command calibrates all files matching "infiles*.fit". If the file mask specified is not fully-qualified the directory specified by the IMAGEDIRECTORY variable is used. If specified, the calibrated images are saved to "outdirectory", otherwise they are saved to the directory specified by the IMAGEDIRECTORY variable. This command must be done after a setcalibration command. The variable MAXIMERROR is to "true" if any error is detected.

kernelfilter

Syntax: kernelfilter

This command performs either a kernel filter (as configured in the variables KERNELFILTERVALUE and KERNELFILTERTYPE) on the just-exposed CCD image or on an image that has been loaded using the loadimagefile command. The variable

Valid values for KERNELFILTERTYPE are:

0 - standard high pass filter fot a 3x3 neighbourhood
1 - standard high pass filter for a 5x5 neighbourhood
2 - standard low pass filter for a 3x3 neighbourhood
3 - standard low pass filter for a 5x5 neighbourhood
4 - dead pixel filter: replaces every pixel darker by Threshold than its darkest neighbour with the median of its surrounding pixels
5 - hot pixel filter: replaces every pixel brighter by Threshold than its brightest neighbour with the median of its surrounding pixels
6 - "boxcar" lowpass filter, replaces every pixel by the neigbbourhood average
7 - replaces every pixel by the neigbbourhood median
8 - replaces every pixel by the neigbbourhood maximum
9 - replaces every pixel by the neigbbourhood minimum
10 - performs a User Kernel filter operation. These filters are setup within Maxim DL's user interface
11 - performs a Gaussian Blur on the image, using a precomputed kernel whose size is approximately six times the blur radius

KERNELFILTERVALUE specifies the Threshold percentage for identifying Dead or Hot pixels, the neighbourhood size (3, 5, or 7) for Average, Median, Maximum and Minimum filters, and the user kernel number for the User Kernel filter. For the Gaussian Blur filter, this value specifies the blur radius in pixels, which must be in the range 0.0 to 5.0.

MAXIMERROR is set to "true" if an error occurs from an image loaded by loadimagefile, otherwise CCDERROR is set to "true" if an error occurs from a just-exposed image.

fftfilter

Syntax: fftfilter

This command performs either an FFT filter (as configured in the variables FFTFILTERTYPE, FFTFILTERCUTOFF, and FFTFILTERWEIGHT) on the just-exposed CCD image or on an image that has been loaded using the loadimagefile command. The variable MAXIMERROR is set to "true" if an error occurs from an image loaded by loadimagefile, otherwise CCDERROR is set to "true" if an error occurs from a just-exposed image.

Valid values for KERNELFILTERTYPE are:

0 - High pass filter (for sharpening image)
1 - Low pass filter (for smoothing image)

FFTFILTERCUTOFF is the radius of filter cutoff as percentage of image size. FFTFILTERWEIGHT is the weight (0 to 100%) applied to filter output when mixing with original input data to produce the final result.

For a high pass filter, a FFTFILTERCUTOFF value of 50% corresponds to a mild filter, 25% to medium, and 10% to hard. For a low pass filter, a FFTFILTERCUTOFF value of 5% corresponds to a mild filter, 2.5% to medium, and 1.5% to hard. The FFTFILTERWEIGHT value is used in the final mixing staging to moderate the amount of filtering; typical values range from 30% for restrained filtering to 80% for strong effects.

flattenbackground

Syntax: flattenbackground

This command flattens the background (such as is caused by moonlight, light pollution, or vignetting in the optical system) of an image that has been loaded using the loadimagefile command. The variable MAXIMERROR is set to "true" if an error occurs.

removegradient

Syntax: removegradient

This command removes a linear gradient in the background level (typically caused by moonlight or light pollution) of an image that has been loaded using the loadimagefile command. The variable MAXIMERROR is set to "true" if an error occurs.

flip

Syntax: flip

This command flips from top to bottom an image that has been loaded using the loadimagefile command. The variable MAXIMERROR is set to "true" if an error occurs.

mirror

Syntax: mirror

This command mirrors from left to right an image that has been loaded using the loadimagefile command. The variable MAXIMERROR is set to "true" if an error occurs.

rotate

Syntax: rotate angle <resample_flag>

This command rotates, by "angle" degrees (-360 to 360), an image that has been loaded using the loadimagefile command. Negative values up rotate counter-clockwise and positive values rotate clockwise. If "resample_flag" is true, bi-cubic resampling is used otherwise bi-linear resampling is used, which is the default. If "angle" is a multiple of 90 degrees resampling is not used. The variable MAXIMERROR is set to "true" if an error occurs.

resize

Syntax: resize width <height>

This command resizes (by bilinear interpolation) an image that has been loaded using the loadimagefile command to "width" by "height" in size. Note that the aspect ratio of the image will change if "width" and "height" are not the same ratio as the size of the original image. If "height" is not specified, the image is resized using the "width" and the aspect ratio of the original image is retained. The variable MAXIMERROR is set to "true" if an error occurs.

crop

Syntax: crop left top width height

This command crops an image that has been loaded using the loadimagefile command such that the upper left corner is at position "left" and "top" and the new image size is "width" by "height" pixels. If "left" is -1, then the cropped image is centered horizontally. If "top" is -1 then cropped image is centered vertically. The rectangle defined must be contained within the size of the original image. The first pixel for "left" and "top" has a value of 0. Note that the aspect ratio of the image will change if "width" and "height" are not the matched with the original image. The variable MAXIMERROR is set to "true" if an error occurs.

croppercent

Syntax: croppercent left top width height

This command crops an image that has been loaded using the loadimagefile command such that the upper left corner is at position "left" and "top" and the new image size is "width" by "height" percent of the original image size. If "left" is -1, then the cropped image is centered horizontally. If "top" is -1 then cropped image is centered vertically. The rectangle defined must be contained within the size of the original image. The first pixel for "left" and "top" has a value of 0. Note that the aspect ratio of the image will change if "width" and "height" are not the matched with the original image. The variable MAXIMERROR is set to "true" if an error occurs.

stretch

Syntax: stretch type(0-2) gamma not_used outputrange inputrange <min max>
stretch type(3) base power outputrange inputrange <min max>

This command stretches an image that has been loaded using the loadimagefile command as defined by the parameters:

Stretch Type:

"type" of 0 - linear (set the "gamma" and "not_used" parameters to 0)
"type" of 1 - logarithmic (set the "gamma" and "not_used" parameters to 0)
"type" of 2 - gamma with parameter of "gamma". A gamma of less than 1 enhances faint details or a gamma of greater than 1 enhances brighter details. The valid range is 0.05 to 20. Set the "not_used" parameter to 0.
"type" of 3 - arcsinh with parameters of "base" and "power". The "base" parameter sets the black level within the output image as 0 to 100% of the output range. The "arcsinh_power" parameter sets the relative arcsinh stretch factor (from 0.01 to 10). A "base" value of 6 and a "power" value of 5 works well for many astronomical objects.

Output Range:

"outputrange" of 0 - scale output to range of 0 to 255
"outputrange" of 1 - scale output to range of 0 to 4095
"outputrange" of 2 - scale output to range of 0 to 65535
"outputrange" of 3 - scale output to unlimited (positive) range. For arcsinh stretches a range of 0 to 65535 is used but values greater than 65536 are not clipped.

Input Range:

"inputrange" of 0 - limit input range to faintest to brightest pixel
"inputrange" of 2

for linear, log, and gamma stretches, limit input range to between "min" and "max". The valid range is 0 to 65535. "max" must be greater than "min".
for an arcsinh stretch:

The "min" parameter operates as follows:

min>=0: the percentage (an integer) of the pixels of the histogram that becomes black
min=-1: means black becomes the median of the pixel values
min=-2: means black becomes 1/4 from the bottom of the sorted pixel values
min=-3: means black becomes 1/8 from the bottom of the sorted pixel values
min=-4: means black becomes 1/16 from the bottom of the sorted pixel values
min=-5: means black becomes 1/32 from the bottom of the sorted pixel values
min=-6: means black becomes 1/64 from the bottom of the sorted pixel values

The "max" parameter is the percentage (an integer) of the pixels of the histogram that becomes white.

If the stretch type is non-linear (log, gamma, or arcsinh), the fits header key STRETCH is set to "LOG", "GAMMA" or "ARCSINH" respectively. The variable MAXIMERROR is set to "true" if an error occurs.

alignxy

Syntax: alignxy centrex centrey

This command aligns an image that has been loaded using the loadimagefile command. The image is shifted by an integer number of pixels so that the new centre is at the specified pixel positions "centrex" and "centrey" in the original image. The variable MAXIMERROR is set to "true" if an error occurs.

combinefiles

Syntax: combinefiles input_files outfile.fit 0-7 trigger_sd calibrate_flag align_flag default_align_mode backup_align_mode kernel_filter_flag fft_filter_flag <quality_check_flag fwhm_limit flatness_limit background_limit>

This command combines groups of image files specified as "input_files" formatted by either:

All image files matching the wildcard specification "filemask*.fit" - if not fully-qualified, the variable IMAGEDIRECTORY is pre-pended.
All image files listed one per line in the plain text file "file.txt" - if not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. The image files listed in the plain text file must be fully-qualified. The extension for the file specified must end in ".txt".

The combined file is saved as "outfile.fit" - if is not fully-qualified, the variable IMAGEDIRECTORY is pre-pended.

The third parameter specifies the combine type (0 to 7). For all except combine type 5, "trigger_sd" should be 0. The combine types are:

0=sum
1=average
2=median
3=sigma clip
4=sdmask
5=Lane-Majaess (LM) clip. The Lane-Majaess (LM) clip algorithm requires the parameter "trigger_sd". LM-clip works by not including pixels in the combined image that deviate more than "triggersd" times the standard deviation from the mean. In particular the standard deviation (SD) and mean are computed for each pixel position using all the images to be combined. The pixel that deviates the most from the mean and is at least "triggersd" times the standard deviation from the mean is marked as "rejected". A new mean and SD is computed from the remaining non-rejected pixels and the same reject algorithm is repeated. The process repeats up to a total of 5 times, but no more than 30% or a maximum of 5 pixels in total per pixel position are ever "rejected". Finally the remaining pixels in each pixel position are averaged to form the final combined image.
6=LM average
7=LM median

Combine types 0-4 are implemented by MaxIm DL and the remaining 3 are done internally be ARAP.

Before the images are combined, they are:

optionally calibrated (if "calibrate_flag" is "true")
kernel filtered (if "kernel_filter_flag" is "true")
fft filtered (if "fft_filter_flag" is "true")
aligned (if "align_flag" is "true") using a primary (default_align_mode) mode and if that fails, a backup (backup_align_mode) mode. The supported modes (as provided by MaxIM DL) are:

-1 : no alignment
0 : autocorrelation
1 : automatic matching of star brightnesses and separations
3 : WCS information in the FITS header
4 : aligns centroids of the principal disk found in each image (planetary mode)
5 : aligns centroids of the brightest star found in each image

If "quality_check_flag" is true, the stars in each image are measured using the getstarinfo command. The average of measured FWHMs and Flatness are computed. If the stars in each image are "fwhm_limit" (in percent, up to 300) larger than the average size, if the flatness is more than the average flatness plus "flatness_limit" (0 to 2), or if the "background_limit" (in percent, up to 300) is larger than the median background, the image is not included in the combined image. This parameter is ignored if there are fewer than three images to combine or if not enough stars are found in the images.

Several FITS header keys are updated by the combine operation to correctly reflect the properties of the new image (in addition to those updated by MaxIm DL): JD-MID, HJD-MID, DATE-OBS, DATE-MID, DATE-END, and TOTALEXP (total exposure time is the sum of all individual EXPTIME/SNAPSHOT values). If more than one filter is detected, FILTER is changed to "MULTIPLE". Care needs to be taken when interpreting the Julian date and Date headers when combining previously combined images.

If any error is detected the variable MAXIMERROR is set to "true".

combinecolour

Syntax: combinecolour lfile.fit rfile.fit gfile.fit bfile.fit outfile.fit alignflag autobge <lweight colourspace>

This command combines either four LRGB or three RGB image files into the colour RGB FITS file "outfile.fit". If any of the filenames provided are not fully-qualified, the variable IMAGEDIRECTORY is pre-pended.

Before the images are combined, they are optionally aligned (if "align_flag" is "true") using MaxIm DL’s star-matching (preferred), auto-correlation (if star matching fails), or brightest star (if both star matching and auto-correlation fails) algorithm. If "autobge" is true, each colour is auto-background equalized.

Luminance, Red, Green, Blue Mode:

If "lfile.fit" is specified, Luminance, Red, Green, Blue mode is active:

lfile.fit - the luminance channel FITS file
rfile.fit - the red channel FITS file
gfile.fit - the green channel FITS file
bfile.fit - the blue channel FITS file
lweight - sets the weight applied to the luminance data (0-100%)
colourspace - sets the color space used: 0 : CIE 1976 L*a*b*, also known as CIELAB, 1 : normalized RGB vector scaled by Luminance, and 2 : HSL (Hue, Saturation, Lightness)

If "lfile.fit" is not specified, Red, Green, Blue mode is active:

rfile.fit - the red channel FITS file
gfile.fit - the green channel FITS file
bfile.fit - the blue channel FITS file
lweight and colourspace are not used

Several FITS header keys are updated by the combine operation to correctly reflect the properties of the new image (in addition to those updated by MaxIm DL): JD-MID, HJD-MID, DATE-OBS, DATE-MID, DATE-END, TOTALEXP (total exposure time is the sum of all individual EXPTIME values), FILTER (the list of filters used to assemble the image).

If any error is detected the variable MAXIMERROR is set to "true".

colourbalance

Syntax: colourbalance rscaling gscaling bscaling

This command balances the colour of an RGB colour image that has been loaded using the loadimagefile command. Each colour channel ("rscaling" is red, "gscaling" is green, "bscaling" is blue) is scaled by the specified value in percent (1 to 500 percent). The variable MAXIMERROR is set to "true" if an error occurs.

coloursaturation

Syntax: coloursaturation saturation

This command adjusts the colour "saturation" (in percent) of an RGB colour image that has been loaded using the loadimagefile command. A saturation value of 100 leaves the saturation as it is, higher numbers, up to 1000, increases it, and a value of 0 effectively turns the image into monochrome. The variable MAXIMERROR is set to "true" if an error occurs.

solveplate

Syntax: solveplate filename.fit rings <ra> <dec>

This command attempts to astrometrically solve the image "filename.fit" using the PinPoint astrometric engine. If not fully-qualified, the variable IMAGEDIRECTORY is pre-pended to "filename.fit". The initial position is as specified in the FITS header or the optional right ascension ("ra") and declination ("dec") parameters and it searches in a spiral pattern for the specified number of "rings" around the initial position. The many PP... variables control the parameters used during the search and whether the solution is valid. If less than PPMINUMUMSTARCOUNT stars are found in the image, the solve is not attempted - PPERRORNUMBER is set to 1 if not enough stars are found or 2 if no stars are found.

If the solve is successful, the WCS FITs header keys are added to the image. If the solving time exceeds PPTIMEOUT seconds, the maximum catalog magnitude in decreased by one magnitude and the "Sigma Above Mean" parameter is increased by a factor of 1.5 to reduce the number of stars and hopefully the complexity of the field. This is done until either the maximum catalog magnitude 12 or the number of image stars become less than PPMINUMUMSTARCOUNT.

A log file named the same as "filename.fit" but with the extension ".log" is created with the centre position on the first line, the error number on the second line (0=successful) and the error message on the third line.

The variables STARCOUNT, PINPOINTERROR, PPERRORNUMBER, and PPERRORMESSAGE are set accordingly. PPERRORNUMBER and PPERRORMESSAGE are as reported by the PinPoint engine, except it is set to:

1 if not enough stars are found
2 if no stars are found
3 if the PinPoint engine cannot be started
4 if the operation was aborted by the user or automation
5 if the roll angle is too high
6 if the image scale is out of tolerance

batchsolveplate

Syntax: batchsolveplate filemask*.fit rings

This command attempts to astrometrically solve a batch of images that match "filemask*.fit". If the filemask specified is not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. The initial position is as specified in the FITS header of each image. In all other respects, this command behaves the same as the solveplate command.

solveplateallsky

Syntax: solveplateallsky filename.fit <upload image>

This command attempts to astrometrically blind plate-solve the image "filename.fit" using the PinPoint astrometric engine and its interface to astronometry.net. If not fully-qualified, the variable IMAGEDIRECTORY is pre-pended to "filename.fit".

No initial position is required, however a working internet connection is needed. Blind plate-solving is allowed to work for up to 10 minutes before it times out. If "upload_image" is true, the FITS image is uploaded to the blind solver, otherwise PinPoint identifies the stars found on the image and a list of stars instead. If the blind solver succeeds in finding the field center and image scale, a secondary plate-solve is done using PinPoint's internal solver. This secondary plate-solve is allowed to run for PPTIMEOUT seconds.

If less than PPMINUMUMSTARCOUNT stars are found in the image, the solve is not attempted.

The many PP... variables control the parameters used during the secondary plate-solve and whether or not the solution is valid. If the solve is successful, the WCS FITs header keys are added to the image. The variables PINPOINTERROR, PPERRORNUMBER, and PPERRORMESSAGE are set. PPERRORNUMBER and PPERRORMESSAGE are as reported by the PinPoint engine, except it is set to:

1 if not enough stars are found
2 if no stars are found
3 if the PinPoint engine cannot be started
5 if the roll angle is too high
6 if the image scale is out of tolerance

radectoxy

Syntax: radectoxy filename.fit

This command locates the pixel position within the specified image corresponding to the right ascension and declination specified in the variables RA and DEC. Due to PinPoint limitations, the image must be in 16-bit FITS format. If the filename specified is not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. The image must have been previously plate-solved – see the solveplate command. If successful, the variables XPOSITION and YPOSITION are set to the corresponding fractional pixel location. The variable PINPOINTERROR is set to "true" if an error occurs or if the position provided corresponds to a position outside of the specified image.

xytoradec

Syntax: xytoradec filename.fit

This command calculates, within the specified image, the right ascension and declination corresponding to the X and Y pixel positions (integer or floating point) specified in the variables XPOSITION and YPOSITION. Due to PinPoint limitations, the image must be in 16-bit FITS format. If the filename specified is not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. The image must have been previously plate-solved – see the solveplate command. If successful, the variables RA and DEC are set. The variable PINPOINTERROR is set to "true" if an error occurs or if the position provided is not within the bounds of the image.

photometry

Syntax: photometry x y refsnr <autoaperture_flag> <centroid_flag>

This command performs aperture photometry on the image loaded by the loadimagefile command at either the pixel location specified or at a "centroided" location within the aperture if the optional centroid_flag is "true". 'refsnr' should be set to the S/N ratio of the reference star, if known - this is used to estimate set the PHOTOERR variable. The x and y parameters are rounded to the nearest pixel before being used. The variables PHOTOAPERTURE, PHOTOGAP, and PHOTOANNULUS are used to specify the aperture and background annulus parameters. If the optional autoaperture_flag is omitted or false these parameters are used for the measurements, however if autoaperture_flag is "true" these are the initial parameters used to first measure the star’s full-width half maximum (FWHM) and then set the aperture automatically set to its measured FWHM times the value in the PHOTOAPERTURERATIO variable. The gap between the aperture and the background annulus is also automatically adjusted so that the background annulus remains the same distance from the centre of the aperture as originally specified. If successful, all of the read-only PHOTO… variables are updated (see the Pre-Defined Variables). The variable MAXIMERROR is set to "true" if an error occurs.

photometrybox

Syntax: photometrybox x y refsnr box_half_size skyx skyy

This command performs "box" photometry on the image loaded by the loadimagefile command at the x and y pixel location specified (rounded to the nearest pixel). The size of the box used is two times "box_half_size" plus one. The sky background location is set by skyx and skyy. "refsnr" should be set to the S/N ratio of the reference star, if not <0 it is used to estimate the S/N set the PHOTOSNR variable. If successful, all of the relevant read-only PHOTO* variables are updated except PHOTOERR (see the Pre-Defined Variables). The variable MAXIMERROR is set to "true" if an error occurs.

areainfo

Syntax: areainfo
Syntax: areainfo x1 y1 x2 y2

This command calculates various statistics on the image loaded by the loadimagefile command. If there are no parameters, then the whole image is used, otherwise the rectangle specified by the parameters (in pixel coordinates) is used. The AREAMAX, AREAMIN, AREAAVERAGE, and AREASD variables are set. The variable MAXIMERROR is set to "true" if an error occurs.

getstarinfo

Syntax: getstarinfo filename.fit <aperture> <minfwhm> <savefwhm> <calibrate_flag>

This command measures the size, flatness (roundness), and sky background of stars in the image "filename.fit" which must be fully-qualified. It uses PinPoint to find the number of stars and stores this value in variable STARCOUNT. It removes saturated and stars within 10% of the field edge. It stores the number of saturated stars (pixel values > 60,000) in variable STARSATURATEDCOUNT. It then sorts by the total flux of each star and measures the FWHM, flatness, and sky background (using Maxim DL) of the up to 20 (minimum of 10) brightest stars and reports the median values in the variables STARFWHM, STARFLATNESS, and STARBACKGROUND. STARBRIGHTESTPIXEL is set to the highest pixel value from the up to 20 non-saturated and non-edge brightest stars.

If "aperture" or minfwhm" are specified, these values is used for the measurement's aperture radius (the default is 7 pixels) and stars smaller that the specified "minfwhm" are skipped (the default is 1.5 pixels). If "savefwhm" is true, the measured FWHM, flatness, and background are saved to the image's FWHM, FLATNESS, and BACKGRND header keys. If "calibrate_flag" is true, the images are calibrated before the stars are measured - note that this does not affect the star finding step done by PinPoint. When a major error occurs, the variable PINPOINTERROR is set to "true", otherwise variable STARFWHM is set to -1.

getfitsheader

Syntax: getfitsheader variable_name key STRING|INTEGER|BOOLEAN|REAL <digits>

This command retrieves the specified fits header "key" from either the just-exposed CCD image or an image that has been loaded using the loadimagefile command and stores it in the variable "variable_name". The data type must be specified as one of the standard fits header types (STRING, INTEGER, BOOLEAN, or REAL). If "REAL" type is selected the number of digits must also be specified (up to 10). If the "key" does not exist, the result will be a null string for a STRING type, a value of 0 for INTEGER or REAL types, and "FALSE" for a boolean type.

The variable MAXIMERROR is set to "true" if an error occurs from an image loaded by loadimagefile, otherwise CCDERROR is set to "true" if an error occurs from a just-exposed image.

putfitsheader

Syntax: putfitsheader value key STRING|INTEGER|BOOLEAN|REAL

This command sets the specified fits header ‘key’ of either the just-exposed CCD image or an image that has been loaded using the loadimagefile command to "value". The data type must be specified as one of the standard fits header types (STRING, INTEGER, BOOLEAN, or REAL). The variable MAXIMERROR is set to "true" if an error occurs from an image loaded by loadimagefile, otherwise CCDERROR is set to "true" if an error occurs from a just-exposed image. Note that MaxIm DL seems to have a bug that does not allow it to set a BOOLEAN value to a key that already exists.

convertfitstojpeg

Syntax: convertfitstojpeg infile outfile min max base quality rotateflg negativeflg <arcsinhflg> <arcsinh_power>

This command reads a monochromatic or colour fits image file ("infile"), stretches it to an 8-bit gray-scale of colour image, and saves it to a jpeg image file ("outfile"). If either filename is not fully-qualified, the value of variable IMAGEDIRECTORY is pre-pended. Text and/or images can also be drawn. PinPoint software is required for this command. The variable PINPOINTERROR is set to "true" if an error occurs.

If the "rotateflg" parameter is "true", the image is rotated 180 degrees.

If the "negativeflg" parameter is "true", the output is a negative image.

The "quality" parameter is the jpeg compression quality (1 to 100 - higher means better quality but also produces a larger file size).

In order to stretch the image, a histogram is calculated using a 90% cropped image of every other pixel in x and y with values of 0 and 65535 ignored. For colour images, the maximum pixel value in red, green, and blue channels is used. Then the parameters "min" (minimum) and "max" (maximum) are used to set the black and white levels of the image (see description below).

Two types of stretches are supported, linear and arcsinh (if the "arcsinhflg" is "true"). The "arcsinh_power" parameter sets the relative arcsinh stretch factor (from 0.01 to 10). A value of 5 works well for many astronomical objects.

The "min" parameter operates as follows:

min>=0: the percentage of the pixels of the histogram that becomes black
min=-1: means black becomes the median of the pixel values
min=-2: means black becomes 1/4 from the bottom of the sorted pixel values
min=-3: means black becomes 1/8 from the bottom of the sorted pixel values
min=-4: means black becomes 1/16 from the bottom of the sorted pixel values
min=-5: means black becomes 1/32 from the bottom of the sorted pixel values
min=-6: means black becomes 1/64 from the bottom of the sorted pixel values

The "max" parameter is the percentage of the pixels of the histogram that becomes white.

The "base" parameter sets the black level within the 8-bit output image, which is usually set to about 10-20.

If a text file exists in the same directory as "infile" but with this extension "txt", it is used to add text and/or images. The lines in the text file need to be tab-delimited and contain 7 fields for text or 5 fields for images. In both cases the first four fields are:

X reference: "left", "centre", or "right" (eg. left is the left edge of image)
X position: pixel position relative to X reference
Y reference: "top", "centre", or "bottom" (eg. bottom is the bottom edge of image)
Y position: pixel position relative to Y reference

For drawing text, the remaining fields are:

The font size (in pixels)
The font type face name
The text drawn

For drawing images, the remaining field is:

The filename of the bitmap (full-qualified). Only Windows BMP format is supported
The scaling in percent (integer only) of the bitmap.

An example file is below:

centre 0 top 5 32 Times New Roman Burke-Gaffney Observatory

centre 5 top 50 24 Times New Roman Saint Mary's University

centre 5 top 85 18 Arial www.ap.smu.ca/bgo

left 5 bottom 5 20 Arial Imaged for @abbeyridgeobs

right 5 bottom 5 20 Arial NGC7735 in OIII filter

left 5 top 5 c:\ARAPOutput\cdk.bmp 100

right 5 top 5 c:\ARAPOutput\bgo.bmp 100

findimagestars

Syntax: findimagestars filename.fit <aperture_radius> <min_snr>

This command use PinPoint and MaxIm DL to find stars in the specified image "filename.fit". If the specified filename is not fully-qualified, the value of variable IMAGEDIRECTORY is pre-pended.

Saturated and stars within 5% of the image edges are removed and then sorted by the total flux. The list of stars found are measured and saved to a text file, one star per line, with the same filename as the input image but with the extension 'txt'. The variable STARCOUNT is set to the number of stars found.

The aperture used in the star's measurement can be specified by the "aperture_radius" otherwise the default value of 7 is used (a gap of 2 and annulus size of 5 are always used). The minimum signal to noise ratio to use can be specified by the "min_snr" parameter, otherwise the default value of 5 is used.

The format of each line of the text file is:

X,Y,FLUX,MAG,FLUX,SNR,FWHM,FLATNESS

where

X and Y is the star's position in pixels
FLUX is the total flux above the sky background
MAG is the differential magnitude of the star using the values of variables PHOTOREFMAG and PHOTOREFINTENSITY (-1 if FLAX is 0)
SNR is the signal to noise ratio between the star's flux and the sky background
FWHM is the full width half max in pixels. This value is set to -1 if the star did not meet the minimum signal to noise ratio limit.
FLATNESS is a measure of the star's roundness (0 is round)

The variable PINPOINTERROR is set to "true" if an error occurs.