Creating Custom Plans

What Are Alnitak Observing Plans?

Alnitak observing plans are text files which contain instructions to the telescope on how to acquire images. You can use Alnitak’s Create Plan menu, but you can also create observing plans by hand in a text editor and upload them in the Plans / Upload Plan menu.

Observing Plan Format

Plan files are text files in which each line is one of the following types:

  • Directive (line beginning with ‘#’)

  • Target specification

  • Comment (line beginning with ‘;’)

The structure of a plan file is most commonly directives followed by a specified target, then other directives and another target, and so on. You can indent lines with either tabs or spaces. As a file is read, any leading or trailing tabs or spaces are removed. Comments beginning with ‘;’ may appear anywhere as they will be ignored. You can separate directives and their arguments with either tabs or spaces.

Target Specifications

Target specification lines make up the core of a plan file. A target specification line is usually composed of three items: the name of the target, the J2000 right ascension of the target, and the J2000 declination of the target. Any other information in the line is ignored.

Orbital elements of a minor planet or comet are contained in a special type of target specification. This target specification allows the Alnitak telescope to calculate the position of the minor planet or comet at the precise time of exposure, and as a further option, perform orbital tracking to follow the object’s motion. Ephemerides for a near-earth object (NEO) are contained in another type of target specification. Alnitak will perform Lagrange interpolation on positions you supply from ephemeris records (spaced 1 or 2 hours apart) to determine the NEO’s precise position and velocity.

Alnitak accepts several formats of target specifications, which can be freely intermixed within an observing plan:

  • Deep sky object or major planet name: If only a name is specified, Alnitak will try to match it to a major planet name, calculating an instant ephemeris for the time of the image. If this does not work, it will try searching its deep sky catalog and retrieving the coordinates. Catalog name and number must be separated by a space (e.g. “M 51”, “PGC 12345”).

  • “MP” followed by minor planet name: You can give the minor planet designation (packed or unpacked), number, or name, and Alnitak will retrieve the orbital elements from its database, and calculate the coordinates for the exposure time. Alnitak uses the Minor Planet Center’s orbital elements database (MPCORB.DAT).

  • “CT” followed by comet name: You can give the comet’s designation or name, and Alnitak will retrieve the orbital elements from its database, and calculate coordinates for the exposure time. Alnitak uses the Minor Planet Center’s cometary orbital elements database (MPCCOMET.DAT).

  • Simple tab-delimited format. An easy alternative to providing the name of the object if you know the J2000 coordinates of your object.

  • Asteroid or Comet 1-Line orbital elements from the IAU Minor Planet Center. You have to get elements for each of your targets from the MPC, so this is a bit more time consuming.

  • Near-Earth Object Ephemerides from the IAU Minor Planet Center.

Sets, Repeats, and Filter Groups

Alnitak observing plans have three distinct levels of repeat capability. Despite being confusing, this capability makes Alnitak very powerful and flexible to the user’s needs.

While the #Filter, #Binning, #Count and #Interval directives remain in effect across multiple targets, #Repeat does not.

A filter group is a series of filters, counts, exposure intervals (durations), and binning modes which can be included in each target. The number of items in each series must match. An example being:

#Filter Red,Clear,Green,Blue
#Binning 2,1,2,2
#Count 5,8,5,10
#Interval 180,240,180,180
M 51

This observing plan specifies 28 images of M 51, starting with 5 Red images at an interval of 180 seconds and a binning of 2, and ends with 10 Blue images at an interval of 180 seconds and a binning of 2.

Using the #Repeat directive, you can multiply a target’s filter group. An example being:

#Repeat 3
#Filter Red,Clear,Green,Blue
#Binning 2,1,2,2
#Count 5,8,5,10
#Interval 180,240,180,180
M 51

This observing plan specifies 84 (28 x 3) images of M 51. Once it takes 28 images in each of the 4 filters, it will loop back to do another 28 images, and afterwards will loop back to do another 28 for a total of 84.

Using the #Sets directive, you can repeat an entire plan. An example being:

#Sets 2
#Repeat 3
#Filter Red,Clear,Green,Blue
#Binning 2,1,2,2
#Count 5,8,5,10
#Interval 180,240,180,180
M 51
#Repeat 2
#Count 6,10,7,15
M 13

This observing plan specifies 320 images (2 x ((28 x 3) + (38 x 2))). While #Filter, #Binning, #Interval, and #Count all carry across targets, #Repeat does not. Therefore, removing the second #Repeat will result in 38 images and not 76.

Directives

You may distribute directives within target lines in your observing plans. The way the system recognizes a directive is by its first non-blank character, which in the case of a directive is a “#”. You can give arguments (parameters) to directives, and you can separate directives and their arguments with either tabs or spaces.

Directives only affecting the next target:

  • #REPEAT – refer to Sets, Repeats and Filter Groups . A #REPEAT directive tells the Alnitak telescope to take a given number of filter groups of the next target (or dark/bias frame (#DARK)) in a row. You can also combine #REPEAT with #SETS to repeat entire plans.

  • #CALIBRATE – A #CALIBRATE directive will force calibration of the images for the next target. It will function even if the Alnitak telescope’s auto-calibration preference is turned off (but is useless if it is turned on). A #CALIBRATE directive will only cause calibration of the final images and not point exposures.

  • #AUTOGUIDE – An #AUTOGUIDE directive will force the images of the next target to be guided, regardless of the selected duration of the exposure or the setting of the Alnitak telescope’s autoguiding preference.

  • #STACK – A #STACK directive will combine, without aligning into one image, repeated images in a filter group. However, individual images used in the stack will be preserved. Instead of the repeat number, file names will have -STACK in them. When you are doing orbital tracking, the #STACK directive is very useful. Refer to #TRACKON. In order to preserve the dynamic range, the stacked image will be saved in IEEE floating-point FITS format.

  • #STACKALIGN – A #STACKALIGN directive will combine, with aligning into one image, repeated images in a filter group. Same as with the #STACK directive, individual images will be preserved. Instead of the repeat number, file names will have STACK in them. You should use this for all stare-mode image sets. The stacked image will be saved in IEEE floating-point FITS format.

  • #AUTOFOCUS – refer to Sets, Repeats, and Filter groups. You can use a #AUTOFOCUS directive to automatically refocus the optical system before each filter group in the next target’s filter group. Even if #REPEAT is greater than one, the autofocus will be done only one time for the next target. If you want to have periodic autofocus, refer to the #AFINTERVAL directive. The Alnitak telescope also has an adaptive autofocus feature whereby the Alnitak telescope will monitor the diameter of the half-flux (which is a measurement of focus quality) and autofocus if needed if half-flux changes by 50% or more.

  • #NOSOLVE – This directive will prevent plate solving of the final/data image for all images of the specified target.

  • #WAITFOR – This directive will pause the observing plan for a given number of seconds before processing the next target. E.g., ‘#WAITFOR 30’ will pause for 30 seconds.

  • #WAITUNTIL (date/time) – This directive will pause the Alnitak telescope during a specific set until the given UTC date/time or (only) time. Specify the set number for the pause in the first parameter, and specify the date/time at which to resume in the second parameter. The specified set number ranges from 0 to the number of sets specified in the #SETS directive, but the set number must be 1 if there is no #SETS directive on the plan. If you specify the set number to be 0, it will mean to wait on all the sets. If a complete date/time is specified, and the date/time has passed, the #WAITUNTIL directive will be ignored by the Alnitak telescope. Note that the Alnitak telescope will wait for up to 12 hours if only a time is specified, and it will not wait if the time is less than 12 hours in the past. For example:
    #WAITUNTIL 3, 14-Mar-2023 09:04:00
    Wait until 09:04 UTC only if the set is #3 and only if it is 14-Mar-2023
    #WAITUNTIL 2, 09:04:00
    Wait until 09:04 UTC only if the set is #2 no matter what date it is
    #WAITUNTIL 0, 09:04:00
    Wait until 00:04 UTC on any night and on any set
    Acceptable formats include:
    7/3/06 08:22
    07/03/2006 18:34:24
    03-July-2006 06:34 PM

  • #WAITUNTIL (sun-down angle) – This directive functions similar to the #WAITUNTIL (date/time) directive, but pauses the specific set until the Sun gets below the specified angle. The angle must be in degrees and a negative number. Instead of the second parameter being the date/time, it is the negative sun-down angle at which to resume. For example:
    #WAITUNTIL 1, -10.5
    Wait until the Sun gets to 10.5 degrees below the horizon if set #1

  • #WAITINLIMITS – This directive will pause the Alnitak telescope until the specified target is within the limits of the observatory. These limits being minimum elevation, horizon, and tilt-up limit. The target will be skipped if it will never meet the criteria. You must include a maximum time to wait (in minutes). For example:
    #WAITINLIMITS 60
    This will cause the Alnitak telescope to wait until the specified target rises
    above the limits of the observatory for up to 60 minutes.

  • #WAITZENDIST – This directive will pause the Alnitak telescope until the specified target is within the given zenith distance. The target will be skipped if it will never get within the specified zenith distance or within the given time. You must include a maximum time to wait (in minutes). For example:
    #WAITZENDIST 40, 30
    This will cause the Alnitak telescope to wait until the specified target is within 40 degrees of the zenith for up to 40 minutes.

  • #WAITAIRMASS – This directive will pause the Alnitak telescope until the specified target is at or below the given air mass. The target will be skipped if it will never get within the given distance or the given time. You must include a maximum time to wait (in minutes). For example:
    #WAITAIRMASS 2.5, 30
    This will cause the Alnitak telescope to wait until the specified target is at or below 2.5 air masses for up to 30 minutes.

  • #TAG – To add a named tag to the specified target, you can use this directive. It does not affect the image acquisition process as it only attaches a tag name and value to the specified target. You can specify any number of tags for any target, as long as they all have different names. For example:
    #TAG type=reference star
    This will attach a tag “type” with the value “reference star” to the specified target.

Directives affecting all subsequent targets:

  • #COUNT – Refer to Sets, Repeats and Filter Groups. You can use this only when specifying a filter group. For example:
    #Count 10,2,5

  • #INTERVAL – Refer to Sets, Repeats and Filter Groups. This directive sets the final target exposure intervals for any subsequent targets, in seconds.

  • #FILTER – Refer to Sets, Repeats and Filter Groups. This directive is required as the Alnitak telescope has filters. This directive sets the filter(s) for any subsequent targets. The observing plan will not run if the filter name is not recognised. For example:
    #Filter Blue
    #Filter Blue,Clear

  • #BINNING – Refer to Sets, Repeats and Filter Groups. This directive sets the binning factor(s) for any subsequent targets. 

  • #SUBFRAME – A #SUBFRAME directive will set the fraction of the chip used for any subsequent targets. For example, if the chip is 1024 x 1024 pixels, and if the value in the #SUBFRAME directive is 0.5, half of the pixels will be used (512 x 512).

  • #DITHER – A #DITHER directive will offset each image taken in a repeat-set by a small amount away from the original target location. The Alnitak telescope will use 5 main imager pixels for dithering if you do not give a parameter. To do dithering, the telescope will generate two uniform random numbers, which will range from minus to plus the amount specified. These two numbers will be added to the x and y directions, and the telescope will shift accordingly. In order for the Alnitak telescope to calculate the main imager pixels for dithering, you must give a value for the guider’s plate scale. Dithering will be in guider pixels and a warning message will appear in your run log if you fail to do this. If you give a parameter of 0, dithering will be disabled. If you give a parameter, it will specify the maximum amount of offset in fractional pixels in each axis. For example:
    #DITHER
    Enables automatic dithering
    #DITHER 5.0
    Enables 5 pixels of dither on your images
    #DITHER 0
    Disables dithering

  • #TRACKON – The #TRACKON directive commences the orbital tracking of solar system bodies. Orbital tracking of solar system bodies will remain indefinitely until the #TRACKOFF directive is used. No non-solar system targets will be orbitally tracked, so they may be intermixed with solar system targets harmlessly. If orbital tracking is active, autoguiding will not be done.

  • #TRACKOFF – The #TRACKOFF directive cancels orbital tracking indefinitely until turned on again by #TRACKON.

  • #DEFOCUS – Before acquiring any subsequent image, this directive moves the Alnitak focuser the specified number of integer steps away from its proper focus. Although the Alnitak telescope will restore the focus position immediately after acquiring the image, the #DEFOCUS directive stays active indefinitely unless changed. The #DEFOCUS directive will not affect pointing images.

Directives affecting the entire plan:

  • #SETS – Refer to Sets, Repeats, and Filter Groups. This directive will repeat the entire plan for a specified number of times. Although this directive may appear anywhere in a plan, if it appears more than once, the value used for the plan will be the last.

  • #AFINTERVAL – This directive will turn on periodic autofocus on the Alnitak telescope and will force an autofocus at the start of your observing plan. The interval is specified in minutes. The #AFINTERVAL directive will override any #AUTOFOCUS directive, and will reset the time to the next autofocus to the specified interval. The #AUTOFOCUS directive can appear anywhere in the plan. E.g.:
    #AFINTERVAL 60
    This will cause the Alnitak telescope to start your plan with an autofocus, then do another one every hour.

  • #ALWAYSSOLVE – The #ALWAYSSOLVE directive will force the Alnitak telescope to always attempt solving every final image. If this directive is not used, the telescope will attempt to solve images once, and if the solving fails the telescope will skip that series. You can place this directive anywhere in your observing plan.

  • #MINSETTIME – This directive tells the Alnitak telescope what the minimum amount of time is for a set. For example:
    #MINSETTIME 00:10
    This will tell the Alnitak telescope to wait until at least 10 minutes has elapsed before starting the next set.

  • #QUITAT – You can use the #QUITAT directive to specify a time at which the Alnitak telescope will stop acquiring images. This directive is in the same format as the #WAITUNTIL directive. Actions that will occur after the plan ends are #DAWNFLATS, #CHAIN, #CHAINSCRIPT. The plan will end normally if it finishes before the specified time. If no date is specified, it will quit at the specified time. For example:
    #QUITAT 9/2/23 11:34
    The Alnitak telescope will stop acquiring images at 11:34 on 9/2/23.

Directives that act like targets:

  • #DARK – This directive forces the Alnitak telescope to acquire a dark or bias frame. The #DARK directive uses the current target exposure interval. If you want to acquire a bias frame, set the #INTERVAL to 0, but it is recommended to use the #BIAS directive instead. A #REPEAT directive can be used for acquiring multiple dark or bias frames. You may also give a file path for the dark or bias frame(s) to be created in.

  • #BIAS – This directive forces the Alnitak telescope to acquire a bias frame. It functions the same way as a #DARK directive, and a file path can also be given.

  • #MANUAL – The #MANUAL directive forces the Alnitak telescope to acquire an image at the current location. You should include an object name, but if one isn’t given the image will be saved with the current date and time.