Survey Definition Tool - User Manual
Definition Tool (SDT) - User Manual
This 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 MSB
Some 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 Areas
A 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
Rectangular areas are defined in terms of two
corners and a coordinate system:
x1 y1 x2 y2 coordSys
Circular areas are defined in terms of their
centre, a radius in degrees and a
x1 y1 radius coordSys
- Spherical coordinates (e.g. RA Dec, Long
x (x1, x2) are in H:M:S or decimal degrees (not decimal hours).
y (y1, y2) are in D:M:S or decimal degrees.
Note that you can not use a space ' ' instead
of ':' in H:M:S and D:M:S. ' ' is
used as delimiter between the coordinates.
Decimal numbers (e.g. 23.4) are
always interpreted as degrees even if they represent the RA in FK5 or
FK4. But if RA, Dec are specified as H:M:S D:M:S then the H:M:S is
interpreted as hours, i.e. in FK5 and FK4 10:00:00.0 10:00:00
is the same as 150.0 10.0
- Radius in degrees
- Coordinate system name: FK5, FK4, GAL,
SLOAN, ECL are currently
10:20:30.0 15:00:0.0 11:20:30.0 25:00:0.0 FK5
Rectangles and circles that should be excluded
from the survey can be defined by
adding a backslash "\" at the beginning of the line.
A tile is excluded from the survey if its
"lower right" pointing
(i.e. pointing with min RA, min Dec in the tile) is inside a specified
or inside a previously include rectangle/circle.
\ 10:50:30.0 20:00:0.0 11:10:30.0 21:30:0.0 FK5
Treatment of Overlaps into Excluded Areas
[From 05B on,] there is a parameter INCLUDE_OVERLAP in the sdt
configuration file. This property specifies how excluded survey areas
(specified with a leading back slash in the survey area field) are
treated. If INCLUDE_OVERLAP=true is set then tiles which lie partially
in included survey areas and partially in excluded survey areas are
included. Otherwise (INCLUDE_OVERLAP=false) they are excluded.
[As of 05B,] incomplete tiles are no longer added to the pointing list.
If there are insufficient guide stars for all pawprints in a tile then
the whole tile is left blank. This fixes the bug which caused tiles and
MSB to be "out of step" (i.e. MSB and tile boundaries were not the
Selecting a catalog
There is a catalog choice box underneath the
survey areas text box.
Local USNO catalog
The Survey Definition Tool can read locally
installed USNO catalogs. The SDT was tested
with USNO-A2.0. If you would like to use a local USNO installation then
specify the path to
its directory in the sdt/cfg/sdt.cfg file by editing the
# Path of the local (binary) installation of the USNO
The USNO_NAME corresponds to the "long_name"
in catalog defined in skycat.cfg files
(see below) and is used in the catalog choice box.
# (or any catalog that uses the USNO binary format
plus acceleration files.)
# This should point to the directory containing the
zone*.cat and zone*.acc files.
# The SDT will use USNO_DIR_WIN
instead of USNO_DIR if it runs under Windows
# Name under
which this catalog should be added to the catalog choice box
You might have one USNO installation
which is accessible from UNIX/Linux as well
as Windows but under different path names. Both paths can be specified
USNO_DIR and USNO_DIR_WIN. This means a single SDT
with one sdt/cfg/sdt.cfg can be used for both UNIX/Linux and
Only their start-up scripts differ: sdt/bin/sdt for
sdt/bin/sdt.bat for Windows.
There is a href="http://www.nofs.navy.mil/projects/pmm/a.response">
description of how to download USNO-A2.0 via ftp but note that due
to the limited speed of file access in Java using a locally installed
binary USNO catalog is actually slower than using an online GAIA/SkyCat
catalog. This may be fixed in the future.
GAIA/SkyCat/JSky catalogs (online and local)
By default the entries of serv_type: catalog contained in the
skycat.cfg file were included in the skycat.cfg distributed with this
SDT. Not all of them will be suitable as guide star catalogs
These catalogs will appear in the catalog choice box of the SDT.
Adding other catalogs
In principle the SDT can read any catalog that can be read by tools
such as GAIA and JSkyCat.
Adding a new catalog can be done as follows:
- Create/copy/edit a skycat.cfg file such as ~/.skycat/skycat.cfg
or sdt/cfg/skycat.cfg in this SDT distribution.
- Put all the catalogs you want to use into the skycat.cfg
- Edit the following entry in the sdt/cfg/sdt.cfg file of
this SDT distribution
# List of catalogs used by JSky/JSkyCat/Skycat/GAIA.
so that the value of jsky.catalog.skycat.config is the path
of the skycat.cfg you want to use.
# Do not use "~" in the path.
- GAIA/SkyCat/JSky catalogs can be online as well as in a local
file conforming with the GAIA/SkyCat/JSky catalog convention but a
local GAIA/SkyCat/JSky catalog is not the same as the local binary USNO
catalog installation described above. I have not tested the use of
local GAIA/SkyCat/JSky catalogs. Let me know if you have problems using
telescope pointings and
allocating guide stars
Click on the "Start" button. Two
windows will pop up:
Survey Areas Display
The survey areas as defined in the survey
areas text box are displayed in light green.
The algorithm tries to retrieve suitable guide stars tile by tile,
pointing by pointing.
As soon as a guide star has been found for a pointing the pointing is
displayed as pink dot.
This pointing is provisional until guide stars for all the pointings in
the tile have been
found. Then the pointings become permanent and are displayed in black.
Note that this display is scaled so for very large survey areas so that
the dots representing
the pointing might appear merged together.
Any changes to the Survey Areas
definition in the text box will reset to the SDT and delete all
the pointings created. Make sure you save your results before changing
the Survey Areas.
By default the 4 WFCAM IR detectors
are displayed for each of the pointings.
This can be switched off by setting
in the sdt/cfg/sdt.cfg file.
It is possible that you have to re-start to SDT before this comes into
Autoguider footprint display
While the SDT is filling the survey areas
with pointings it searches the selected catalog for
suitable guide stars. The catalog entries and the autoguider footprint
displayed while this process goes on. The following colour coding is
||The entry that is selected as guide star.
||Entry in autoguider range and valid.
||Entry in autoguider range and invalid.
||Valid but not in autoguider range.
||Not valid and not in autoguider range.
Autoguider footprint display
||Normal mode of operation.
||No guide star found yet. Backtracking.
||Backtracking was successful.
||red and yellow flash
||No guide star found. Backtracking unsuccessful. Leaving this
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_offset
where 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.0
This 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
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
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
The generation of telescope pointings
interrupted at any time using the "Stop" button of the
online download dialog with progress bar when using an (online)
Note that sometimes this button has to be hit repeatedly until
the catalog choice box and the "Start" button in the main window become
When the local binary USNO catalog
installation is used, the "Stop" button in the main window should
used to interrupt the generation of telescope pointings.
After hitting the "Stop" button it
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.
the results to MSBs
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
First, create a template MSB in the OT and save it as a Science
(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
NOTE the order of the file naming
above. You do not need to give the name of the saved .sdt file when
generating the overall programme from the template - the two file
dialogues ask only for the name of the template xml file (which you
should have created already) and the name of the final science
programme you want generated.
- 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
are used to store multiple targets which make up tiles and surveys.
template MSB can contain a
single Survey Container or multiple Survey Containers or no Survey
all. (In the latter case the SDT will automatically add a Survey
Container to each generated MSB.)
survey target list of a
Survey Container inside a template MSB should be left as it is by the
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
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
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.
is an "Options" -> "View Areas"
menu which allows you to view the
survey areas specified in the text box without starting the process of
pointings and allocating the guide stars.
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
the original directory before changing things.
Most properties are specified in the sdt/cfg/sdt.cfg file.
The default settings
An 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
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
be set to the online version.
AUTOGUIDER_WIDTH = 265.1
AUTOGUIDER_HEIGHT = 257.8
AUTOGUIDER_ANGLE = 45.0
DEFAULT_CATALOG_LONG_NAME=USNO at ESO
GUIDE_MIN_MAG = 4.0
GUIDE_MAX_MAG = 17.0
GUIDE_MIN_DIST = 7.0
HELP_URL = help/index.html
MSB_DURATION = 30
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
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
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
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
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
You can edit the following parameters:
OFFSETS_X = 0 792.684
Their 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
of a single 4-detector WFCAM footprint:
DETECTOR_GROUP_WIDTH = 2402.568
DETECTOR_GROUP_HEIGHT = 2402.568
Missing features and known bugs
backtracking display (An
additional window pops up during
backtracking which should display the
backtracking position. It currently does not work properly most of the
but it is not particularly useful anyway. It was intended to be a
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
- 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.