David's Astronomy Pages CCD Application User Guide Updated 2005-06-04 (Version 2.5.4)

Scripting

Introduction

This manual provides User Guide documentation for the CCD Imaging and Analysis Program, written by David Richards, Aberdeenshire, UK.  Further enhancements to this manual will hopefully be made available in future releases.  There are no screen captures, so please read in conjunction with the open program.

New Program Features

Version 2.5.4
Added enhancement to VMA script, that enables the program to calculate and report S/N., and also to calculate and report breakdown of image link/VMA successes and failures.  (Note that realtime VMA is now disabled in this version)

Version 2.5.0
Added enhancement to VMA script, that enables the program to obtain plate solutions via the PinPoint Engine.

Version 2.4.1
Added enhancement that moves auto-reduced images to subfolders named "B Cal", "V Cal", "R Cal", "I Cal" according to filter.

Version 2.4
New features in program version 2.4 are

Version 2.3  
Release version 2.3 contained Imaging Target Page (being a subset of more complete development version).   VMA Analysis was conducted in a separate program (VMA Version 1.5).

Back to Top

Installation

The CCD Imaging and Analysis Program is supplied within a ZIP file.  Unzip the file and extract all files to a new program folder. This can reside anywhere on the computer.  You may like to create you own shortcuts to "CCD_Application" and "ScriptController.hta". 

Earlier program versions will still operate (however only one copy of the program can be safely run at any one time).

If this is a very first setup of this program, it may 'be necessary to Install Windows Script Host (vn 5) on the computer. To install the latest version of Microsoft Windows Script Host (WSH) :
Go to Microsoft Windows Script Host [http://msdn.microsoft.com/scripting/]
     > Windows Scripting Host > Downloads. 
and follow the installation instructions. 
Or alternatively, run ste50en.exe from the "Orchestrate" folder.

In order to quickly utilise your previous settings (from version 2.3 and VMA 1.5), please copy into the new CCD 2.4 program folder area, the following two files : “CCD_Setup.dat” from your CCD 2.3 program area and  “vma_Setup.ini” from your Vma 1.5 program area.

Back to Top

Setting Up

Sky Version
The Program is set up to work with TheSky6   

The scripts can work with TheSky5, but the variable “SkyVersion” must be set to “5” in “CCD_Scripts.vb” (the Preferences tab must also be changed in CCDSoft)

Dec/Alt Limits
In order to help prevent accidental equipment damage the program uses Dec and Alt Limits, These are hard-coded, but can be set by changing the variables "gDecLimit" & "gAltLimit" in the file "CCD_Scripts.vb". These protections are additional and independent of any Dec and Alt Limits that are defined and activated within TheSky.

Despite these protections there are of course risks associated with using Telescope equipment unattended, therefore please read and note the disclaimer.

Base Folder
The Program assumes that you have created a Base Folder in which you will do your CCD Imaging Work. You will need to specify this folder in the Settings Set Up. The Program will create subfolders “New”, “Analysis” & “Logs”.   From inside the CCD Application you can create a Session Folder area  for holding the images taken (alternatively a Test Folder Area can be created).  In normal operation the Session folder will point to a location like “../new/2004-08-03 S00001”.  There is a facility to set CCDSoft's Autosave folder to the Session Folder area. 

[Note - it is entirely possible to work outside the Session Name/Folder structure, however the AutoSave Folder must be manually set to your own requirements each session ]

Targets Folder
You will need to create an area for holding Target List files.  This can reside anywhere on the computer, though it might conveniently be placed as folder within the Base Folder.  You may like to copy the example target and support frame list files from the supplied zip file ("Example_Targets.zip") to a "Targets" Folder

Back to Top

Opening the Program

The Program is activated by running “CCD_Application.hta”. The program assumes that CCDSoft and TheSky are capable of connecting to a Camera and Telescope. These could be to the respective Simulators. (Probably best for first testing).

Whilst the program will open TheSky and CCDSoft itself, it is recommended however that both of these SB applications are already open when starting the CCD_Application. This seems to reduce the chances of avoiding a situation where two CCDSoft Application processes are running.

It is useful to also open “ScriptController.hta”, as this provides the only safe mode for stopping or pausing a script.  This tool can be left open throughout the time that the CCD Application program is being used.  

(Make sure that you open the "ScriptController.hta" that resides in the same program folder as CCD_Application.hta” otherwise script control will not work )

Back to Top

Main Page

The Opening Screen provides the Main Menu with buttons that access to following screens

• Session Setup (for Setting Program and Session Parameters)
• Target Imaging (for automated acquisition of target images)
• Bias, Darks & Flats (for taking support frames)
• VMA Analysis (Variable Star Magnitude Analysis tool)

The screen also provides a reminder of certain key program parameters : session name, image scale, camera orientation, TheSky version, Declination Limit and Altitude Limit (Note that the later 3 items are hard-coded. Changing the values is described in the Installation Section)

Back to Top

Session Setup Page

The Session Setup Screen provides access to settings that control aspects of the program execution.

Session [special field]
Name of Imaging Session.  The Session Name is normally generated automatically using either New Session or Test Session buttons.   However the Session Name can be entered manually.

The session name can be used for setting CCDSoft's Autosave Folder to a named folder area. This is done using the "Set Autosave Folder" button. 

Note - it is entirely possible to work outside the Session Name/Folder structure, however the AutoSave Folder must be manually set to your own requirements each session

New Session [button]
This button creates a New Session name,  creates a series of subfolders and subject to user confirmation sets the Autosave folder.  The standard format of the session name is  YYYY-MM-DD S00000 where S00000 is the imaging session number, derived by incrementing the Last Session No.    (please refer to details on AutoSave Folder below)

Last Session no [numeric field]
This fields automatically increments by one each time a New Session is created.  The field can be overwritten if necessary.

Test Session [button]
This button creates a Session Area for Testing, using the Session Name in the format "YYYY-MM-DD TEST".   Subject to user confirmation the function also sets the Autosave folder. 

Image Scale [numeric field]
This field is for specifying the Image Scale of 1x1 binned images for the optical setup being used. This is in arc secs/pixel.  Image Scale at 2x2 and 3x3 are derived from this number.  This field is important for ensuring images can be correctly linked during Real Time VMA or when taking Locate Images.

Camera Orientation [numeric field]
This field is for specifying the Camera Orientation. For ST7/ST8 camera 180 is the leads up position. (This field is ?used to help reduce false matches during Image Linking)

Save Folder  (Path) [text field]
This special field will either show the AutoSave folder path that has been set following the creation of a New or Test Session, or alternatively can be used for specifying an AutoSave Folder Path that can then be set using the "Set AutoSave Folder" button.

Set AutoSave Folder  [button]
This button will set the AutoSave Folder held in CCDSoft, but how it does this depends on the "Save Folder (Path)"  field :

If the "Save Folder (Path)" field is blank, AutoSave Folder will be set to a name constructed from Base Folder Path/New/Session Name.
    e.g.  “C:/../CCD Imaging/New/2004-08-03 S00001”

Alternatively if the "Save Folder (Path)" field is not blank, ie contains a folder path, the AutoSave Folder will be set to the specified Folder.

Notes:
1) The  "New Session" and "Test Session" functions will automatically offer to set AutoSave Folder.

2) Only try to Set Autosave Folder AFTER selecting the Camera in CCDSoft's Camera Control Setup. If you later change the Camera in CCDSoft  the autosave folder details will be overwritten.   

3) It is strongly recommended that the Autosave Tab on Camera Control is not open, when trying to Set AutoSave Folder using this button.   Problems have been reported whereby CCDSoft's Starting number resets itself to "1"

4) It is entirely possible to work outside the Session Name/Folder structure, however the AutoSave Folder must be manually set to your own requirements each session

Base Folder  (Path) [text field]
This field is for specifying the folder path to an area set aside for CCD Imaging Use. Subfolders are created within this area.

Targets Folder (Path)  [text field]
This field is for specifying the folder path to a folder that will contain Targets Files, Dark Set Files, Flat Set Files etc.

Camera Type [text field]
This field is for specifying the Camera Type e.g. ST-7
(This field is possibly not used for anything in Version 2.4)

Focal Length [text field]
This field is for specifying the Total Focal Length of the Optical System. 
(This field is possibly not used for anything in Version 2.4)

Save Image Options 
In this section there are checkboxes that control how Image and Support Frames are saved.
(You will need scroll down to bottom of window to see these)

Save Bias, Dark and Flat Frames in Separate Support Folders [Checkbox]
This box (when checked) enables the saving of support frames to separate subfolders, named "_BIAS", "_DARKS" and _FLATS".  

Rename Support Frames [Checkbox]
This box (when checked) enables the renaming of support frames to permit easier identification and potential further separation. Frames are renamed in format as per following examples

BIAS.-20c_2x2.00000001.FIT
DARK.-20c_2x2_20s.00000001.FIT
FLAT.-20c_2x2_2s.00000001.FIT   (no filter)
R_FLAT.-20c_2x2_2s.00000001.FIT (R Filter)

Save Reduced Frames in Separate Folder [Checkbox]
This box (when checked) enables the saving of reduced frames to a separate subfolder, named "_REDUCED".  This may be useful for workflows which require the rapid separation of raw and auto-reduced frames for quick data analysis.  In Version 2.4.1 auto-reduced images are saved to subfolders named "B Cal", "V Cal", "R Cal", "I Cal" according to filter.

Time Settings
There are fields for specifying the time that the program should use for the following activities

Locate Image Exp [Numeric Field]
The exposure length (in secs) to be used for taking Locate Images.  This should be long enough to record sufficient stars to permit reliable image linking, but not too long that it wastes time.

Delay after Slew [Numeric Field]
The delay (in secs) to be used between a slew and the first image thereafter. This is to provide time for the telescope tube/mount to completely stablise after movement.

Delay after Jog [Numeric Field]
The delay (in secs) to be used between a telescope jog and the first image thereafter. This is to provide time for the telescope tube/mount to completely stablise after movement.

Time Estimate
There are fields for specifying the estimated time that it takes the system to perform specific activities. This is used by the program for estimating expected run time of a Target Files or Flat/Darks Sets .

Download (1x1) [Numeric Field]
The time (in secs) to download a 1x1 binned image

(2x2) [Numeric Field]
The time (in secs) to download a 2x2 binned image

(3x3) [Numeric Field]
The time (in secs) to download a 3x3 binned image

Typical Slew [Numeric Field]
The typical time taken (in secs) to perform a telescope slew.

Typical Image Link [Numeric Field]
The typical time taken (in secs) to perform an image link & locate

Filter Wheel Setups 
In this section there are fields that allow up to 3 different filter setups to be defined and stored, eg RGB, CBRVI & CUBVR. For each Filter Set, specify a Set Name, Default Filter No. and the Names of the various Filters  (Version 2.4 only provides support for "5 filter" filter wheel) , eg

Name :	RGB		[Text Field]
Default Filter No:	4		[Numeric Field] (usually no. for the clear filter)
Filter 1:	Red		[Text Field]
Filter 2:	Green		[Text Field]
Filter 3:	Blue		[Text Field]
Filter 4:	Clear		[Text Field]
Filter 5:	Lunar		[Text Field]

Filter Set [button]
This button allows the user to toggle between 3 different filter setups defined or to specify no Filter Wheel.  It is up to the user to ensure that the Filter Setup defined and selected matches the actual filters in use within the Filter Wheel.

RealTime VMA Alerts 
In this section there are fields that control the alert levels for highlighting unusual Brightening or Dimming of Stars, when using the Real Time VMA option

Mag Diff Hurdle (in mag) [Numeric Field]
This helps to define the Alert Threshold by providing the program with knowledge on the reliability of magnitude estimation.  Try 0.1 as a starter.  Setting the parameter to a lower number increases the sensitivity of the alert facility but might give more false alarms.  Setting to a higher number reduces the number of false alarms (for setups where the repeatability of magnitude estimation is not good). 

Mag Rate of Change Alert Filter  (in mag/day) [Numeric Field]
This helps to define the Alert Threshold by specifying the rate of magnitude change that is deemed significant. Try 0.1 mag/day as a starter.    Setting the parameter to a lower number increases the sensitivity of the alert facility but might give more false alarms. Setting the parameter to a higher number reduces the number of false alarms. 

<< Main Menu >> [button]
This button saves the settings and return to the Main Menu Screen.

 Back to Top

Target Imaging

The "Target Imaging" screen provides access to facilities to acquire images based on files specifying list of targets and details about the required  Binning, Number of Frames, Exposure and Filters.  There are options to either take the set of targets once or cycle round to repeat the set of targets.  There are other realtime options that include Taking a Locate Image (to allow for poor telescope pointing or alignment), Using Auto-Reduction or Performing Realtime VMA (variable star magnitude analysis).   Monitoring of CCD Temperature is performed during acquisition of support frames and warnings are given if Temperature drifts from the Setpoint or Cooling capacity rises above 90%.  

Live/Test Mode [information field]
This field shows whether the program is currently in  LIVE or TEST mode (using Switch Modes button). Imaging is of course normally performed in LIVE mode.  

In TEST mode, the script is designed for quickly testing the scripts and would normally be used when also working with Telescope and Camera Simulators. In this mode exposure times are substituted with quick 1 sec exposures and and there are no delays before exposures are taken. If a real image is active in CCDSoft when the script runs, the 'Use Locate Image' part of the script can be tested.   Image Reduction may fail when using the Simulator camera,  so test with a live camera if fully exploring this option. 

Switch Mode [toggle button]
This button toggles between LIVE and TEST mode.  

Image Scale [information field]
These fields display the expected image scale (in arc secs/ pixel) at 1x1, 2x2 and 3x3 binning. These are dependant on the Image Scale that is specified on the Session Setup Page . It is used to correctly link & locate images, taken when using the Locate Images Option. 

Targets File [text field]
This field contains the name of a Target File that will be used when Taking Target Images. The file should be one that resides in the Targets Folder (Only the file name should be given, not the full file path). 

The Targets File Format is described in a special section on File Formats.

Airmass Cutoff [numeric field]
This field specifies the largest airmass that a target can have for imaging.  If the Airmass of a Target lies lower in the sky than this Airmass equivalent, the Target will be skipped.

If you don't wish to be restricted by Airmass Cutoff use a fairly large number, such as 10.

Take Images (Once) [button, activates a run time script]
This function with acquire a sequence of Targets that are specified in the Targets File. After reaching the end of the target list, the script stops. 

Take Image (Cycle) [button, activates a run time script]
This function with acquire a sequence of Targets that are specified in the Targets File. After reaching the end of the target list, the script cycles back to the first target in the list. 

This script will continue indefinitely whilst running, this is useful if it is required to repeatedly image a certain set of targets throughout an evening or entire night. The observer for example returning in the morning to close down the observatory.

The script is ended by using the Script Controller facility.

Estimate Run Time [button]
This button will estimate the run time that will be involved in acquiring Target listed in the Targets File.  This value shows the estimated time for a single cycle of operation.  The expected run time assumes that all targets are i) valid objects in TheSky,  ii) visible at the time of imaging and iii) lie within acceptable alt/dec/airmass limits.

Options
A number of options are available for controlling Target Imaging, including specific modules such as Auto-Reduction and Realtime VMA.

Option : Ignore Cutoff for Rising Targets  [checkbox]
This option (when checked) will ignore the airmass restriction for rising objects. i.e. the specified Airmass Cutoff will only apply for setting objects.  This option only works correctly when viewing from Northern Hemisphere. The option allows rising objects to be imaged as soon as they become visible.

Option : Imaging Mode [radio buttons]
When taking images using 2 or more filters, this option (activated using radio buttons) allows user choice over the order in which images are acquired.  This is best described using an example in which 3 frames are being taken using R and V filters.  In "Mode 1" images will be taken in the order RRR VVV, whilst in "Mode 2" images will be taken in the order RV RV RV.  With "Auto" option selected the script will use Mode 1 when number of frames is less than or equal to a specified cutoff and will use Mode 2 when number of frames is greater than the cutoff.

Option : Take Locate Images [checkbox]
This option forces the script take an initial 'locate' or pointing' image after slewing to each target.  The 'locate' image is then used to identify the precise location where the telescope is pointing, and then jog the scope to try to centre the target object.

This option is useful if you telescope pointing is inaccurate or you get significant drift over the course of a night.   Where telescope pointing and alignment is good, and when using large CCD Arrays with smaller focal lengths this option may not be required.

Duration of the 'Locate' image is specified on the Session Setup Page

Option : Use Auto-Darks [checkbox]
The “Use Auto-Darks” option enables the use of CCDSoft facility to take a Dark Image and subtract this from the Raw Image, to give a quick & rough reduction.

The “Use Auto-Darks” option is still retained in 2.4, but should eventually become redundant if Auto-Reduction proves to work effectively (see below)

Option : Use Auto-Reduction [checkbox]
The “Use AutoReduction” option enables the use of CCDSoft Reduction Groups to reduce raw images ‘on the fly’.  The program uses a lookup file called  “CCD_autoreduction.dat”, which has columns defining the Reduction Group to use for specific combinations of Bin, Exposure, Filter and optionally Temperature.  

See section on Auto-Reduction for more information.

Option - "Save Reduced Frames in Separate Folder" [checkbox on Setup Screen ]
This option (which is selected via a checkbox setting near the bottom of the Session Setup Screen)  enables the saving of reduced frames to a separate subfolder, named "_REDUCED".  This may be useful for workflows which require the rapid separation of raw and reduced frames for quick data analysis. In Version 2.4.1 auto-reduced images are saved to subfolders named "B Cal", "V Cal", "R Cal", "I Cal" according to filter.

Option : Use Real time VMA [checkbox]
The “Realtime VMA” option enables the realtime variable star magnitude analysis, including the alerting of star dimming and star brightening events.  

See section on Auto-Reduction for more information.

Target Set List [text field]
This field contains the name of a Target Set List file that will be used when performing a series of Imaging Operations. The file should be one that resides in the Targets Folder (Only the file name should be given, not the full file path). 

The Target Set List File Format is described in a special section on File Formats.

Take Target Set [button, activates a run time script]
This button  runs a script that reads a Target Set List File, and carries out the specified Imaging Operations, such as Imaging Targets listed in a Targets Files, taking Mosaics, or Taking Dark/Bias  Frames. Any number of operations can be specified (the limit will be controlled in practice by the length of time available before dawn).  The operations list can be supplemented or changed whilst the script is running. This is handy if you decide you wish to cutout or substitute one set of later imaging activity with another, without having to stop/restart the imaging of current targets.

This script doesn't cycle round, but a certain Targets List can be specified as many times as required. For example the Target Set could be specified to take some variable stars (file1), repeat the variable stars (file 1), then image a series of galaxies (file 2) , a couple of comets (file 3), take some darks frames (file 4) and then finally go back to repeat the variables again (file 1, file 1).

Estimate Run Time [button]
This button will estimate the run time that will be involved in acquiring Targets and Images specified through the Target Set File and Associated Files.  The expected run time that is reported assume that all targets are valid targets,  visible at the time of imaging and lie within acceptable alt/dec/airmass limits.

Current Status [information fields]
A number of fields provide status information when Target Acquisition is in progress. These are as follows:

Last Set :
Current Set :
Current Object :
Current Frame :
Est Time Left : (in hours, mins & secs)

The Est. Time Left field shows the estimated time left. This values reduces as Imaging progresses. The number assumes that all remaining  targets are valid targets,  and will be visible and lie within acceptable alt/dec/airmass limits. 

Status [information field]
This scrolling area provides a log of program activity.  During operation of a script the window may temporarily go blank if another window  is moved over the top of the Program window.  Status information should appear again when the program writes further information. 

The information shown in the Status field is also written to a "report.htm" file [more info]

<< Main Menu >> [button]
This button returns to the Main Menu Screen.

Notes

FITS Header - Custom Information
A variety of custom information is recorded in the FITS header of images acquired. This includes 

COOLING  - Cooling Capacity of Camera at time of image (in %)
AIRMASS  - Airmass at the Image Centre
FILTERNO - Filter Number (1 to 5)
FILTERX  - Filter name as used in CCDSoft 
FILTER   - Filter Name as used by CCD Imaging Program.

Where Auto-Reduction is being used the Reduced Image will contain a further FITs header item
AUTOREDN  -  Name of Reduction Group used for Auto-Reduction

Custom information is also written to RAW images when using Auto-Reduction. The script does this by re-opening the RAW file after Auto-Reduction has been completed. (This only succeeds if Auto-Reduction is successfully performed).

Auto-Reduction Failures
Should CCDSoft throw an error during Auto-Reduction (e.g. if Bin Size/Pixel Area is incorrect or there is some other problem such as a  “Memory Error” if using the Simulator Camera) a .RAW frame will still be produced. However the script is currently unable to recognise this and simply assumes that the image has completely failed and won't report the image in the report.htm or log file. 

In such situations the raw image will also not contain any of the custom written FITS information.  FILTER will be the Filter name as used in CCDSoft (e.g.  with photometric filters FILTER may show "Blue" in such raw files instead of "B" if auto-reduction had been successful).

See section on Auto-Reduction for more information on this option.

Back to Top  

Program Status / Report Files

Program script status information is sent to a Status Area at the bottom of the principal pages (Target Imaging, VMA Analysis).  

This information is also directed to a “report.htm” file (overwritten each time the program is run) and also to a time-stamped file ( eg report_20040720_1833.htm, which is available for record keeping).  

If you open the report.htm file in a web browser you can use its Refresh button to keep an eye on imaging progress even when the Program Window goes blank when it is busy on an operation.

Monitoring of CCD Temperature is performed during acquisition of both target and support frames and warnings are given if Temperature drifts from the Setpoint specified in CCDSoft or Cooling capacity rises above 90%.  

A Log file is written for each Session. Information is appended to a log file based on the Session name, ie a new log file is only opened if New Session is created.. 

Back to Top

Aborting or Pausing the Program

It is not possible to directly stop or interact with the Program when it is busy running a script.  However the script can be Paused or Aborted indirectly via a separate program. Open “ScriptController.hta” and click on the relevant button.  

Note that if the script is in the middle of taking a long exposure, the program won't actually pause or abort until after the current image has been completed and downloaded.

In 2.4 it is not necessary to press Resume after using Abort, as the CCD Program will now clear the lock file itself.  

(Make sure that you open the "ScriptController.hta" that resides in the same program folder as CCD_Application.hta” otherwise script control will not work )

 Back to Top

Auto-Reduction

The “Use AutoReduction” option enables the use of CCDSoft Reduction Groups to reduce raw images ‘on the fly’ as they are taken.  These reductions groups need to contain appropriate Support Frames (Bias, Darks & Flats) as appropriate for Reduction.   The user must ensure that the Reduction Group/Support Frames are suitable for the task required, otherwise images will not be appropriately reduced.

How does the program know which Reduction Group to use ?.  Well it uses a lookup file “CCD_autoreduction.dat”, which has columns defining the Reduction Group to use for specific combinations of Bin, Exposure, Filter and optionally Temperature.  

The Auto-Reduction List File Format is described in a special section on File Formats.

You create your reduction groups in CCDSoft and then edit the lookup file to your requirements.  Obviously this system will be easiest to operate with if your imaging sessions are using consistent CCD temperatures and exposure times and ideally have a Camera/Telescope setup that remains completely fixed between sessions so that you can reuse flats from earlier sessions as much as possible. 

1        2         3         4         5         6
12345678901234567890123456789012345678901234567890
Bin|Exp |Filter |Temp |Reduction Group      |
2   20   R             2x2 R 20s
2   10   V             2x2 V 10s
2    5   V             2x2 V 5s
2    2   R             2x2 R 2s

The script checks that the Reduction Group name in the Lookup List is a valid Reduction Group in CCDSoft. If a Group is not recognised the script continues but a warning is posted.  There is still opportunity to Cancel the “Take Targets” run and edit/correct the Lookup file or CCDSoft without having to exit the CCD Program.

If using a large number of different exposure settings,  say  0.11, 0.2, 0.3, 0.5, 0.6, 1, 2, 3, 5, 8, 10, 15, 20 sec exposures for R and I (Infrared) and say 0.3, 1, 2, 3, 5, 10, 20, 30, 40, 60 sec exposures for V, that represents a total of 36 Reduction Groups that you would need to maintained.   Its quite a pain to have to re-select Flat Field files data for each of 36 reduction groups when optical setup or camera orientation is changed.  However by using Automatic Dark Exposure Correction  the number of Reduction Groups you need to maintain suddenly drops to just 3  - or more specifically 3 per temperature setting .  Sounds tempting.

With Automatic Dark Exposure Correction you might then have a simple Reduction Group look-up file which had following rows.  This would be for the case where you update the Dark Frames for the specific CCD Temperatue that you are using for the night.

Bin|Exp |Filter |Temp |Reduction Group      |
2        R             2x2 R 
2        V             2x2 V 
2        I             2x2 I

Alternatively you might have a lookup file which looked like the following example if you regular switched between say 2 CCD temperatures depending on local climate variation.  CCD Temperature reported by the CCDSoft Camera object generally fluctuates +/- 0.3 deg C during operation. The program scripts use a +/- 0.5 degC tolerance when selecting a Reduction Group based on Temperature to overcome this.

Bin|Exp |Filter |Temp |Reduction Group      |
2        R      -10    2x2 R -10c
2        V      -10    2x2 V -10c
2        I      -10    2x2 I -10c
2        R      -15    2x2 R -15c
2        V      -15    2x2 V -15c
2        I      -15    2x2 I -15c

If you have a row where Exp and/or Temp are explicitly defined the script will use that reduction group in preference to a more generalised row.  If the explicit row doesn’t match the script falls back to the general case. For example for the following reduction file 

• Reduction “2x2 R” would be used if you were imaging in R at -12 deg C (you would need to ensure that “2x2 R” had Dark Frames for -12 deg C).    
  
• Reduction “2x2 R -10c 60s” would be used if you were imaging in R at -10 deg C for 60 sec.   But for any other exposure the script would use “2x2 R -10c”  (you would need to ensure that “2x2 R -10c 60s” had Dark Frames for -10 deg C and 60s exposure, and that “2x2 R -10c”  had Dark Frames for -10 deg C and had Automatic Dark Frame Compensation

Bin|Exp |Filter |Temp |Reduction Group      |
2        R      -10    2x2 R -10c
2        V      -10    2x2 V -10c
2        I      -10    2x2 I -10c
2   60   R      -10    2x2 R -10c 60s
2        R             2x2 R 
2        V             2x2 V 
2        I             2x2 I 
2        R             2x2 R 60s

Back to Top  

Bias, Darks & Flats

The "Bias, Darks and Flats" screen provides access to facilities to assist the acquisition of support frames.  Buttons permit the rapid definition of settings such as Binning, Number of Frames, Exposure and Filter.  There are also options to read and acquire a predefined list of darks or flats. There is also an option to take flats in selected filters with exposure automatically calculated based on a specified target ADU count.  The scripts are set up for taking full frames (ie no sub- frame imaging is supported).  Monitoring of CCD Temperature is performed during acquisition of support frames and warnings are given if Temperature drifts from the Setpoint or Cooling capacity rises above 90%.  

Live/Test Mode [information field]
This field shows whether the program is currently in  LIVE or TEST mode (using Switch Modes button). Acquisition of Support frames should be performed in LIVE mode.  

In TEST mode, the script is designed for quickly testing the scripts and would normally be used when also working with Telescope and Camera Simulators. In this mode exposure times are substituted with quick 1 sec exposures. If a real image is active in CCDSoft when the script runs, the 'Use Locate Image' part of the script can be tested.   Image Reduction will normally fail when using the Simulator camera,  so test with a live camera if exploring this option. 

Switch Mode [toggle button]
This button toggles between LIVE and TEST mode.  

Binning [toggle button]
Bin Mode button allows selection of 1x1, 2x2 or 3x3 binning.

No. of Frames [numeric field] & [buttons]
Number of required Frames can be specified by either typing in a number or selecting one of the custom buttons. 

Exposure [numeric field] & [buttons]
Exposure (in secs) can be specified by either typing in a number of selecting on the custom buttons.  Exposure length is used when taking either Dark or Flat Frames. (Bias Frames are automatically taken with ~ 0 sec duration)

Filters [information field] & [buttons]
Filter to be used is specified by clicking on one of 5 buttons.  The Filters being used are defined on the Session Setup Page.   It is of course up to the user to ensure that the filters listed in the CCD program match up with those being used with the Camera.   It is strongly recommended (but not actually required for operation) that the names in CCDSoft also match up.  

Take Bias Frames [button, activates a run time script]
This button will run a script to collect the specified number of bias frames at the specified binning.  

Take Dark Frames [button, activates a run time script]
This button runs a script to collect the specified number of dark frames at the specified binning and exposure time.

Take Flat Frames [button, activates a run time script]
This button runs a script to collect the specified number of flat frames at the specified binning and exposure time using the specified filter. It is up to the user to select an appropriate exposure.  

(A "Trial Flat" facility is available to take a single flat frame that can then be inspected first before committing to multiple exposures. Alternatively a "Take AutoExp Flat Set" facility is available that will automatically select an optimum exposure time)

Trial Flat [button, activates a run time script]
This button runs a script to collect a single flat frame at the specified binning and exposure time using the specified filter (if filters are being used). This Trial Flat is not saved, as it is intended as a quick check of exposure setting before committing to acquiring and saving multiple flats. 

Auto Expose Flats
This facility enables the collection of the specified number of flat frames at the specified binning and for 1 or more specified filters. The exposure is automatically calculated. To use the facility enter the ADU count that you wish the flat frame to have (eg 22000) and tick the filters that you wish to take flats for.  Then click the "Take AutoExp Flat Set" button. This starts a scripts that takes trial flats and calculates recommended exposure times.  These are presented to the user who then has the option to continue or cancel.

Flats Req'd  [checkboxes]
Series of checkboxes that specify the Filters for which Flats will be acquired. 

Req'd Flat Count  [numeric field]
This field specifies that flat count (in ADU) that Auto-Exposure will attempt to achieve. 

Take AutoExp Flats [button]
This button begins the script to take auto-exposed flats. 

Save Options
A couple of save options are available to control the way that Support Frames are saved. These are specified via checkboxes located at the bottom of the Session Setup Screen

 "Save Bias, Dark and Flat Frames in Separate Support Folders" [checkbox on setup screen]
This option (which is selected via a checkbox setting near the bottom of the Session Setup Screen)  enables the saving of support frames to separate subfolders, named "_BIAS", "_DARKS" and _FLATS".  This may be useful for workflows which require the rapid  separation and use of support frames at the beginning of an observing session.

"Rename Support Frames" [checkbox on setup screen]
This option (which is selected via a checkbox setting near the bottom of the Session Setup Screen)  enables the renaming of support frames to permit easier identification and potential further separation. Frames are renamed in format as per following examples

BIAS.-20c_2x2.00000001.FIT
DARK.-20c_2x2_20s.00000001.FIT
FLAT.-20c_2x2_2s.00000001.FIT   (no filter)
R_FLAT.-20c_2x2_2s.00000001.FIT (R Filter)

Darks Set  [text field]
This field contains the name of a Darks Set List file that will be used when taking a series of different Dark Frames (eg for compiling a library of Darks). The file must exist in the "Targets" Folder and use the correct file column format.  (Only the file name should be given, not the full file path).  By specifying an Exposure of  0 secs, Bias Frames can be also be taken. Note that the Darks are only taken at the Current Temperature.  The program does not control CCD temperatures (though Temperatures are monitored and any discrepancies reported)

The Darks Sets File Format is described in a special section on File Formats.

Take Dark Sets [button, activates a run time script]
This button runs a script that read a "Darks Set" file and acquires one or more Dark/Bias Sets based on specifications contained in the named file. 

Estimate Run Time [button]
This button will estimate the run time that will be involved in acquiring the Dark Sets based on specifications in the file provided.

Flats Set  [text field]
This field contains the name of a Flats Set List file that will be used when taking a series of different Flat Frames (eg for compiling a regular set of Flats). The file must exist in the "Targets" Folder and use the correct file column format.  (Only the file name should be given, not the full file path). To be useful lighting conditions for taking flats need to be similar between sessions.

The Flats Sets File Format is described in a special section on File Formats.

Take Flat Sets [button, activates a run time script]
This button runs a script that read a "Flats Set" file and acquires one or more Flat Sets based on specifications contained in the named file.  

The Flats Sets File Format is described in a special section on File Formats.

Estimate Run Time [button]
This button will estimate the run time that will be involved in acquiring  Flat Sets based on specifications in the file provided.

Est. Time Left [information fields]
The Est. Time Left field shows the estimated time left (in hours, mins & secs). This values reduces as Support Frame acquisition progresses. 

Status [information field]
This scrolling area provides a log of program activity.  During operation of a script the window may temporarily go blank if another window  is moved over the top of the Program window.  Status information should appear again when the program writes further information.     

The information shown in the Status field is also written to a "report.htm" file [more info]

<< Main Menu >> [button]
This button returns to the Main Menu Screen.

Notes

FITS Header - Custom Information
Additional custom information is recorded in the FITS header of support frames acquired.  

BIAS and DARK Frames have the following additional data written.

COOLING  - Cooling Capacity of Camera at time of image (in %)

FLAT Frames have the following additional data written.

COOLING  - Cooling Capacity of Camera at time of image (in %) FILTERNO - Filter Number (1 to 5)
FILTERX  - Filter name as used in CCDSoft 
FILTER   - Filter name as used by CCD Imaging Program.

Back to Top

VMA Analysis (Variable Star Magnitude Analysis) 

Work Folder [text field]
Full path name to folder area where Analysis Work is conducted.   Images should exist in subfolders within the Work Folder.

Image Scale [numeric field] 
Image Scale (in arc secs/pixel) of the images to be analysed. 
(This field is independent of the Image Scale specified in the Session Setup, the latter is used for realtime imaging)

Plate Solution : [radio button group] 
Method to be used for performing Plate Solutions (if for inserting WCS).

CCDSoft/TheSky [ radio button]
This mode employs Software Bisque applications (CCDSoft/TheSky) to perform the Plate Solution

PinPoint [ radio button]
This mode uses PinPoint application engine to perform the Plate Solution.

(If the PinPoint engine is to be used to perform plate solutions, then for the time being the variable "PinPoint_StarCatalog" near top of CCD_Scripts.vb must be set to the pathname of star catalogs to be used by PinPoint.  

Note that there are other hard-coded variables that are used to control the operation of astrometry/photometry, please refer to the CCD_Scripts.vb file. 

Method 1.2 [radio button] - Comparison Method 
When checked this specifies Variable Star Magnitude Analysis using Comparison Method  method (1.2)

Reference File [text field]
Full file path to 1.2 reference file to be used for the analysis. 

Results File [text field]
Name of the file that will contain the 1.2 magnitude results . This is saved in the work folder.

Method 1.3 [radio button] - All Sky Method
When checked this specifies Variable Star Magnitude Analysis using All Sky Method  (1.3)

Reference File [text field]
Full file path to 1.3 reference file to be used for the analysis. 

Results File [text field]
Name of the file that will contain the 1.3 magnitude results . This is saved in the work folder.

Band Folders [text fields and checkboxes]

Up to 5 subfolder of images can be analysed  (nominally representing 5 filter bands).
Enter the subfolder name.  Checking the subfolder will indicate analysis is required. Unchecking the subfolder indicates that analysis is not required.

Note : Whilst the VMA program notionally operates on individual Band folders (eg R, V and I ), it doesn’t actually care about folder contents, such that all REDUCED files could be placed in one subfolder as the VMA program uses the FITS keyword FILTER for assessing the  Filter Band used by an image not the explicit name of the folder.

Save Settings [button]
This button will save the specified settings for future analysis.

Reset Settings [button]
This button will revert to the settings that were last saved.

Start Analysis [button, activates a script]
This button will begin Analysis of images in specified subfolders used the specified method and reference file. 

<< Main Menu >> [button]
This button returns to the Main Menu Screen.

Back to Top

Real time VMA

The “Realtime VMA” option enables the realtime variable star magnitude analysis. This uses the VMA Comparison Star (1.2) Method to analyse variables after each image is taken.  It uses the 1.2 Reference Data file specified on the VMA Analysis Screen. Besides writing data to results file, results are written to a “vma_pastmagvalues.txt” file - these results will be used in subsequent sessions.  

With this option activated the script will post alerts to star dimming and star brightening events. Thresholds are dependant on two global values specified on the Session Setup Page.

Mag Diff Hurdle (in mag) - this helps to define the Alert Threshold by providing the program with knowledge on the reliability of magnitude estimation.  Try 0.1 as a starter.  Setting the parameter to a lower number increases the sensitivity of the alert facility but might give more false alarms.  Setting to a higher number reduces the number of false alarms (for setups where the repeatability of magnitude estimation is not good). 

Mag Rate of Change Alert Filter  (in mag/day) - this helps to define the Alert Threshold by specifying the rate of magnitude change that is deemed significant. Try 0.1 mag/day as a starter.    Setting the parameter to a lower number increases the sensitivity of the alert facility but might give more false alarms. Setting the parameter to a higher number reduces the number of false alarms or to ignore background brightening which is below the level of flare-ups being looked for.

When Real time VMA is running,  variable star or flare-up alerts are flagged for brightening/dimming in magnitude compared to observations from i) the most recent previous session, ie > 12 hours ago and ii) the current session ie minutes or hours ago.

Variable Star estimates are saved in file called "CCD_PastMagValues.txt". There is a possibility that with prolonged use this .txt file could become large in size and slow down performance.  Until a script is written to 'clean-out' the file, it is possible to manually remove rows from the file, provided that the file format is retained.

In order to calculate how long ago previous estimates were made, it necessary to calculate the difference between the previous Julian Date of the previous estimate and the current Julian Date. With TheSky6 it is relatively straightforward to get the current Julian Date via an Object call, however there is no direct access to Julian Date in TheSky5 and as a workaround a single short CCD Image is taken, in order to 'steal' its Julian Date.

When using TEST mode, previous magnitude values are generated that will force brightening and dimming events to test detection.  Calculated Magnitude values are not written to the “vma_pastmagvalues.txt” when in Test Mode.

Back to Top  

File Formats 

File formats are specified below for 

1) Targets File
2) Target Set List File
3) Auto-Reduction List File
4) Darks Set File
5) Flats Set File 
6) Mosaic Set File 
7) Mosaic Frame Coordinates File

1) Target File Format
The Target file must use the format shown in the "example_targets.txt" file. Format is also shown below.  Please stick closely to using this format (avoid inserting Tabs, just use spaces when editing). There are 3 header rows which are skipped when reading the file.

Con [text] - a three-letter free format field, normally used for the giving the constellation of the target.  The field can be used for specifying the Landolt Field Number (eg 110) or simply VAR to highlight variable star targets.  The field is used for reporting status during run.

Name [text] - The Name of the Target, as recognised by TheSky. To be accessible the appropriate database may need to be active in TheSky.

Short Name [text] - A short name for the Target. 
(It is not certain how this field is used in the current version)

Jog N/JogW [numbers in arc mins] - When specified these values will jog the scope a specified amount from the Target Object, in situations where it is required to 'frame' the target in a particular way. Normally these values will be 0.
Use -ve numbers for jogs to S or E.

Bin [number ] - Binning required :  1 for 1x1 binning or 2 for 2x2 binning

Exp1 to Exp5  [numbers in secs ] - Exposure settings to be used. If Filter Wheel is being used then Exp1 refers to exposure through Filter 1, Exp 2 refers to exposure through Filter 2 etc. Use blank or 0 for no images.  

Frames  [number] - Number of Frames to be taken for each Filter/Exp setting. 

Delay  [number in secs] - When Specified this adds a delay before taking the first image for the target. This is normally only used when taking time lapse images.

RA (for Sort)   [text] - This is a user field for personal sorting of the Targets.

2) Target Set List Format 
The Target Set List file must use the format shown in the " example_set.txt " file. Format is also shown below.  Please stick closely to using this format (avoid inserting Tabs, just use spaces when editing). There are 3 header rows which are skipped when reading the file.

1         2         3         4         5         6 123456789012345678901234567890123456789012345678901234567890 Use|Type---------|Name------------------------------| 1   FILE          Variables01.txt 1   FILE          Variables01.txt 1   FILE          Andromeda_Galaxies.txt 1   FILE          Current_Comets.txt     MOSAIC        Mosaic_M101.txt 1   DARK          20s_Darks.txt   1   FILE          Variables01.txt 1   FILE          Variables01.txt

Use [text] - a flag  to indicate that operation should take. 1 to do operation, blank to skip operation.

Type [text] - The Type of Operation/File Format for Operations.

FILE - Targets File
DARK - Dark Set File
MOSAIC - Mosaic Set File

Name [text] - name of File containing Imaging Specifications. The file should be one that resides in the Targets Folder (Only the file name should be given, not the full file path). Format of the file should match that indicated in the Type field.

Notes
Any number of operations can be specified (the limit will be controlled in practice by the length of time available before dawn).  The operations list can be supplemented or changed whilst the script is running. This is handy if you decide you wish to cutout or substitute one set of later imaging activity with another, without having to stop/restart the imaging of current targets.

This script doesn't cycle round, but a certain Targets List can be specified as many times as required. For example the Target Set could be specified to take some variable stars (file1), repeat the variable stars (file 1), then image a series of galaxies (file 2) , a couple of comets (file 3), take some darks frames (file 4) and then finally go back to repeat the variables again (file 1, file 1).

3) Auto-Reduction List File
The Auto-Reduction Look-Up List File must use the following format.  Please stick closely to using this format (avoid inserting Tabs, just use spaces when editing).  There are 3 header rows which are skipped when reading the file.

1         2         3         4         5  12345678901234567890123456789012345678901234567890 Bin|Exp-|Filter-|Temp-|Reduction Group------| 2   10   V       -15   2x2 V 10s 2    5   V       -15   2x2 V 5s 2   10   R       -15   2x2 R 10s 2    5   R       -15   2x2 R 5s

Bin [number ] - Binning  :  1 for 1x1 binning or 2 for 2x2 binning

Exp  [numbers in secs ] - Exposure setting.  
When left blank it implies that the Auto-Reduction Group uses Dark Exposure Compensation (Note : since the program is unable to make any checks Reduction Group details, the user must be responsible for what settings are being used in CCDSoft)

Filter  [text ] - Filter Name as used in Current Filter Set. 
When left blank it implies that no Filters are being used.

Temp  [numbers in degC ] - Temperature.  
When left blank it implies that the Reduction Group uses darks that were taken at the same temperature as the Image (Note : since the program is unable to make any checks Reduction Group details, the user must be responsible for what settings are being used in CCDSoft and associated Support Frames)

Reduction Group  [text ] - Name of Reduction  Group as it appears in CCDSoft. 

4) Darks Set File
The Darks Set File must use the following format.  Please stick closely to using this format (avoid inserting Tabs, just use spaces when editing). There are 3 header rows which are skipped when reading the file.

1         2         3 123456789012345678901234567890 Bin|Num|Exp | 2   7   0 2   7   1 2   7   2 2   7   5 2   7   10 2   7   20 2   7   60 1   5   20 1   5   60

Bin [number ] - Binning required :  1 for 1x1 binning or 2 for 2x2 binning

Num  [number] - Number of Frames to be taken for the  Bin/Exposure setting. 

Exp  [numbers in secs ] - Dark Exposure length required .
If an Exposure of  0 is specified, Bias Frames are taken.

5) Flats Set File    
The Flats Set File must use format shown in the "example_flats.txt" file. The format is also  shown below.  Please stick closely to using this format (avoid inserting Tabs, just use spaces when editing).  There are 3 header rows which are skipped when reading the file.

1          2         3         4  1234567890123456789012345678901234567890 Bin|Num|Exp1|Exp2|Exp3|Exp4|Exp5|  2   7   1    4    2    2    2    1   7   3

Bin [number ] - Binning required :  1 for 1x1 binning or 2 for 2x2 binning

Num  [number] - Number of Flat Frames to be taken for each Exp/Filter.

Exp1 to Exp5  [numbers in secs ] - Exposure settings to be used. 

If a Filter Wheel is being used then Exp1 refers to exposure through Filter 1, Exp 2 refers to exposure through Filter 2 etc.  

Use blank or 0 if no images are required for a certain Filter. 

6) Mosaic Sets File Format
The Mosaic Sets file must use the format shown in the "example_mosaic.txt" file. Format is also shown below.  Please stick closely to using this format avoid problems (avoid inserting Tabs, just use spaces when editing).. There are 3 header rows which are skipped when reading the file.

The file can contain the outline specification for one or more Mosaics. The actual Mosaic Frame coordinates for each Mosaic are contained within the specified Frame File.

Con [text] - a three-letter free format field, normally used for the giving the constellation of the mosaic target.  

Name [text] - The Name of the Mosaic Target, as recognised by TheSky. To be accessible the appropriate database may need to be active in TheSky.

FrameFile [text] - Name of File containing Mosaic Frame Coordinates. The file should be one that resides in either the Targets Folder or in a subfolder of it called "_Mosaic Data". (Only the file name should be given, not the full file path).  Format of the Frame File is described in the section Mosaic Frame Coordinates File

Bin [number ] - Binning required :  1 for 1x1 binning or 2 for 2x2 binning

(Please note that in order to take Luminance at 1x1 and RGB at 2x2, the Mosaic needs to be specified twice, one row with Bin 1 and another row with Bin 2. The Frame File would of course be the same).

Num  [number] - Number of Frames to be taken for each Filter/Exp setting. 

Exp1 to Exp5  [numbers in secs ] - Exposure settings to be used. If Filter Wheel is being used then Exp1 refers to exposure through Filter 1, Exp 2 refers to exposure through Filter 2 etc. Use a blank (or 0) to indicate no images at that Filter/Exp.

Comment   [text] - This is a free-format user field, but is normally used for information on the matrix size (eg 5x5).  

7) Mosaic Frame Coordinates File Format
Format for Mosaic Frame Coordinates files is under review due to changes in the way that TheSky6 outputs Mosaic Coordinates data, and it is probable that the required Format will be changed in a future version.

However in the meantime in version 2.4  the required file format is shown in the "example_mosaicframes.txt" file.  Format is also shown below.  Please stick closely to using this format to avoid problems (avoid inserting Tabs, just use spaces when editing).   There are no header rows.

Mosaic 0                5.2129199       16.8283840 Mosaic 1                5.2016180       16.8285660 Mosaic 2                5.1903161       16.8286108 Mosaic 3                5.1790142       16.8285183 Mosaic 4                5.1677122       16.8282885 Mosaic 5                5.2129082       16.7202050 Mosaic 6                5.2016127       16.7203869 Mosaic 7                5.1903172       16.7204317 Mosaic 8                5.1790218       16.7203392

Frame [text] - Frame name/description. This is normally just the frame name/number that is given by TheSky when Mosaic is defined and output.

RA [numeric] - This is RA of the Frame Centre in decimal hours.
This should be contained in an 11 column wide field beginning at column 44.

DEC [numeric] - This is DEC of the Frame Centre in decimal degrees.
This should be contained in an 11 column wide field beginning at column 61.

MosaicText = Mid(LineFromFile,1,20)
MosaicPoint = CLng(Mid(LineFromFile,8,3))
dRa = CDbl(Mid(LineFromFile,44,11))
dDec = CDbl(Mid(LineFromFile,61,11))

Back to Top  

Disclaimer

Telescopes do not have an unlimited range of movement. The type of telescope, type of mount, and size and position of accessories can prevent it pointing in certain directions. If the telescope is forced past these points, the telescope, it's mounting or accessories (such as an attached CCD Camera) might be damaged. 

Whilst the program scripts operate with TheSky (which includes a "limit line" feature to specify inaccessible positions) and has some independent safety features, any telescope could run past its mechanical limits through accident or carelessness or component failure. With unattended operation and the dependence on correct content and formatting of user supplied target data, the potential risk is higher still.

The author (David Richards) therefore cannot be responsible for any damage to any telescope or equipment that occurs when using the program, its script or any modified derivative.

Back to Top