ARAP scripts are written in plain-text and as such can be created/edited in the Windows Notepad program. Here are the basic syntax rules and other info:
There are many commands covering a wide variety of simple and complex tasks used for automating the operation of an astronomical telescope, ccd camera, and observatory. In the command syntaxes below, a parameter surrounded by less-than and greater-than characters "<>" is optional.
The available commands are divided into several categories: Telescope Commands, Dome Commands, CCD Camera Commands, Compound Telescope and CCD Commands, Image Processing Commands, File and Internet Commands, Database Commands, X10 Controller Commands, Cloud Sensor Commands, Calculation Commands, Miscellaneous Commands, Flow Control Commands, and Variables and Variable Commands.
telescopesetup
Syntax: telescopesetup
Description: This command displays the ASCOM telescope setup dialog box. From this dialog box, the user can select a specific ASCOM telescope driver and set its parameters. The selected driver is saved to the TELESCOPE variable and becomes the active telescope used by ARAP.
telescopeon
Syntax: telescopeon
Description: This command initiates communication with the telescope. If this operation is successful, the variable TELESCOPECONNECTED is set to "true", otherwise a fatal error is generated and the script aborts. After the telescope is connected the variable EPOCH is set. All commands that require communication with the telescope must be preceded by this command.
telescopeoff
Syntax: telescopeoff
Description: This command terminates communication with the ASCOM telescope and sets the variable TELESCOPECONNECTED to "false".
park
Syntax: park
Description: This command, depending on the telescope's capability or driver settings, moves the telescope to its predetermined park position and stops the right ascension drive. The variable TELESCOPEERROR is set accordingly. Note that some telescope models stop communicating after this command is issued and requiring them to be powered off and on before they will respond.
unpark
Syntax: unpark
Description: This command, assuming the telescope is so capable, unparks the telescope and may start the right ascension drive depending on the telescope model. Note that some telescope models don't actually start their drive until after the first "goto" operation or until the 'trackingon' command is issued. The variable TELESCOPEERROR is set accordingly.
setpark
Syntax: setpark
Description: This command, assuming the telescope is so capable, sets the telescope position for subsequent "park" commands. The variable TELESCOPEERROR is set accordingly.
trackingon
Syntax: trackingon
Description: This command, assuming the telescope is so capable, starts the right ascension drive. The variable TELESCOPEERROR is set accordingly.
trackingoff
Syntax: trackingoff
Description: This command, assuming the telescope is so capable, stops the right ascension drive. The variable TELESCOPEERROR is set accordingly.
goto
Syntax: goto objectname <delay>
Description: This command searches the object databases for "objectname", enables tracking, and moves the telescope there. The telescope can be moved to a specific position by using the format "#RA,DEC". The optional "delay" parameter causes a delay (in integer seconds) after the telescope has been moved. The variables RA, DEC, TELESCOPEERROR and FINDERROR are set accordingly. The telescope is given a maximum of five minutes to complete its slewing.
gotoasync
Syntax: gotoasync objectname
Description: This command searches the object databases for "objectname", enables tracking, and starts moving the telescope there. The telescope can be moved to a specific position by using the format "#RA,DEC". The variables RA, DEC, TELESCOPEERROR and FINDERROR are set accordingly.
gotoradec
Syntax: gotoradec <delay>
Description: This command enables tracking and moves the telescope to the position specified by the RA and DEC variables. The optional "delay" parameter causes a delay (in integer seconds) after the telescope has been moved. The variable TELESCOPEERROR is set accordingly. The telescope is given a maximum of five minutes to complete its slewing.
gotoradecasync
Syntax: gotoradecasync
Description: This command enables tracking and starts moving the telescope to the position specified by the RA and DEC variables. The variables TELESCOPEERROR and FINDERROR are set accordingly.
gotowait
Syntax: gotowait <delay>
Description: This command waits for the completion of a prior gotoasync or gotoradecasync command. The optional "delay" parameter causes a delay (in integer seconds) after the telescope has been moved. The variable TELESCOPEERROR is set accordingly. The telescope is given a maximum of five minutes to complete its slewing.
sync
Syntax: sync objectname
Description: This command searches the object databases for "objectname" and then synchronizes the telescope's position. The telescope can be synced to a specified position by using the format "#RA,DEC". The variables TELESCOPEERROR and FINDERROR are set accordingly.
syncradec
Syntax: syncradec
Description: This command synchronizes the telescope's position to the . The telescope can be synced to a specified by the RA and DEC variables. The variable TELESCOPEERROR is set accordingly.
getradec
Syntax: getradec
Description: This command queries the current position of the
telescope and sets the variables RA and DEC. The variable TELESCOPEERROR is set
accordingly.
getsideofpier
Syntax: getsideofpier
Description: This command queries the telescope and sets the variable SIDEOFPIER to either true for west or false for east. This command is generally only relevant for German Equatorially mounted telescopes and you must be using a V2 ASCOM driver. The variable TELESCOPEERROR is set accordingly.
nativecommand
Syntax: nativecommand blind flag command
Description: This command sends a native “command” (a command string in the native language of the telescope) to the telescope. If “blind” is true, the command is sent, but a response is not expected or received from the telescope. If “blind” is false, the command is sent and the result is stored in the NATIVERESULT variable. If “flag” is true, the result is expected to be a boolean (set to TRUE or FALSE) otherwise it is expected to be a string. The variable TELESCOPEERROR is set accordingly.
domesetup
Syntax: domesetup
Description: This command displays the ASCOM dome setup dialog box. From this dialog box, the user can select a specific ASCOM dome driver and set its parameters. The selected driver is saved to the DOME variable and becomes the active observatory dome used by ARAP.
domeon
Syntax: domeon
Description: This command initiates communication with the observatory dome. If this operation is successful, the variable DOMECONNECTED is set to "true", otherwise a fatal error is generated and the script aborts. All commands that require communication with the observatory dome must be preceded by this command.
domeoff
Syntax: domeoff
Description: This command terminates communication with the observatory dome and sets the variable DOMECONNECTED to "false".
domeopen
Syntax: domeopen
Description: This command opens the observatory dome shutter. The variable DOMEERROR is set accordingly.
domeclose
Syntax: domeclose
Description: This command opens the observatory dome shutter. The variable DOMEERROR is set accordingly.
domepark
Syntax: domepark
Description: This command rotates the dome to an azimuth set by the driver to be the "park" position. This is usually the azimuth the owner prefers to dome to be rotated to when its not-in-use. The variable DOMEERROR is set accordingly.
domefindhome
Syntax: domefindhome
Description: This command causes the dome driver to reinitialize its azimuth sensor. This may or may not actually rotate the dome. The variable DOMEERROR is set accordingly.
domeazimuth
Syntax: domeazimuth azimuth
Description: This command causes the dome to rotate to the specified "azimuth" (in integer degrees clockwise from true north). The variable DOMEERROR is set accordingly.
domeslavedon
Syntax: domeslavedon
Description: This command causes the dome's azimuth to begin following ("slaved") the telescope's current position. The variable DOMEERROR is set accordingly.
domeslavedoff
Syntax: domeslavedoff
Description: This command causes the dome's azimuth to stop following ("slaved") the telescope's current position. The variable DOMEERROR is set accordingly.
getdomestatus
Syntax: getdomestatus
Description: This command queries the dome driver’s shutter status and sets the variable DOMESTATUS accordingly. The variable DOMEERROR is set accordingly.
focusersetup
Syntax: focusersetup
Description: This command displays the ASCOM focuser setup dialog box. From this dialog box, the user can select a specific ASCOM focuser driver and set its parameters. The selected driver is saved to the FOCUSER variable and becomes the active focuser used by ARAP.
focuseron
Syntax: focuseron
Description: This command initiates communication with the focuser. If this operation is successful, the variable FOCUSERCONNECTED is set to "true", otherwise a fatal error is generated and the script aborts. All commands that require communication with the focuser must be preceded by this command.
focuseroff
Syntax: focuseroff
Description: This command terminates communication with the focuser and sets the variable FOCUSERCONNECTED to "false".
focuserposition
Syntax: focuserposition position
Description: This command causes absolute-type focusers to move to the absolute "position" (an integer between 0 and the value of the variable FOCUSERMAXSTEP). For relative-type focusers, “position” is a positive or negative number (between 0 and the variable FOCUSERMAXINCREMENT) which causes the focuser to move an amount relative to its current position. The variable FOCUSERERROR is set accordingly.
focusertcon
Syntax: focusertcon
Description: This command enables the focuser’s temperature compensation mode. The variable FOCUSERERROR is set accordingly.
focusertcoff
Syntax: focusertcoff
Description: This command disables the focuser’s temperature compensation mode. The variable FOCUSERERROR is set accordingly.
getfocuserstatus
Syntax: getfocuserstatus
Description: This command queries the focuser driver and updates all of the FOCUSER… variables. The variable FOCUSERERROR is set accordingly.
ccdon
Syntax: ccdon
Description: This command initiates communication with the MaxIm DL/CCD software and connects to the CCD camera. It also sets the frame size to a full frame at the binning defined in the variable CCDBINNING and sets then sets the values of the variables CCDLEFT, CCDTOP, CCDWITTH, and CCDHEIGHT. If this operation is successful, the variable CCDCONNECTED is set to "true", otherwise a fatal error is generated and the script aborts. All commands that require communication with the MaxIm DL must be preceded by this command.
ccdoff
Syntax: ccdoff
Description: This command terminates communication with the MaxIm DL/CCD software and sets the variable CCDCONNECTED to "false".
cooleron
Syntax: cooleron
Description: This command turns on the CCD camera's chip cooler. The variable CCDERROR is set accordingly.
cooleroff
Syntax: cooleroff
Description: This command turns off the CCD camera's chip cooler. The variable CCDERROR is set accordingly.
setcooler
Syntax: setcooler DegC
Description: This command sets the regulation temperature of the CCD camera's chip cooler to "DegC" (degrees Celsius). The variable CCDERROR is set accordingly.
coolerwait
Syntax: coolerwait DegC <timeout>
Description: This command sets the regulation temperature of the CCD camera's chip cooler to "DegC" (degrees Celsius) and waits until the temperature is within 0.5 degrees of the specified temperature. ARAP will wait a maximum of either 10 minutes or the optionally specified "timeout" value (in integer seconds to a maximum of 3600 seconds). The variable CCDERROR is set accordingly.
setcalibration
Syntax: setcalibration bias.fit dark.fit flat.fit
Description: This command sets the image files used by MaxIm DL when performing image calibrations. All three types (bias, dark and flat) of image files must be specified. The files must include their full filenames including the drive and directory. Filenames can contain wildcard character (* or ?) to specify more than one file. Remember to include these filenames in double quotes if they contain spaces. The variables CCDERROR and CCDCALIBRATIONERROR are set accordingly. It is appropriate to use this command prior to using the “calibrate” and “calibratefile” commands.
calibrate
Syntax: calibrate
Description: 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.
kernelfilter
Syntax: kernelfilter
Description: 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 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.
light
Syntax: light exptime <objectname>
Description: This command takes a normal CCD image, but does not save the image (see the "save" command). The exposure time is "exptime" seconds long (up to 3600 seconds - fractional seconds are ok). The variable FILTERINDEX specifies the optical filter to be used. If the optional "objectname" parameter is included, it is added to the FITS header in the "OBJECT" key. If the telescope is connected, its current right ascension and declination are added to the FITS header in the "OBJCTRA" and "OBJCTDEC" keys. Other keys added to the FITS header if the telescope is connected are: “AIRMASS”, “ALTITUDE”, “AZIMUTH”, “SITELAT”, and “SITELONG”. If the variable CALIBRATIONENABLED is true, the image is automatically calibrated - see the "calibrate" command. If the variable KERNELFILTERENABLED is true, the image is automatically kernel filtered - see the "kernelfilter" command. The image is also automatically flipped left-right and/or top-bottom based on the state of the FLIPX and FLIPY variables. The variable CCDERROR is set accordingly.
lightstart
Syntax: lightstart exptime
Description: This command starts a normal CCD image and returns program control to the script. It is used in conjunction with the "lightwait" and "lightfinish" commands to provide the same functionality as the "light" command, but in three steps instead.
lightwait
Syntax: lightwait exptime
Description: This command waits for the CCD image that is already being exposed to complete and be downloaded. If the telescope is connected, its current right ascension and declination are added to the FITS header in the "OBJCTRA" and "OBJCTDEC" keys. Other keys added to the FITS header if the telescope is connected are: “AIRMASS”, “ALTITUDE”, “AZIMUTH”, “SITELAT”, and “SITELONG”. This command must follow a "lightstart" command. It is used in conjunction with the "lightstart" and "lightfinish" commands to provide the same functionality as the "light" command, but in three steps instead.
lightfinish
Syntax: lightfinish <objectname>
Description: This command must follow a "lightstart" and "lightwait" command to provide the same functionality as the "light" command, but in three steps instead. The "lightfinish" command does the auto image calibration, auto kernal filtering and auto image flip functions. If the optional "objectname" parameter is included, it is added to the FITS header in the "OBJECT" key.
lights
Syntax: lights n exptime objectname <delay>
Description: This command takes a sequence of "n" normal CCD images. Image files are saved in the directory specified by the IMAGE DIRECTORY variable. The filename used is "objectname-XXXX.fit" where "XXXX" is an auto-incrementing image counter. The current value of the image counter is in the variable IMAGECOUNTER. If the optional "delay" parameter is included, there will be a time delay of up to 3600 seconds (in integers) after each exposure. In all other respects, this command is the same as the "light" command.
flat
Syntax: flat exptime
Description: This command takes a "flat" calibration image, but does not save the image (see the "save" command). The exposure time is "exptime" seconds long (up to 3600 seconds - fractional seconds are ok). The variable FILTERINDEX specifies the optical filter to be used. The word "flat" is added to the FITS header in the "OBJECT" key. The variable CCDERROR is set accordingly.
flats
Syntax: flats n exptime
Description: This command takes a sequence of "flat" calibration images. Image files are saved in the directory specified by the IMAGE DIRECTORY variable. The filename used is "flat-XXXX.fit" where "XXXX" is an auto-incrementing image counter. The current value of the image counter is in the variable IMAGECOUNTER. In all other respects, this command is the same as the "flat" command.
bias
Syntax: bias
Description: This command takes a "bias" calibration image, but does not save the image (see the "save" command). The word "bias" is added to the FITS header in the "OBJECT" key. The variable CCDERROR is set accordingly.
biases
Syntax: biases n
Description: This command takes a sequence of "bias" calibration images. Image files are saved in the directory specified by the IMAGE DIRECTORY variable. The filename used is "bias-XXXX.fit" where "XXXX" is an auto-incrementing image counter. The current value of the image counter is in the variable IMAGECOUNTER. In all other respects, this command is the same as the "bias" command.
dark
Syntax: dark exptime
Description: This command takes a "dark" calibration image, but does not save the image (see the "save" command). The exposure time is "exptime" seconds long (up to 3600 seconds - fractional seconds are ok). The word "dark" is added to the FITS header in the "OBJECT" key. The variable CCDERROR is set accordingly.
darks
Syntax: darks n exptime
Description: This command takes a sequence of "dark" calibration images. Image files are saved in the directory specified by the IMAGEDIRECTORY variable. The filename used is "dark-XXXX.fit" where "XXXX" is an auto-incrementing image counter. The current value of the image counter is in the variable IMAGECOUNTER. In all other respects, this command is the same as the "dark" command.
save
Syntax: save objectname
Description: This command saves the just-exposed CCD image (in 16-bit FITS format) in the directory specified by the IMAGEDIRECTORY variable. The filename used is "objectname-XXXX.fit" where "XXXX" is an optional (controlled by the IMAGECOUNTERENABLED variable) auto-incrementing image counter (from the IMAGECOUNTER variable). The variable CCDERROR is set accordingly.
autofocus
Syntax: autofocus exptime <halfflux>
Description: This command autofocuses, using the facilities of FocusMax, the telescope with an exposure of "exptime". It is assumed that FocusMax has been configured and calibrated, that the ASCOM focuser have been previously setup, and that the telescope is pointed at a suitable star. If the optional "halfflux" parameter is specified (in pixels up to 20), the focus procedure is skipped if the star is already smaller than the value specified. The variable FOCUSERROR is set accordingly.
gotolightsave
Syntax: gotolightsave exptime objectname <delay>
Description: This command searches the object databases for "objectname", moves the telescope there, takes a normal CCD image, and saves the image. The telescope can be moved to a specific position by using the format "#RA,DEC". The exposure is "exptime" seconds long (up to 3600 seconds - fractional seconds are ok). The variable FILTERINDEX specifies the optical filter to be used. The image is saved in the directory specified by the IMAGEDIRECTORY variable with a filename of "objectname-XXXX.fit", where "XXXX" is an optional (controlled by the IMAGECOUNTERENABLED variable) auto-incrementing image counter (from the IMAGECOUNTER variable). The optional "delay" parameter causes a delay (in integer seconds) after the telescope has been moved. The variables CCDERROR and TELESCOPEERROR are set accordingly.
solveandsync
Syntax: solveandsync exptime rings <dosync> <SETAUTOFLIP>
Description: This command takes a normal CCD image, astrometrically solves the image (see the "solveplate" command for details), and if successful it synchronizes the telescope to the solved position if "dosync" is true. The exposure is "exptime" seconds long (up to 3600 seconds - fractional seconds are ok). The variable FILTERINDEX specifies the optical filter to be used. If the optional "SETAUTOFLIP" text is present, the variables FLIPX and FLIPY are updated. The current telescope position is used as the initial position. The image is saved as "pinpoint.fit" in the directory specified by the IMAGEDIRECTORY variable. The variable POSITIONERROR is set to the difference, in arc-minutes, between the initial and synced telescope position (-1 if an error occurs). The variable PINPOINTERROR is set accordingly.
autocentre
Syntax: autocentre minimum or autocenter minimum
Description: This command finds the brightest star in the just-exposed CCD image. If it is brighter than "minimum" counts, the telescope is moved to position the star in the center of the field. It is assumed that north is up in the image and the variables PIXELSIZEX and PIXELSIZEY are set correctly. The variable TELESCOPEERROR is set accordingly.
autosync
Syntax: autosync objectname exptime minimum <delay>
Description: This command searches the object databases for "objectname", moves the telescope there, takes a normal CCD image, and finds the brightest star in the image If it is brighter than "minimum" counts, the telescope is moved to position the star in the center of the field and the telescope is synchronized on the "objectname". The exposure is "exptime" seconds long (up to 3600 seconds - fractional seconds are ok). The variable FILTERINDEX specifies the optical filter to be used. The optional "delay" parameter causes a delay (in integer seconds) after the telescope has been moved. It is assumed that north is up in the image and the variables PIXELSIZEX and PIXELSIZEY are set correctly. The variables CCDERROR and TELESCOPEERROR are set accordingly.
batch
Syntax: batch filename.obj exptime <delay>
Description: This command takens normal CCD images of a batch of objects whose names are in the text file "filename.obj". The format of the file is the same as object list files used in ECU Pro. The exposure is "exptime" seconds long (up to 3600 seconds - fractional seconds are ok). The variable FILTERINDEX specifies the optical filter to be used. The image is saved in the directory specified by the IMAGEDIRECTORY variable with a filename of "objectname-XXXX.fit", where "XXXX" is an optional (controlled by the IMAGECOUNTERENABLED variable) auto-incrementing image counter (from the IMAGECOUNTER variable). The optional "delay" parameter causes a delay (in integer seconds) after the telescope has been moved.
Image
Processing Commands
maximon
Syntax: maximon
Description: This command initiates communication with MaxIm DL and is to be used before all image processing commands in this section, but is not necessary when using the CCD 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
Description: This command terminates communication with MaxIm DL and sets the variable MAXIMCONNECTED to "false".
savecalibration
Syntax: savecalibration bias.fit dark.fit flat.fit
Description: 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
Description: This command loads into memory the image file “file.fit” so that it can be accessed by other commands such as “calibrate” or “photometry”. 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. The variable MAXIMERROR is set accordingly.
saveimagefile
Syntax: saveimagefile file.fit
Description: This command saves and closes the image file loaded by the “loadimagefile” command to the file “file.fit” in 16-bit FITS format. If the filename specified is not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. The variable MAXIMERROR is set accordingly.
closeimagefile
Syntax: closeimagefile
Description: This command closes the image file loaded by the “loadimagefile” command without saving it. The variable MAXIMERROR is set accordingly.
calibratefile
Syntax: calibratefile infile.fit <outfile.fit>
Description: This command calibrates the file “infile.fit” and saves the calibrated image either back to the same file or to the optionally specified “outfile.fit”. It must be done after a “setcalibration” command. If the filenames specified are not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. The variable MAXIMERROR is set accordingly.
batchcalibratefiles
Syntax: batchcalibratefiles infiles*.fit <outdirectory>
Description: 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.
kernelfilterfile
Syntax: kernelfilterfile infile.fit <outfile.fit>
Description: This command kernel filters (as configured in the variables KERNELFILTERVALUE and KERNELFILTERTYPE) the file “infile.fit” and saves the filtered image either back to the same file or to the optionally specified “outfile.fit”. If the filenames specified are not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. The variable MAXIMERROR is set accordingly.
combinefiles
Syntax: combinefiles filemask*.fit outfile.fit 0-4,6,7 align_flag calibrate_flag OR combinefiles filemask*.fit outfile.fit 5 triggersd align_flag calibrate_flag
Description: This command combines groups of image files specified by “filemask*.fit” and saves the combined file as “outfile.fit”. If the filenames specified are not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. Before the images are combined, they are optionally calibrated (if “calibrate_flag” is true) and are optionally aligned (if “align_flag” is true) using MaxIm DL’s star-matching (preferred) or brightest star (if star matching fails) algorithm. The third parameter specifies the combine type as follows: 0=sum, 1=average, 2=median, 3=sigma clip, 4=sdmask, 5=Lane-Majaess (LM) clip, 6= LM average, and 7=LM median. Combine types 0-4 are implemented by Maxim DL and the remaining 3 are done internally be ARAP. The Lane-Majaess (LM) clip algorithm requires the parameter “triggersd”. 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. If any error is detected the variable MAXIMERROR is set to true.
solveplate
Syntax: solveplate filename.fit rings <ra> <dec>
Description: This command attempts to astrometrically solve the image "filename.fit" (located in the directory specified by the IMAGEDIRECTORY variable) using the PinPoint astrometric engine. If the filename specified is not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. 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. If the solve is successful, the WCS FITs header keys are added to the image. The variable PINPOINTERROR is set accordingly.
batchsolveplate
Syntax: batchsolveplate filemask*.fit rings
Description: 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.
radectoxy
Syntax: radectoxy filename.fit
Description: 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
Description: 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 <autoaperture_flag> <centroid_flag>
Description: 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. 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 variables section). The variable MAXIMERROR is set to true if an error occurs.
intensitytomagnitude
Syntax: intensitytomagnitude intensity
Description: This command converts a linear intensity value (usually originating from the photometry command) to a logarithmic magnitude based on the reference values in variables PHOTOREFMAG and PHOTOREFINTENSITY. The result is stored in the PHOTOMAG variable.
getfitsheader
Syntax: getfitsheader variable_name key STRING|INTEGER|BOOLEAN|REAL <digits>
Description: 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). 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
Description: 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.
execute
Syntax: execute timeout command parameter1 parameter2 … parameterx
Description: This command executes the external program “command” with up to 7 parameters. It is allowed to run for as long as “timeout” seconds. The variable EXITCODE is set to the exit code returned by the external program – usually an exit code of 0 means the program worked correctly. The variable FILEERROR is set to true if there was an error running the command or if EXITCODE is not 0.
directorymake
Syntax: directorymake directoryname
Description: This command makes (if it does not already exist) a directory named "directoryname" in the directory specified by the IMAGEDIRECTORY variable. Regardless, it sets the variable IMAGEDIRECTORY to the new fully qualify directory name. If the directory cannot be created, the error is reported and the variable FILEERROR is set accordingly.
directorydate
Syntax: directorydate
Description: This command creates (if it does not already exist) a directory named "yyyymmdd" (year, month, and date in the current local time) in the directory specified by the IMAGEDIRECTORY variable. Regardless, it sets the variable IMAGEDIRECTORY to the new fully qualify directory name. If the directory cannot be created, the error is reported and the variable FILEERROR is set accordingly.
getfilelines
Syntax: getfilelines filename
Description: This command counts the number of text lines in the file 'filename' and sets the variable FILELINES with the number of lines. 'filename' must be fully-qualified. The variable FILEERROR is set accordingly.
getfileline
Syntax: getfileline filename line_no
Description: This command sets the variable FILELINE to the text contained on line number 'line_no' of the file 'filename'. 'filename' must be fully-qualified. The variable FILEERROR is set accordingly.
findfileline
Syntax: findfileline filename string
Description: This command searches every line in the file 'filename' for the character sequence ‘string’ and sets the variable FILELINENO with the line number of the first occurrence, or zero if the sequence is not found. 'filename' must be fully-qualified. The variable FILEERROR is set accordingly.
splitfields
Syntax: splitfields string <delimiter> <quoter>
Description: This command splits the variable ‘string’ into separate fields. By default, the space character is used to delimit the fields and fields that might contain the space character are kept as one field if they are surrounded by double-quotes. The fields are accessed with the ‘getfield’ command and the number of fields found is stored in the NUMFIELDS variable. The optional ‘delimiter’ and ‘quoter’ fields can be used to change the delimiter and quoting characters. Other commonly used delimiters are a comma and a tab. Use the variable TAB to specific the tab character. The maximum number of fields that are allowed is 50.
getfield
Syntax: getfield variable fieldno
Description: This command sets the variable ‘variable’ to the field ‘fieldno’ previously set by the ‘splitfields’ command. Field numbers start with 1.
putfileline
Syntax: putfileline filename linetext
Description: This command writes the line of text (‘linetext’) to the file 'filename'. 'filename' must be fully-qualified. If the file does not exist it is created, otherwise the line is appended to the end of the file. The variable FILEERROR is set accordingly.
deletefile
Syntax: deletefile filename
Description: This command deletes the file 'filename'. 'filename' must be fully-qualified. The variable FILEERROR is set accordingly.
findfile
Syntax: findfile filemask
Description: This command is used to find the names of files that match the filemask parameter. If the filemask specified is not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. The first time this command is used in a sequence, the filemask parameter must be used, but it can be omitted afterwards. The FILENAME variable is set to the filename with directory that is found. The variable FILEERROR is set to true if the first or subsequent file is not found.
findfileoff
Syntax: findfile filemast
Description: This command ends the current findfile command sequence. This command must be used if the findfile sequence not completed normally (until all files are found).
zip
Syntax: zip zipfile.zip files*.fit
Description: This command creates a new zip archive named "zipfile.zip" (specify the full path name) and then adds the files "files*.fit" (specify the full pathname and use the * and ? wildcard characters) to the archive. The variable ZIPERROR is set accordingly and EXITCODE is set to the exit code returned by the zip utility.
ftp
Syntax: ftp host username password destination_directory upload_file <timeout>
Description: This command is used to upload the file "upload_file" (specify the full path name) to an "ftp" server on the internet. The “upload_file” can include wildcards (*,?) to specify more than one file to be transferred. The “host” parameter is the internet domain name of the server or IP address. The “username” and “password” form the "credentials" for the account. The “destination_directory” is the directory on the server where the file is to be uploaded - it must currently exist on the server. If the default directory is desired used the parameter ".". The optional “timeout” parameter (maximum 7200 seconds) sets the maximum time that command will wait for the ftp operation to complete. The variables FTPERROR and EXITCODE are set accordingly. If EXITCODE=1 the connection to the server failed; if EXITCODE=2 changing to the specified directory failed; if EXITCODE=3, the file upload failed; and if EXITCODE=4, closing the connection with the server failed.
scp
Syntax: scp profile file.zip <timeout>
Description: This command is used to upload the file "file.zip" (specify the full path name) to an "scp" server on the internet. "scp" servers are similar to ftp servers but use a secure encrypted communications. This command uses the WinSCP (at least version 3.7.1) program. To use this command you will have to have previously setup a "profile" in winscp which includes the hostname, username and password, and destination directory. The optional “timeout” parameter (maximum 3600 seconds) sets the maximum time that command will wait for the ftp operation to complete. The variable SCPERROR is set accordingly and EXITCODE is set to the exit code returned by the scp program.
Syntax: email to@address.com subjectline bodytext
Description: This command sends an internet e-mail to "to@address.com" with the subject set to "subjectline" and the body of the message set to "bodytext". The variable SMTPSERVER must be set to a suitable outgoing mail server. The variable OUTGOINGEMAIL is used to specify the "from" address of the email. To send the message to more than one address, separate the individual addresses with a comma.
find
Syntax: find objectname
Description: This command searches the object databases for "objectname" and sets the RA and DEC variables accordingly. The variable FINDERROR is set accordingly.
findstar
Syntax: findstar rank minmag maxmag maxdistance
Description: This command searches the stellar database (Yale bright star catalog) to find the rank’th closest star to the position indicated by the variables RA and DEC that is between brightness “minmag” and “maxmag” and no farther than “maxdistance” degrees. The RA and DEC variables are set to the position of the star found. This command is intended to be used to find nearby stars suitable for focusing. The variable FINDERROR is set accordingly.
loadorbits
Syntax: loadorbits orbitfilename <append>
Description: This command loads into memory the orbital elements for up to 1000 comets and asteroids from the file “orbitfilename”. This file is to be formatted in the orbit format used by The Earth Centered Universe planetarium software. If the optional parameter “append” is true then the currently loaded orbit database is retained and the new database is appended, otherwise the currently loaded database is deleted before loading the new orbits. The variable ORBITERROR is set accordingly.
findorbit
Syntax: findorbit orbitname <strict>
Description: This command searches the currently loaded orbits (comets and asteroids – see “loadorbits” command) for “orbitname” and if found the variables RA and DEC are set to its current position, the variable “ORBITMAG” is set to its magnitude, and the variable “ORBITNAME” is set to its full name. If the optional parameter “strict” is false or omitted “orbitname” need only be contained within the full orbit name. For example if the “orbitname” is “Levy” it would find the comet “129P/Shoemaker-Levy”. If the optional parameter “strict” is true then the exact “orbitname” must be specified. This command is not space or case-sensitive. The variable ORBITERROR is set accordingly.
x10on
Syntax: x10on
Description: This command initiates communication with X10 type devices. If this operation is successful, the variable X10CONNECTED is set to "true", otherwise a fatal error is generated and the script aborts. All commands that require communication with X10 devices must be preceded by this command.
x10off
Syntax: x10off
Description: This command terminates communication with X10 type devices and sets the variable X10CONNECTED to "false".
x10deviceon
Syntax: x10deviceon house device
Description: This command turns on the power to a device connected to an X10 switch configured as "house" and "device". Both parameters accept a range of 1 to 16. Note that X10 house codes are usually labeled "A" to "P" which must be converted to a range of 1 to 16. The variable X10ERROR is set accordingly.
x10deviceoff
Syntax: x10deviceoff house device
Description: This command turns off the power to a device connected to an X10 switch configured as "house" and "device". Both parameters accept a range of 1 to 16. Note that X10 house codes are usually labeled "A" to "P" which must be converted to a range of 1 to 16. The variable X10ERROR is set accordingly.
x10devicebright
Syntax: x10devicebright house device percent
Description: This command increases the brightness, by the specified "percent", of a lamp connected to an X10 switch configured as "house" and "device". Both the "house" and "device" parameters accept a range of 1 to 16. The variable X10ERROR is set accordingly.
x10devicedim
Syntax: x10devicedim house device percent
Description: This command decreases the brightness, by the specified "percent", of a lamp connected to an X10 switch configured as "house" and "device". Both the "house" and "device" parameters accept a range of 1 to 16. The variable X10ERROR is set accordingly.
cloudsensoron
Syntax: cloudsensoron
Description: This command initiates communication with "Clarity", the software used to interface to the Boltwood Cloud Sensor. If this operation is successful, the variable CLOUDSENSORCONNECTED is set to "true", otherwise a fatal error is generated and the script aborts. All cloud sensor related commands must be preceded by this command.
cloudsensoroff
Syntax: cloudsensoroff
Description: This command terminates communication with the Boltwood Cloud Sensor and sets the variable X10CONNECTED to "false".
getcloudsensordata
Syntax: getcloudsensordata
Description: This command queries the cloud sensor for its data and sets the following variables: SKYSTATE, SKYTEMPERATURE, and AMBIENTTEMPERATURE. The variable CLOUDERROR is set accordingly.
radectoazalt
Syntax: radectoazalt
Description: Converts right ascension and declination to altitude and azimuth using the current time. The variables RA and DEC are used and the variables AZ and ALT are set.
azalttoradec
Syntax: azalttoradec
Description: Converts altitude and azimuth to right ascension and declination using the current time. The variables AZ and ALT are used and the variables RA and DEC are set.
sunradec
Syntax: sunradec
Description: Computes the current position of the Sun and sets the variables RA and Dec.
moonradec
Syntax: moonradec
Description: Computes the current position of the Moon and sets the variables RA and Dec. The Moon’s illumination is also stored in variable ILLUMINATION.
planetradec
Syntax: planetradec planet_no
Description: Computes the current position of a planet and sets the variables RA and Dec. The planet is specified by a number from 0 to 7 representing the planets Mercury through Pluto in order from the Sun (excluding Earth).
orbitradec
Syntax: orbitradec orbitnumber
Description: The “orbitnumber”
specifies at orbit (1 is the first orbit) from the database of currently loaded orbits (comets and asteroids
– see “loadorbits” command) and
computes and sets the variables RA and DEC are set to its current position, the
variable “ORBITMAG” is set to its current magnitude, and the
variable “ORBITNAME” is set to its full name. The variable
ORBITERROR is set accordingly.
calchourangle
Syntax: calchourangle
Description: Computes the current hour angle (westward from the meridian) of the position specified by the variables RA and Dec. The variable HOURANGLE is set.
calcairmass
Syntax: calcairmass
Description: Computes the current air mass of the position specified by the variables RA and Dec. The variable AIRMASS is set. If the air mass refers to an altitude less than 5 degrees, then the result will always be -1.
caljuliandate
Syntax: calcjuliandate
Description: Computes the current julian date and sets the variable JD.
azaltseparation
Syntax: azaltseparation az1 alt1 az2 alt2
Description: Computes the distance in degrees between two angular positions identify as az1/alt1 and az2/alt2. The variable SEPARATION is set.
radecseparation
Syntax: radecseparation ra1 dec1 ra2 dec2
Description: Computes the distance in degrees between two equatorial positions identify as ra1/dec1 and ra2/dec2. The variable SEPARATION is set.
precessfrom2000
Syntax: precessfrom2000
Description: Precesses the position specified by the variables RA and Dec from J2000 to the current date.
precessto2000
Syntax: precessto2000
Description: Precesses the position specified by the variables RA and Dec from the current date to J2000.
round
Syntax: round variable
Description: The variable ‘variable’ is rounded to the nearest integer with the result returned to ‘variable’.
echo
Syntax: echo message
Description: This command echos a "message" to the screen. The output of the echo command is not suppressed when the quieton command is active.
quieton
Syntax: quieton
Description: This command turns off the display of status information to the screen, except for error messages which always begin with “!!!” and output from the echo command. Note that status information continues to be written to the log file.
quietoff
Syntax: quietoff
Description: This command turns on the display of status information to the screen. Note that this command is automatically executed at the start of every script.
concat
Syntax: concat variablename string1 string2 string3…
Description: This command concatenates a list of strings and stores the result in the variable “variablename”.
script
Syntax: script filename.scr <parameter1>
<parameter2>
Syntax: filename <parameter1> <parameter2>
Description: This command runs a "child" script named "filename.scr". The script file must be either in the current directory (the directory where ARAP is installed) or in the directory specified in the "General Settings..." dialog box. Up to 10 parameters can be passed to a "child" script - see the Parameter Variables section below. When the "child" script finishes, the "parent" script continues running. If the script file is not found a fatal error is generated and the script aborts. Note that an easier way to run a script is to reference it by name as the first parameter of a line without the ".scr" part. For example, "script test.scr" just becomes "test".
pause
Syntax: pause
Description: This command causes the execution of a script to be paused. A dialog box is presented to the user with the option to either continue (Continue button) or abort (Abort button) the script (even if executed within a sub-script). Also provided is the ability to execute a manual command – enter the command in the space provided and press the “Manual Command” button. After the command has finished, script execution continues.
wait
Syntax: wait seconds
Description: This command causes the execution of a script to wait for the specified number of seconds (up to 86400 integer seconds – this is one day).
waitevenminute
Syntax: waitevenminute <minutes>
Description: This command causes the execution of a script to wait until the next even minute if no parameter is specified or until the passage of "minutes" even minutes (up to 60 integer minutes).
waittime
Syntax: waittime hours minutes seconds
Description: This command causes the execution of a script to wait until the specified time of day, given in local 24-hour time as "hours", "minutes", and "seconds".
waitdate
Syntax: waittdate year month date
Description: This command causes the execution of a script to wait until the specified local date, given as "year", "month", and "date".
end
Syntax: end
Description: This command causes the execution of a script to be stopped (even if it is executed from within a sub-script).
return
Syntax: return
Description: This command causes the execution of a sub-script to be stopped, but execution continues in the parent script.
Syntax: label linelabel
Syntax: linelabel:
Description: This command "labels" the current line as "linelabel". Labels are used by the "jump" command.or one of the several "if" commands. Note that an easier way to set a label is to reference it by name as the first parameter of a line followed by a ":" character. For example, "label label5" just becomes "label5:". A script can contain up to 100 labels.
jump
Syntax: jump label
Description: This command causes the script execution to jump to a new point ("label") in the script as set by the "label" command. If the label is not found a fatal error is generated and the script aborts.
iftrue
Syntax: iftrue $variable jump label
Description: This command causes the script execution to jump to a new point ("label") in the script, as set by the "label" command, if the specified "variable" is true. Note that valid "true" values include "true", "yes" and "on". If the label is not found a fatal error is generated and the script aborts.
iffalse
Syntax: iffalse $variable jump label
Description: This command causes the script execution to jump to a new point ("label") in the script, as set by the "label" command, if the specified "variable" is false. Note that valid "false" values include "false", "no" and "off". If the label is not found a fatal error is generated and the script aborts.
ifeq
Syntax: ifeq $variable1 $variable2 jump label
Description: This command causes the script execution to jump to a new point ("label") in the script, as set by the "label" command, if the two specified variables are equal (by comparing the strings). The string comparison is not case-sensitive. If the label is not found a fatal error is generated and the script aborts.
ifnoteq
Syntax: ifnoteq $variable1 $variable2 jump label
Description: This command causes the script execution to jump to a new point ("label") in the script, as set by the "label" command, if the two specified variables are not equal (by comparing the strings). The string comparison is not case-sensitive. If the label is not found a fatal error is generated and the script aborts.
if
Syntax: if $variable1 = $variable2 jump label
Syntax: if $variable1 <> $variable2 jump label
Syntax: if $variable1 > $variable2 jump label
Syntax: if $variable1 < $variable2 jump label
Syntax: if $variable1 <= $variable2 jump label
Syntax: if $variable1 >= $variable2 jump label
Description: This command causes the script execution to jump to a new point ("label") in the script, as set by the "label" command, if the numerical test of the two specified values is true. If the label is not found a fatal error is generated and the script aborts.