This document provides definitions of three types of program structures that are assumed by the modular routines available here:
The following objects are assumed to be available globally by default, by virtue of the script being run in the ACP 1.3 console. You should not attempt to create these objects or dimension variables for them. Note that some of these objects will have to be changed if you are using ACP 2. (We are cutting all our scripts over to ACP 2 and Maxim 3 at this time, and should have updated sources here by mid-January 2002. We've unfortunately chosen to add features while doing the cutover, which takes more time. In the meantime, very little will have to be changed to get these things working right for modular use in the newest versions of this software.)
Scope - the ACP scope object which allows you to slew your telescope, find out where it is pointed, etc. Alternately, the object name of the ASCOM telescope driver that you are using. Console - the ACP window that passes messages back to the operator. Util - the various tools that ACP provides internally, principally the WaitForMilliseconds method to allow us to wait for things like images to be taken. Voice - a "hook" into the Microsoft Agent, which is used only for the log functions.
There is some latitude here for creating these objects globally or locally. The modular functions and subroutines assume they are available globally, but you may have reason to alter these routines to create them locally.
Global declarations will require dimensioning at the beginning of a script, outside of Sub main(). In other words, global dimensioning will require:
Dim camera
Dim tools
'etc
Sub Main()
Set camera = CreateObject("MaxIm.CCDCamera")
Set tools = CreateObject("Widgets.Tools")
'etc - rest of subroutine goes here
End Sub
On the other hand, local dimensioning can be done just as easily:
Sub Main()
Dim camera
Dim tools
'etc
Set camera = CreateObject("MaxIm.CCDCamera")
Set tools = CreateObject("Widgets.Tools")
'etc - rest of script goes here
End Sub
Obviously, the big difference here is that the camera and tools objects will not be visible outside of Sub Main() if you dimension them locally. For the most part, global variables are considered a bad thing, so try to limit your use of them as much as possible (pass as many values as you can with functions). On the other hand, if you have multiple functions or subroutines hitting the same object, it is rather pointless to dimension the object identically in each function or subroutine. So in the case of these devices, it is much more straightforward to just dimension them globally.
Whatever method you elect to use, the following devices are assumed to be globally dimensioned by the modular functions and subroutines (these lines can be cut and pasted into your script):
'Global Dim
'Put these ABOVE your sub main()
Dim logFSO
Dim cam
Dim tools
Dim site
Dim objv
Dim plate
'Object creation - put this INSIDE your sub main()
Set logFSO = CreateObject("Scripting.FileSystemObject")
' (Supplied by the Windows Scripting Host.)
Set cam = CreateObject("MaxIm.CCDCamera")
' (Supplied by MaximDL/CCD, from Cyanogen Productions.)
Set tools = CreateObject("Widgets.Tools")
' (Supplied by Widgets, available on this site.)
Set site = CreateObject("NOVAS.Site")
' (Supplied by NOVAS freeware, from DC3 Dreams.)
Set objv = CreateObject("NOVAS.Star")
' (Supplied by NOVAS freeware, from DC3 Dreams.)
Set plate = CreateObject("PinPoint.Plate")
' (Supplied by PinPoint, from DC3 Dreams.)
The modular routines assume that you are using certain conventions for identifying certain kinds of data. For example, tgtRA is assumed to always contain (or contain a pointer to, or return) the right ascension of the object currently being observed.
In this example, tgtRA can be implimented in one of several ways:
The modular routines do not care how you impliment the data behind the names. If you want to write a function called tgtRA that returns the value, you can do so (throw out any target-generating code we have that defines tgtRA as a variable if you do this). You can do this with any of the names defined below.
The modular routines assume that these are all variables, globally defined. In general, global variables are frowned upon. The modular routines here come from scripts that I've written, and my early scripting efforts were a bit clunky. Part of this clunkiness was defining more globals than were really needed. By settling on a set of conventional names, I hope to cut these variables over to returns from functions as this project expands.
The code below can be pasted directly into your script. The comments indicate what the variable does. If something is identified as "clunky" it means there are significant peculiarities in how we handle this data, and sooner or later we're going to change how we do this. Here are the names:
' These first entered this list through the TakePicture function:
Dim GuideThisExposure ' True if a given exposure
' is to be autoguided. Set
' during runtime to "true" to
' guide an image, "false" to
' avoid guiding the image.
Dim GuideInterval ' This value times 1.25 is the
' duration of the guiding exposure.
' Clunky.
session ' a session number; the first four digits of the
' julian day and two decimal places. Used to
' distinguish logs started at different times and
' as a prefix to FITS files so that they don't
' overwrite each other even if they land in the
' wrong directory. How I make this number is documented
' with the log, logtext, and sayit functions.
' These first entered this list through the AimCamera & SpiralSolve functions:
regExpDelay ' The delay in seconds between
' completing a slew and starting
' a pointing exposure. Allows scope
' to damp vibrations.
astExpDelay ' The delay in seconds between
' completing a slew and starting
' a data exposure. Allows scope
' to damp vibrations.
pimageDir ' The directory in which you will
' be putting your pointing exposures
' (if any). Do not use a trailing \
tgtName ' The name of the target.
setNum ' The set number. If 1, then this is
' the first image taken of a given
' target; if two, the second, etc.
UseSubFrame ' If true, pointing exposures use
' a subframe for faster downloading.
PointSolveScale ' The image scale, arcseconds per pixel,
' of the CCD camera. Used for solving
' pointing exposures.
Rotation ' The roll angle of your images.
' These first entered this list through the GetGuideStar function:
DoWeGuide ' This is set to true if you intend to
' guide *any* image taken by your script.
' Note that individual images are guided or
' not by logical tests in the script -
' pointing exposures are never guided, nor
' are short data exposures. If you set this
' to True, longer exposures will be guided;
' if false, no exposures will be guided.
tgtDuration ' The exposure duration for the current target.
NoGuide ' Any exposure greater than this value (in seconds)
' will be guided. Any exposure equal to or less than
' this value will be unguided.
guider_offset ' The angular distance in degrees between the center
' of the guider field and the imaging field.
GuiderMagLimit ' The faintest star that can be used by the guider.
' These first entered this list through the log functions:
logStream ' the textstream for logFSO (documented with
' the log functions)
logDir ' the directory in which to put the log.