This is an Advanced Option.
You can write custom scripts for special missions with iTelescope ACP. You will need to upload your finished scripts to the telescope you wish to use via your itelescope interface.
A lot of information on writing your own scripts to control the telescope sessions can be found here.
It may be best to test your own scripts before starting to a long session.
iTelescope systems are based on a highly modified version of ACP, that we have customized in house. A number of key differences exist between the generic version and the iTelescope version. Please review this document for the supportediTelescope directives.
About Observing Plans
You can generate iTelescope ACP plans a number of ways:
- One Click Image. If you are new to iTelescope and ACP follow the “One Click Image” link, this will give you a menu of target currently visible from the observatory. You just click the target to start imaging it.
- iTelescope Advanced ACP can generate a simple plan via its web interface consisting of single target with multiple filters and exposure time, please see “Run Image Series” link in the iTelescope/ACP interface. This plan will automatically start at the observatory. This is by far the easiest way to get started. The plan it generates is called “last-plan-from-web.txt” and it can be download via the My Documents link on the interface if you wish to view its contents.
- iTelescope has also implemented via its reservation system a Plan Generator which works the same way as point two. You can select a target, filters and exposure times. You can give you plan a name and it will save it. You can then use this plan via the Launch a Plan feature on the reservation system to start the plan at a given date and time.
- You can also start this plan manually via “Run Scripted Plan” link. When you use the Plan Generator, it will also provide you the suggested start, transit and end imaging time for the selected target. Additionally it also provide the Sun rise and sun set times. You can use this information to figure out the best way to start your Launch a Plan reservation.
- You can write your own plan by hand or use the free ACP Planner. Use the directives contained in the bottom part of this page. Observing plans are text files containing instructions on how to acquire images. The easiest way to make observing plans for most people is via the free ACP Planner. It is your responsibility to create your observing plans, using ACP Planner or by hand.
Note that Planner can convert TheSky™ database exports and mosaics into ACP plans.
Overall Plan Format
Plan files are text files. Each line of a plan file must be one of the following:
Directive (line beginning with a „#‟)
Comment (line beginning with ‘;’) These are echoed into the log file (though sometimes at unexpected times due to ACP’s slew-ahead logic!)
Typically, a plan will consist of some directives followed by a target, some more directives, another target, etc. Lines may be indented by tabs or spaces. Any leading or trailing tabs or spaces are removed as soon as each line is read from the file. Comments beginning with ‘;’ may appear anywhere in a live line, and will be ignored.
The heart of a plan file is its target specification lines. Most commonly, each target specification line contains three pieces of information:
(1) the name of the target
(2) the J2000 right ascension of the target.
(3) the J2000 declination of the target.
Other information may be in the line, but it is ignored. One special type of target specification contains the orbital elements of a minor planet or comet, allowing Acquire images.js to calculate its position at the precise time of the exposure, and optionally perform orbital tracking (if the mount supports it) to follow the motion of the object.
Another special target specification contains ephemeral data for a near-earth object. In this case, you supply several ephemeris records, spaced 1 or 2 hours apart, and ACP will perform a Lagrange interpolation on the positions to determine a precise position and velocity (for orbital tracking) of the NEO. ACP accepts target specifications in several formats. These target specifications may be freely intermixed within a single plan file. They are:
Deep sky object or major planet name: If you specify only a name (nothing more on the target line) ACP will first try to match it to a major planet name and calculate an instant.
Simple tab-delimited format. Use this with objects for which you know the J2000 coordinates. This is really easy, but not as easy as just supplying the name as described above! The tab-delimited list is the simplest of the target formats accepted by the ACP. You can create tab-delimited text using Notepad, Word, Works, Excel, and many other tools.
The two most common tools are Notepad and Excel. In any case, the format of a target line is:name<tab>right-ascension<tab>declination mytarget 12:45:23 -10:45:03
The RA and Dec must be in standard J2000 coordinates. Will precess them to the current epoch and translate to local topocentric for you. The right ascension and declination may be supplied in a variety of formats, we’re very liberal in what we accept. Here are some examples:
Right Ascension Declination
13 24 18.25 63 11 43.2
Basically, the strings are chopped up into numeric parts (from 1 to 3) and combined sexagesimally. Any and all parts may have decimal digits. Right Ascension and Declination may have different formats as well.
“MP” followed by minor planet name: You can simply give the minor planet designation (packed or unpacked), number, or name, and ACP will retrieve the orbital elements from this database, then calculate coordinates for the exposure time.
Near-Earth Object Ephemerides from the IAU Minor Planet Center.
Asteroid or Comet 1-Line orbital elements from the IAU Minor Planet Center. This is a bit time-consuming because you have to get the elements for each of your targets from the MPC. For minor planets (not comets), see above. Additional Information on MP, NEO, Asteroids, Comets Acquiring images of minor planets (asteroids and comets) is complicated by the fact that the target moves relative to our position on the Earth. This means that the coordinates change with time and thus, to center the target in the image, the coordinates must be calculated for the time of the exposure. By using orbital elements, you provide ACP with the formula for calculating the position of the target at the time we actually start the exposure.
iTelescope supports offset tracking rates, be sure to look at the #TRACKON and #TRACKOFF plan directives. These control ACP’s orbital tracking feature, where the motion of the minor planet is fed into the telescope and its tracking is adjusted to match the motion. An orbitally tracked image will show trailed stars and a stationary minor planet.
Newly discovered near-earth orbit (NEO) asteroids may not have elements available. They may be listed on the Near Earth Asteroid Confirmation Page (NEOCP), however, in the form of ephemerides. ACP can also handle targets composed of multiple NEOCP ephemeris records. See NEO Ephemerides.
Minor Planet Elements
ACP accepts minor planet orbital elements in the Minor Planet Center “1-line” format or just the designation (numbered, named, packed or unpacked provisional, see the info on MPCORB below). To get this information directly from the Minor Planet Center’s web site (as opposed to a local MPCORB database), first prepare a list of targets you want to image by designation or name. Designations should be entered in one of the following forms: Named objects: Denny Numbered objects: (1290) or 1290 Unnumbered objects: 1997 XF11 or 1998 AA.
Designations are case sensitive. Once you have this list, go to the Minor Planet Ephemeris Service web page. Enter your objects as above into the list area. You can leave the Ephemeris Options section blank, as you are not getting an ephemeris. Make sure you select “MPC 1-line” for the return format, as shown in the image to the right. You will be prompted to save a file called “elements.txt” (or possibly “elements.txt.COM”), save the file with the name you wish, and an extension of “.txt”.
Please see this link for the format of the MPC 1-line elements
The MPC furnishes elements in a number of formats used by other software, however ACP uses the standard MPC format. ACP is compatible with the new encoded numbering format used for asteroids with numbers 100000 and greater.
iTelescope uses the MPCORB Database If you built the local MPCORB database as described in the note above, you need only give “MP ” (note the space after MP) and the designation. If you use a (numbered) minor planet number, you must give all 5 digits, including leading zeroes if necessary. For example: MP 12000 ; or 1996 CK2 MP 2000 YX26 ; or K00Y26X MP Denny ; or 23257 Comet Elements
MPC 1-Line Observable Comet elements are available from the Minor Planet Center
The MPC furnishes elements in a number of formats used by other software, however ACP uses the standard MPC 1-line format. ACP supports the specially named comet-fragment MPS 1-line elements as well.
#INTERVAL 120 ; 120 second exposures of each
#COUNT 3 ; 3 expositions 120sec each
#TRACKON ; Enable orbital tracking
CK12F060 2013 03 24.5138 0.731247 0.998530 304.9873 332.7147 82.6079 20130213 10.0 4.0 C/2012 F6 (Lemmon)
A near-earth object listed on the Minor Planet Center’s Near Earth Object Confirmation Page (NEOCP) will not have orbital elements available. Instead, the MPC publishes short-term ephemerides on the NEOCP. You can retrieve the ephemerides for one or more NEOs and construct target specifications for each. The format of NEO Ephemeris target specifications is strict. You must follow the directions explicitly or your plan will fail on the bad specifications. You must set up the NEOCP ephemeris generator web page with the following options in order to get ephemeris lines in the expected format (all of these options are vital):
Geocentric observing point
Ephemeris Interval of 1 hour
Decimal coordinate format
Motions in “/hr
Separate RA and Dec coordinate rates (not sky rates!)
Full output (not brief!)
The length of the resulting ephemeris lines should be exactly 65 characters (ignoring any uncertainty hyperlinks that may be present!). If not, you picked the wrong options above. A typical ephemeris line from the MPC should like this (this is not the target specification format!): 2004 10 27 02 01.6915 -40.095 126.8 18.7 -69.29 -2.51 Once you have the NEO ephemerides displayed on your browser, select from 4 to 6 lines (spaced two hours apart) that will provide data for the entire night (so you don’t have to know just when ACP will observe the NEO). Then build your ACP target specification as:
1. A 10-character target name (add spaces to make it 10-characters)
2. Exactly one space
3. The first 35 characters of the first ephemeris line (Time, RA, Dec only)
4. A “|”
5. The first 35 characters of the next ephemeris line (use the one for 2 hours later than the first)
6. … and so on, for 4 to 6 lines.
This may seem complex, but once you get it, it’s actually straightforward. Here is an example ACP plan target line for NEO A123456789 (hypothetical!) with 4 ephemeris records spaced 2 hours apart: A123456789 2004 10 27 02 01.6915 -40.095|2004 10 27 04 01.6834 -40.167|2004 10 27 06 01.6689 -40.301|2004 10 27 08 01.6721 -40.462
This target specification format is the most demanding of care and accuracy of any of ACP’s target lines. The benefit is that your NEO images will be at precisely the coordinates predicted by the MPC, and if you use orbital tracking, your scope will move to track the motion of the NEO during the exposure.
Sets, Repeats, and Filter Groups
Plans have three levels of repeat capability. While this makes ACP plans very powerful and flexible, it can also be confusing at first, so please read on.
The #Filter, #Binning, #Count, and #Interval directives remain in effect across multiple targets, until changed. #Repeat does not. Each target can include a filter group, that is, a series of filters, counts, exposure intervals, and binnings. For example: #Filter Luminance,Clear,Green,Blue #Binning 1,2,2,2 #Count 6,3,3,3 #Interval 300,300,300,300 M 51 This specifies a total of 15 images of M 51, starting with 3 Red images at 300 sec. and binning 2, etc.
The number of items in each series must match and you must specify series for filter, count, interval, and binning. For example, if you specify four filters, you must also specify four counts, four intervals, and four binnings. You can multiply a target’s filter group with the #Repeat directive. For example #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 specifies 28 x 3 = 84 images of M 51.
The complete filter group is repeated three times, in other words, it will take 28 images in each of 4 filters, then loop back and do another 28 images in 4 filters, and then loop back for a third time taking another 28 images. An entire plan may be repeated using the #Sets directive. Remember, #Repeat does not carry across multiple targets. For example: #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 specifies 2 x ((28 x 3) + (38 x 2)) = 320 images.
Note that #Filter, #Binning, #Interval, and #Count all carry across targets, while #Repeat does not. If you omit the second #Repeat (#Repeat 2) the second filter group (for M13) will result in only 38 images, not 76.
GRAS Directives (These affect the plan as a whole) Directives may be interspersed within the target lines in your observing plans. The system recognizes a directive by its first non-blank character, which must be a “#”.
These are iTelescope specific directives these directly only work with the iTelescope version of ACP.
- #PLATESOLVE Forces each imaging to be plate solved the fits header will contain the plate solved information. This directive affects all targets. #DEFOCUS Defocus the image slightly, sometimes used for photometry. This directive affects all targets.
- #TIFF Also saves your images in unprocessed 16bit TIFF file format. #EXPRESS Will cause ACP to skip all pointing updates and cause ACP not to auto guide at all. This directive use the telescope raw pointing and we can not guarantee your target will be centered or your images will be well formed. Use at your own risk, suggested application is for high speed imaging runs that consist of lots of targets with short exposure times. This directive affects all targets.
- #FILTEROFFSETS Focus using filter offsets on change of filter instead of re-focusing the telescope on each filter switch. If you wish to achieve optimal focus between filters we recommend not using this directive as your images may sometimes be slightly out of focus, due to terminal expansion/contraction of telescope over changing weather conditions. This directive affects all targets.
- #VPHOT Send your image files to VPHOT server for online photometry analysis. You need to have an AAVSO membership to use this service. This directive affects all targets.
- #REPEAT Tells script to take the given number of filter groups of the next target or dark/bias frame (#DARK) in a row. #REPEAT may be combined with #SETS. For example: #REPEAT 5 #AUTOGUIDE Forces the next target’s images to be guided,
- #POINTING Schedule a pointing update prior to the target. This will work even if auto-center is disabled in Preferences. Thus, you can use #POINTING as a means to manually control when pointing updates occur in a plan. For example: #POINTING These affect the current and all subsequent targets
- #COUNT Used only when specifying a filter group. For example: #Count 5,10,5,15 #INTERVAL Set the final target exposure interval(s) for subsequent targets (sec.). For example: #INTERVAL 31.5 #INTERVAL 180,240,180,180
- #FILTER Set the filter(s) for subsequent targets. If the filter name is not recognized, an error is logged at plan start, and the plan will not run. For example: #FILTER Blue #FILTER Red,Clear,Green,Blue
- #BINNING Sets the binning factor(s) for subsequent targets. Note that some detectors don’t support arbitrary binning values. #BINNING 1 #BINNING 2,1,2,2
- #SUBFRAME Sets the fraction of the chip to be used for subsequent images. Legal values are 0.1 to 1.0 (full frame). For example, if the chip is 1K by 1K (1024 by 1024), a SUBFRAME of 0.5 will result in using the center 512 by 512 pixels of the chip. For example: #SUBFRAME 0.5
- #DITHER Offset each image in a repeat-set by some small amount away from the original target location. Works for both guided and unguided images. If no parameter is given, ACP uses values of 1 guider pixel for guided dithering and 5 main imager pixels for unguided dithering (see below). Normally, these values will be appropriate for achieving the noise reduction effect of dithering. Dithering is done by generating two uniform random numbers ranging from minus to plus the “amount”. One is applied in the X direction, the other in the Y direction. If given, the parameter specifies the maximum amount in each axis of this offset in fractional pixels. A parameter value of 0 disables dithering. Note: If guiding, the value is in guider pixels, not pixels on the main chip! You have to make the conversion if you want to know how far on the main chip the dither will be. For unguided images, the distance is in main imager chip pixels. In either case, the random offsets are applied independently in X and Y and are always relative to the initial position. For example: #DITHER ; Automatic dithering #DITHER 1.5 #DITHER 0 ; Disable dithering
- #TRACKON Initiates orbital tracking of solar system bodies. This remains in effect until cancelled by #TRACKOFF. Orbital tracking will not be done except for solar system bodies, so non-solar-system targets may be intermixed without harm. Autoguiding will not be done if orbital tracking is active. Note that orbital tracking requires orbital elements as the target specification (major planet targets will also be tracked). For example: #TRACKON
- #TRACKOFF Cancels orbital tracking. This remains in effect until re-enabled with #TRACKON. For example: #TRACKOFF These affect the plan as a whole #SETS Repeat the entire plan a given number of times. The images are acquired in round-robin order. This directive may appear anywhere in the plan. If it appears more than once, the last value is used for the plan. The default is a single set. For example: #SETS 3
- #AFINTERVAL Turns on periodic autofocus. The interval is given in minutes. If an #AUTOFOCUS directive is seen, it overrides a scheduled autofocus, and the time to the next autofocus is reset to the interval. This directive may appear anywhere in the plan, and the value given in the last appearance will be used for the entire plan. If you want an initial autofocus at plan start, include a separate #AUTOFOCUS for the first target. For example, to do an autofocus every 30 minutes: #AFINTERVAL 30
- #SHUTDOWN Will park the telescope and log you off the observatory. #SHUTDOWN These act like targets #DARK Acquire a dark or bias frame using the current target exposure interval. If you set #INTERVAL to 0 before using #DARK, ACP will acquire a bias frame, and the file naming will be adjusted. It is recommended, however, to use the #BIAS directive described below. You can use the #REPEAT directive to acquire multiple darks or biases. Multiple darks/biases will be sequence numbered as well as carrying the current #SET number, similar to file naming for light images (except no filter name is included of course). For example: #DARK results in one or more files of the form Dark-Snnn-Rnnn.fts, or if the preceding #INTERVAL was 0, Bias-Snnn-Rnnn.fts. #BIAS Acquire a bias frame using the current target exposure interval. You can use the #REPEAT directive to acquire multiple biases. Multiple biases will be sequence numbered as well as carrying the current #SET number, similar to file naming for light images (except no filter name is included of course). For example: #BIAS
- #MANUAL Acquire an image at the current telescope location. No pointing updates or slews will be done. This is actually a type of target, so don’t include a target line. Include an object name. For example: #MANUAL MyImage If you don’t include an object name, the current date/Time will be used. For example: #MANUAL results in an image file name of Manual-dd-mm-yyyy@hhmmss-Snnn-Rnnn-filter.fts These terminate the plan (last or only set)
- #CHAIN When encountered during the last (or only) set, immediately stops reading image acquisition lines from the current plan file, queues a new run of AcquireImages.js with the new plan, then exits. A chained-to plan is thus run in a separate invocation of AcquireImages.js, and starts with conditions identical to those when the same plan is run directly. Use this to chain together plans, each of which might take several sets of images, then wait for a while, then run the new plan which would also take several sets of images. For example: #CHAIN nextplan.txt or if you just specify a file name, the plan is assumed to be in the same folder as the plan being chained-from. For example:
#CHAIN nextplan.txt ; In current plan’s folder