|
|||
| Joint Astronomy Centre |
|
|
|
| Show document only |
|
||||||||||||||||||||||
|
____________________
|
||||||||||||||||||||||
|
IntroductionThis document details the use of the Survey Definition Tool in conjunction with the UKIRT OT. It assumes that you have acquired the software as detailed in the download page, and are ready to define your survey areas and import into a template MSB. The processes covered by this document are:
Definition of survey areas
Guide-star Catalog selection
Pointing generation and allocation of guide stars per pointing
Saving the pointings (.sdt) file
Merging ("Exporting") the pointings into a template MSBSome additional configuration information and notes on additional features are given at the end of the document. You can download the SDT from here. Please note that the SDT has been patched and now includes a current copy of the UKIRT Observing Tool libraries so that it can run as a stand-alone application. Note for 07B preparation: the OT was last released in July 2007, and the SDT was released in initial form on 24-Jul-2007. Note that SDSS is now available for use in the Sloan area (but that in the 24-Jul release it does not handle secondary sources, hence you should expect of order 5% blanks in your coverage). Defining Survey AreasA list of rectangular and circular survey areas is defined in the Survey Areas text box. Each rectangle/circle is defined on a new line. The format is as follows.Rectangular areas are defined in terms of two corners and a coordinate system: x1 y1 x2 y2 coordSysCircular areas are defined in terms of their centre, a radius in degrees and a coordinate system: x1 y1 radius coordSyswhere x2 y2
Example10:20:30.0 15:00:0.0 11:20:30.0 25:00:0.0 FK5 |
| green | The entry that is selected as guide star. |
| cyan | Entry in autoguider range and valid. |
| yellow | Entry in autoguider range and invalid. |
| blue | Valid but not in autoguider range. |
| magenta | Not valid and not in autoguider range. |
Autoguider footprint display background color
| ____ | ____ | gray | Normal mode of operation. |
| ____ | ____ | red | No guide star found yet. Backtracking. |
| ____ | ____ | pink | Backtracking was successful. |
| ____ | ____ | red and yellow flash | No guide star found. Backtracking unsuccessful. Leaving this pointing empty. |
Guide star selection criteria
In order to select guide stars that can be used for all jitter and microstep pattern positions it is important that the AUTOGUIDER_WIDTH and AUTOGUIDER_HEIGHT specified in the sdt/cfg/sdt.cfg file are reduced accordingly:AUTOGUIDER_WIDTH = total_autoguider_width - 2√2 max_xy_offsetwhere max_xy_offset is the same in both of the above equations. It is the maximum offset (jitter + microstep) from the telescope base position in either x or y (RA or Dec) direction (whichever is greater). Before subtracting it max_xy_offset is multiplied by 2 because the autoguider CCD is centred around the base position and its valid area must be decreased by the same amount on either side and it is additionally multiplied by √2 because the autoguider CCD is diamond shaped, i.e. AUTOGUIDER_WIDTH and AUTOGUIDER_HEIGHT are measured at an angle of 45 degrees compared to the RA, Dec coordinates in which max_xy_offset is measured.
AUTOGUIDER_HEIGHT = total_autoguider_width - 2√2 max_xy_offset
The default settings are
AUTOGUIDER_WIDTH = 265.1 - 2√2 * 5.0 ≈ 250.0This allows offsets in x and y (RA and Dec) direction of up to ±5.0 arcseconds. The values are rounded to the integer below the actual value. Using these sighly smaller values should prevent guiding on the edge of the CCD.
AUTOGUIDER_HEIGHT = 257.8 - 2√2 * 5.0 ≈ 243.0
The SDT considers all objects
with magnitudes between GUIDE_MIN_MAG and GUIDE_MAX_MAG that
are not closer than GUIDE_MIN_DIST to the next object in the catalog.
(See Changing the configuration.)
Out of these objects it picks the brightest object. From 05B on, there
is a DELTA_MAG parameter which will allow the selection of the brighter
of two close stars if the magnitude difference is sufficiently large.
Suppressing guide star allocation
For testing the generation of pointings and to look at the general layout of survey areas it can be useful to switch the guide star allocation off. To do that set SKIP_GUIDE_STARS=true in the sdt/cfg/sdt.cfg file. You may have to re-start to SDT before this comes into effect.
Administrative information
The fields Title, PI, Country, Project ID are copied from the
Science Program Node in the template Science Program to the Science
Program Node in the generated Science Program.
Saving the results
Once the SDT has finished filling the survey areas the user is prompted to save them and the pointings to a file. This is done by using the usual "File" -> "Save" or "File" -> "Save As ..." menu. A file with the suffix "*.sdt" should be used.Interrupting the generation of telescope pointings
The generation of telescope pointings can be interrupted at any time using the "Stop" button of the online download dialog with progress bar when using an (online) GAIA/SkyCat/JSky catalog. Note that sometimes this button has to be hit repeatedly until the catalog choice box and the "Start" button in the main window become enabled again.When the local binary USNO catalog installation is used, the "Stop" button in the main window should be used to interrupt the generation of telescope pointings.
After hitting the "Stop" button it
is
possible to save intermediate results to the file in the
same way as described above for final results. The file can later be
opened again using
the "File" -> "Open" menu. The generation of telescope pointings can
then be resumed where it
had stopped before. A file with suffix ".sdt" should be used.
Exporting the results to MSBs for use in the Observation Preparation Tool (OT)
Refer to the online documentation for the UKIRT OT. Here we list the operations you will need to complete to export your survey to a template MSB, and then discuss the ways in which different templates are treated by the export process.First, create a template MSB in the OT and save it as a Science Program. (Make sure that the MSB is directly under the Science Program node and not hidden in an "AND" or "OR" folder.) The first MSB found as a child node of the Science Program node is used as the template MSB by the SDT.
- In the SDT, select the "File" -> "Export to OT ..." menu.
- The first file selection dialog that appears is used to select the OT Science Program XML file that contains the template MSB.
- The second file selection dialog allows the user to name a new OT Science Program XML file into which the generated MSBs are saved. OT Science Program files use an XML format and should be saved using the file suffix ".xml".
Survey Containers in a template MSB
Survey Containers are used to store multiple targets which make up tiles and surveys.A template MSB can contain a single Survey Container or multiple Survey Containers or no Survey Container at all. (In the latter case the SDT will automatically add a Survey Container to each generated MSB.)
The survey target list of a Survey Container inside a template MSB should be left as it is by the user, so that it is more or less empty apart from the one (0, 0) dummy target that is in every newly created Survey Container and that will later be removed by the SDT. The survey targets are filled in by the SDT (in the Survey Containers of the generated MSBs).
Option 1 - If
there is no Survey
Container in the template MSB then the SDT creates one and moves all
the components
other than the Scheduling Constraints and Site Quality components into
the Survey Container:
 No Survey Container in template MSB |
Option 2 - If there is a single
Survey Container in the template MSB then the SDT
simply copies the
whole template MSB when creating the generated MSBs and fills the
Survey Container with survey targets:
 Single Survey Container in template MSB |
It should not make much difference whether a single Survey Container is
used in the template MSB or
none. Putting a single Survey Container in the template MSB allows more
control over how
the generated MSBs will look like because the SDT will maintain the
layout of the template
MSB when it creates the generated MSBs.
Template MSB with multiple Survey Containers
Template MSBs with multiple Survey Containers can be used to observe several targets with the same configuration (e.g. same filters) before changing the configuration and observing the same targets again, and so on, all within the same generated MSB (see figure below).
 Multiple Survey Containers in template MSB |
Automatic MSB Numbering
From 05B on, the SDT will automatically add an index number to the title of each generated MSB, to assist with identification during survey execution. For example, if the template MSB looks like this:
then the generated survey might look like this:
In this example, the seed MSB has an index number (:23) at the end of its title. If this is omitted, then numbering would commence at 1.
Additional features.
View Areas
There is an "Options" -> "View Areas" menu which allows you to view the survey areas specified in the text box without starting the process of generating the pointings and allocating the guide stars.Help
The help menu displays this HTML document.Changing the configuration
Many configuration details can be changed. They are specified in the sdt/cfg directory of this distribution. Make sure you make a copy of the original directory before changing things. Most properties are specified in the sdt/cfg/sdt.cfg file. The default settings areBASE_TAG=BaseAn explanation of all these properties is provided in the sdt/cfg/sdt.cfg file. Of these BASE_TAG, GUIDE_TAG should remain unchanged for use with the ORAC/OMP/OT system at UKIRT. AUTOGUIDER_WIDTH, AUTOGUIDER_WIDTH, AUTOGUIDER_ANGLE may change in future versions of the SDT (to avoid guiding on the edge of the detector and depending on the exact angle but also to make sure that a guide star is still in range when jittering and microstepping) but once these values have been established they should be left unchanged for use with WFCAM. The SDT has not recently been tested with GUIDE_QUERY_DISPLAY=false. HELP_URL should probably remain unchanged although a version of this might be made available online which could be kept more up to date. In that case HELP_URL could be set to the online version.
GUIDE_TAG=GUIDE
PRIMITIVE_PATTERN=pattern.cfg
AUTOGUIDER_WIDTH = 265.1
AUTOGUIDER_HEIGHT = 257.8
AUTOGUIDER_ANGLE = 45.0
USNO_DIR=
USNO_DIR_WIN=
USNO_NAME=
DEFAULT_CATALOG_LONG_NAME=USNO at ESO
jsky.catalog.skycat.config=../cfg/skycat.cfg
GUIDE_MIN_MAG = 4.0
GUIDE_MAX_MAG = 17.0
GUIDE_MIN_DIST = 7.0
GUIDE_QUERY_DISPLAY=true
HELP_URL = help/index.html
MSB_DURATION = 30
SKIP_GUIDE_STARS=false
WFCAM_FOOTPRINT_DISPLAY=true
If you want to change jsky.catalog.skycat.config make sure you know what you are doing (i.e. you have edited skycat.cfg files before).
The PRIMITIVE_PATTERN property is described below.
Note that although the files pattern.cfg and ../cfg/skycat.cfg are in the same directory (sdt/cfg) their paths have to be specified differently. PRIMITIVE_PATTERN is specified relative to the sdt/cfg directory whereas jsky.catalog.skycat.config must be specified either as an absolute path or relative to the sdt/bin directory. This allows users to specify other skycat.cfg files they might have on their computers. But remember not to use the "~" when specifying the ~/.skycat/skycat.cfg or ~/.skycat/skycat.cfg in your home directory. Use the full path.
Most other properties are set to ad hoc values and can be changed by users at will.
Primitive Pattern (Tile Configuration)
To change the primitive pattern (tile configuration) you can either make multiple copies of sdt/cfg/pattern.cfg, modify them and then set PRIMITIVE_PATTERN in sdt/cfg/sdt.cfg to the version you want or you can leave PRIMITIVE_PATTERN=pattern.cfg in sdt/cfg/sdt.cfg unchanged and edit sdt/cfg/pattern.cfg directly. You can edit the following parameters:OFFSETS_X = 0 792.684Their meaning is described in the file itself. The default values are used for a filled in WFCAM tile.
OFFSETS_Y = 0 792.684
NEXT_PATTERN_X = 3170.736
NEXT_PATTERN_Y = 3170.736
The following should remain fixed (once the final relative positions of the WFCAM detector arrays have been measured). They specify the dimensions of the bounding rectangle of a single 4-detector WFCAM footprint:
DETECTOR_GROUP_WIDTH = 2402.568
DETECTOR_GROUP_HEIGHT = 2402.568
Missing features and known bugs
- Faulty backtracking display (An additional window pops up during backtracking which should display the backtracking position. It currently does not work properly most of the time but it is not particularly useful anyway. It was intended to be a debugging feature. Ignore it for now.).
OT Telescope Position Editor
You can view the WFCAM multi-detector autoguider footprints projected on a digitized sky image by using the OT Telescope Position Editor (GAIA-like tool).- Select a Survey Target in the in the OT's Survey Container.
- Select the "Target Information" tab and click on the "Plot..." button. (Alternatively, click on the "Image" button on the Science Program window.)
- To see the autoguider footprint, click on the "WFCAM AG" button.
- To see the IR multi-detector footprint select the WFCAM instrument component in the Science Program tree, then select "View" -> "Scale" -> 0.2 from the TPE menu and finally click on the "Sci Area" button of the TPE.