Sometimes ACP's standard image file naming and/or folder usage is not well suited for a particular observatory's use. Since ACP is designed to be usable by a wide spectrum of astronomers, we've provided a way to customize the image (and log) file naming, as well as the folder paths and names for same. This facility treats "light" images separately from calibration images, flat frames, and log files.
Lost? Having trouble visualizing what is going on with customizing? Try the Template Generator Tool. Having trouble finding the image and log files themselves and/or the configuration files you may have already set up? Try the Where Are My Files? tool!
To activate this feature for most classes of files (image, dark/bias, or log), you need to create a corresponding template text file (with notepad or your favorite text editor) in the ACP configuration file folder (typically Public Documents\ACP Config). The template text files are:
Live images: ImageFileConfig.txt
Dark/Bias frames: CalFileConfig.txt
Log files: LogFileConfig.txt
For flat fields generated by ACP's automatic flat feature, the folder and file template strings are included in the AutoFlatConfig.txt file. See Getting Started in the ACP AutoFlat documentation for other info on AutoFlatConfig.txt; the template information is given below in AutoFlat File and Folder Customization.
Template Concept
Folder and fiile paths and names are constructed by ACP using the concept of a template which can consist of simple text with substitution tokens interspersed. For example, let's say we want our image file names to be like Image of M-57 taken on the night of 27-Dec-2014.fts. For this we would use a template of
Image of $TGTNAME taken on the night of $DATENITE
where the tokens (see below for the list of tokens) $TGTNAME and $DATENITE are replaced at observation time by the name of the target and the local date for the evening on which the run started. The key concept here is that the naming template can contain both simple text as well as the substitution tokens.
Config File Format (Light, Dark, Bias and Log files)
The format of the config files (for each type of image) is the same. Blank lines and lines beginning with ; are considered to be comments. At least one line (see next section) needs to have the template for the path and name of the corresponding class of files. To generate customized file and folder paths and names, the template can contain "tokens" which will be replaced by ACP to form the final folder/file path and name. For example, an ImageFileConfig.txt containing
will result in the normal/default folder and file naming for light images that ACP provides without customization. The other config files are CalFileConfig.txt (bark/bias images) and LogFileConfig.txt (log files).
Do not include the file type (extension) such as .fts or .fit in the templates!
In order to help you get started with the templates, we've included a tool that constructs a template based on your choices. Obviously, the limitless ways that you can set up folders and files can't be covered by this tool. However, we've tried to anticipate some useful and common setups. At a minimum, playing with this for a few minutes should help you "get it".
Per-User and Separate Web Templates (advanced)
It is possible to have special file/folder naming for one or more web users. You can specify one template for all web users and/or separate templates for one or more web users. To do this, precede any default template (as described above) with user-specific templates, then (optionally) a web-specific template (applies to all web users who don't have specific templates, then end the file with the (optional) override template as described in the preceding section. Web users are designated by enclosing their login username in square brackets. An "all web users" template is specified with [*]. The user-specific templates must come first, followed by a possible all-web-users template, followed by a possible default template. Some examples should make this clearer:
This gives web users a naming where file names start with the "run date" (see below) instead of creating separate folders with the run-date name. Note the '-' after $DATENITE, which makes it part of the file name. Local users get the standard ACP naming.
This gives all web users the custom naming from the previous example, and gives local users folders with the UTC date name (instead of the run date) as well as adding East/West meridian status to file names.
The Julian date (no fractional part, just the date, for example 2453935 for 19-Jul-2006).
$DATELOC
The date in local time (per the Windows date/time control panel, time zone settings), formatted as yyyymmdd, for example 20060719. This format will sort alphanumerically in date order.
$DATENITE
The local date of the run (night), formatted as yyyymmdd, for example 20060719. This token is useful if you want to put all of your images from a single run/night into one folder. The date changes when the sun crosses the local meridian, thus the folder will remain the same even though the local date changes at midnight.
$DATEUTC
The UTC date, formatted as yyyymmdd, for example 20060719.
$DEFPATH
Image and cal files only: The default images folder as configured in ACP Preferences, Local User tab, for the local user, or the path to a web user's default image folder depending on ACP's web document root preferences). Normally your images and cal templates will start with this token.
$FILTER
Image and cal files only: The name of the filter used when the image was acquired. If you plan to combine LRGB images in MaxIm DL, and you have named your filters Clear, Red, Green, and Blue in MaxIm's filter setup, MaxIm will automatically recognize the appropriate color if this token appears at the end of the file name (this is true for the default file name template shown above). For example NCG3210-Blue.fts.
$INTERVAL
Image and cal files only: The exposure duration (interval), seconds, rounded to the nearest second, formatted as three digits, for example 65.5 would be 066.
$LOGPATH
Log files only: The default logs folder as configured in ACP Preferences, Local User tab, for the local user, or the path to a web user's default logs folder depending on ACP's web document root preferences). Normally your logs template will start with this token.
$MERSIDE
Image files only: The viewing side of the meridian for a German mount. If the scope is looking west of the meridian, "W", and if looking east, "E". Most useful as a path token (as opposed to a file name token). This permits you to separate images taken looking west of the meridian versus east into separate folders. If the mount is not German, this will be set to "_", and is thus not useful in that case.
$PLANNAME
The name of the current observing plan (without the extension). Most useful for log files, but may be used on any type of file.
$RPTNUM
Image and cal files only: The sequence number (starting with 1) of the file within a repeat sequence (#repeat xxx), formatted as three digits, leading zero(s). Note that this token must be in the template if you plan to use ACP's automatic stacking feature!
$SETNUM
Image and cal files only: The set-loop number (starting with 1), formatted as three digits. This can be greater than 1 only if the plan includes a #sets directive.
$TEMP
The imager's cooler temperature, Celsius, formatted in whole degrees. Probably not useful for log files!
$TGTDEC
Image files only: The J2000 declination (degrees) of the target, formatted as +ddmmss, for example +024352 or -260533. Either a + or a - is always included. If the target is a solar system body specified using orbital elements or NEOCP ephemerides, this will reflect the declination at the time the image is acquired.
$TGTNAME
Image and cal files only: The name of the current target for light frames, or "dark" for dark frames, and "bias" for bias frames. If the target is a solar system body specified using orbital elements or NEOCP ephemerides, the name will be automatically extracted from the elements or ephemerides.
$TGTPA
Image files only: The equatorial position angle of the target (degrees, 0-360), formatted as ddd, for example 027.
$TGTRA
Image files only: The J2000 right ascension (hours) of the target, formatted as hhmmss, for example 071256. If the target is a solar system body specified using orbital elements or NEOCP ephemerides, this will reflect the right ascension at the time the image is acquired.
$TIMELOC
The local time, formatted as hhmmss, for example 061335.
$TIMEUTC
The UTC time, formatted as hhmmss, for example 061335.
$USRNAME
The login username of a web user, or "local_user" for plans run directly by the local user via the ACP console.
AutoFlat File and Folder Customization
The template strings for custom AutoFlat file/folder naming are part of the file AutoFlatConfig.txt. Rather than using a single template string as above, there are separate templates for folders and files. The format of each is similar to those described above, and appear in AutoFlatConfig.txt to produce the default/standard naming. Click this button
to open AutoFlatConfig.txt in Notepad now.
;
; Required folder name customization template. If using the default ACP image file
; template ($DATENITE folders) this will create an AutoFlat subfolder in the same
; folder that the images themselves go in.
;
FolderTemplate $DEFPATH\$DATENITE\AutoFlat
;
; Optional flat name customizing template
;
;FileTemplate AutoFlat-PA$FLATPA-$FLATFILT-Bin$FLATBIN-$FLATSEQ-$MERSIDE
This will result in flat frames going into an AutoFlat subfolder located in the same folder as your light images (assuming you have not customized those file folders/names). Note that the FileTemplate template string is commented out (leading semicolon). If you leave this commented out, the file names will be constructed internally per your system's capabilities (rotator or not, filters or not, GEM or not). If you specify a template for files, you are responsible for leaving out the pieces that are not applicable to your configuration.
If you have an AutoFlatConfig.txt from an older version of ACP, your AutoFlatConfig.txt may have only a FolderName config string. The current logic preserves compatibility with this older feature, so you will still have your autoflats in a folder directly under My Documents\ACP Astronomy. To activate the expanded features, remove the FolderName line and add the text above in its place. Updates to ACP do not replace your AutoFlatConfig file.
Substitution Tokens for FolderTemplate
The following substitution tokens may be used in the FolderTemplate template string:
$DATEJUL
The Julian date (no fractional part, just the date, for example 2453935 for 19-Jul-2006).
$DATELOC
The date in local time (per the Windows date/time control panel, time zone settings), formatted as yyyymmdd, for example 20060719. This format will sort alphanumerically in date order.
$DATENITE
The local date of the run (night), formatted as yyyymmdd, for example 20060719. This token is useful if you want to put all of your images from a single run/night into one folder. The date changes when the sun crosses the local meridian, thus the folder will remain the same even though the local date changes at midnight.
$DATEUTC
The UTC date, formatted as yyyymmdd, for example 20060719.
$DEFPATH
The default images folder as configured in ACP Preferences, Local User tab, for the local user, or the path to a web user's default image folder depending on ACP's web document root preferences). Normally your FlatFolder template will start with this token.
$DUSKDAWN
If the flat field is acquired during dusk, this will be Dusk, else it will be Dawn.
$TIMELOC
The local time, formatted as hhmmss, for example 061335.
$TIMEUTC
The UTC time, formatted as hhmmss, for example 061335.
Substitution Tokens for FileTemplate
The following substitution tokens may be used in the FileTemplate template string:
$DATEJUL
The Julian date (no fractional part, just the date, for example 2453935 for 19-Jul-2006).
$DATELOC
The date in local time (per the Windows date/time control panel, time zone settings), formatted as yyyymmdd, for example 20060719. This format will sort alphanumerically in date order.
$DATENITE
The local date of the run (night), formatted as yyyymmdd, for example 20060719. This token is useful if you want to put all of your images from a single run/night into one folder. The date changes when the sun crosses the local meridian, thus the folder will remain the same even though the local date changes at midnight.
$DATEUTC
The UTC date, formatted as yyyymmdd, for example 20060719.
$DUSKDAWN
If the flat field is acquired during dusk, this will be Dusk, else it will be Dawn.
$FLATBIN
The binning level of the flat field, for example 2.
$FLATFILT
The name of the filter used when the image was acquired, for example Luminance.
$FLATPA
The sky PA of the images for which the flats are acquired. This is the fourth parameter in a line of the flat plan. If there is no rotator present, this will be set to "NoRot", and is thus not useful in that case.
$MERSIDE
For a German Equatorial mount, this is the meridian side (East or West). See Rotator Support. Because the flats are always taken at the same area of the sky, this is not the same as the $MERSIDE for images. It is the $MERSIDE for which this flat is taken so you can match it up with images for the same $MERSIDE. If the mount is not German, this will be set to "NoGEM", and is thus not useful in that case.
$FLATSEQ
A three-digit sequence number for the flat within a group for one filter/binning/PA (one line of the Flat Plan), for example 012.
$TIMELOC
The local time, formatted as hhmmss, for example 061335.
$TIMEUTC
The UTC time, formatted as hhmmss, for example 061335.
$TEMP
The current cooler temperature of the main imager. May be a crazy number if the cooler is off (manufacturer-dependent).
Lost? Having trouble visualizing what is going on with customizing? Try the Template Generator Tool. Having trouble finding the image and log files themselves and/or the configuration files you may have already set up? Try the Where Are My Files? tool!