Survey Definition Tool (SDT) - User Manual

If you got the error meassage:
Exception while trying to load plugin survey.msb.MsbFactory: java.lang.ClassNotFoundException: survey.msb.MsbFactory
then go to MsbFactory missing.

This page contains a few characters that Netscape Communicator 4.8 cannot display.

If you view this document in the SDT help window and prefer viewing it in a proper HTML browser you can load it into a browser of your choice instead. The location of this document is sdt/cfg/help/index.html in the SDT distribution. The SDT help display provides only the most basic functionality.

Contents

1. 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 follows.

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 coordinate system:
  x1 y1 radius coordSys
where
x1 y1
x2 y2
Spherical coordinates (e.g. RA Dec, Long Lat etc).
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. If it were better to separate coordinates by a comma and allow ' ' in H M S and D M S instead then this could be changed in future versions of the SDT.

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
Radius in degrees

coordSys
Coordinate system name: FK5, FK4, GAL, SLOAN, ECL are currently supported.

Example

  10:20:30.0 15:00:0.0 11:20:30.0 25:00:0.0 FK5

Excluding Areas

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 excluded rectangle/circle or inside a previously include rectangle/circle.

Example

  \ 10:50:30.0 20:00:0.0 11:10:30.0 21:30:0.0 FK5

2. 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 following entries:
# Path of the local (binary) installation of the USNO catalog
# (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.
USNO_DIR=

# The SDT will use USNO_DIR_WIN instead of USNO_DIR if it runs under Windows
USNO_DIR_WIN=U:\\oxnaMfo\\USNO-A2.0_lt17

# Name under which this catalog should be added to the catalog choice box
USNO_NAME=
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.

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 using USNO_DIR and USNO_DIR_WIN. This means a single SDT installation with one sdt/cfg/sdt.cfg can be used for both UNIX/Linux and Windows. Only their start-up scripts differ: sdt/bin/sdt for UNIX/Linux and sdt/bin/sdt.bat for Windows. There is a 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. If there is a demand this can probably be made faster.

GAIA/SkyCat/JSky catalogs (online and local)

By default the entries of serv_type: catalog contained in the standard skycat.cfg file were included in the skycat.cfg that included in the distribution of this SDT. Not all of them will be suitable as guide star catalogs though. These catalogs will appear in the catalog choice box of the SDT.

Adding other catalogs

In principal 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:
  1. Create/copy/edit a skycat.cfg file such as ~/.skycat/skycat.cfg or sdt/cfg/skycat.cfg in this SDT distribution.
  2. Put all the catalogs you want to use into the skycat.cfg file.
  3. Edit the following entry in the sdt/cfg/sdt.cfg file of this SDT distribution
    # List of catalogs used by JSky/JSkyCat/Skycat/GAIA.
    # Do not use "~" in the path.
    jsky.catalog.skycat.config=../cfg/skycat.cfg
    so that the value of jsky.catalog.skycat.config is the path of the skycat.cfg you want to use.
  4. 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 them.

3. Generating telescope pointings and allocating guide stars

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. It is possible that you have to re-start to SDT before this comes into effect.

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
WFCAM_FOOTPRINT_DISPLAY=false
in the sdt/cfg/sdt.cfg file. It is possible that you have to re-start to SDT before this comes into effect.

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 are displayed while this process goes on. The following colour coding is used:

Catalog entries

greenThe entry that is selected as guide star.
cyanEntry in autoguider range and valid.
yellowEntry in autoguider range and invalid.
blueValid but not in autoguider range.
magentaNot valid and not in autoguider range.

Autoguider footprint display background color

____ ____grayNormal mode of operation.
____ ____redNo guide star found yet. Backtracking.
____ ____pinkBacktracking was successful.
________ red and yellow flashNo guide star found. Backtracking unsuccessful. Leaving this pointing empty.
It sometimes happens that the change of background colour of the detector display is not exactly as described in the user manual. Especially when the algorithm is interupted by clicking the "Stop" button the algorithm might briefly assume it is in backtracking mode and trigger the display to be painted red although backtracking is subsequently not really executed. Similary, if the detector display might sometimes stay red even though backtracking has already finished.

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
  AUTOGUIDER_HEIGHT = 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.

The default settings are

  AUTOGUIDER_WIDTH  = 265.1 - 2√2 * 5.0 ≈ 250.0
  AUTOGUIDER_HEIGHT = 257.8 - 2√2 * 5.0 ≈ 243.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.

The SDT considers all objects with magnitudes between GUIDE_MIN_MAG and GUIDE_MAX_MAG that are not closer then GUIDE_MIN_DIST to the next object in the catalog. (See Changing the configuration.) Out of these objects it picks the brightest object.

4. 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 the main window become enabled again.

When the local binary USNO catalog installation is used then 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.

5. Exporting the results to MSBs for use in the Observation Preparation Tool (OT)

There is an online documentation available for the UKIRT OT. But in connection with the SDT the OT that comes with this SDT should be used because the official UKIRT OT might not have all the features needed yet.
  1. Create a template MSB (or multiple template MSBs) 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.
  2. Select the "File" -> "Export to OT ..." menu.
  3. The first file selection dialog that appears is used to select the OT Science Program XML file that contains the template MSB.
  4. The second file selection dialog allows the user to select 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".

5.2. Multiple Template MSBs

Multiple template MSBs result in generated MSBs with multiple Observation components. Each of these Observation components corresponds to one of the template MSBs.

Example:

This would result in the generated MSB time split into three 20 minute chunks. The first of these would be filled using the first template MSB, the second chunk would be filled using the second template MSB and so on. Given the length of the template MSBs this would result in two tiles using template MSB 1 followed by the same two tiles done again, but this time using template MSB 2 and finally the same 2 tiles using template MSB 3. The three template MSBs could be set to filter H, J, K respectively and be otherwise identical. The 2 tiles repeated three times using different filters would all end up in the same generated MSB, indicating that they have do be observed at the same time. Since MSBs cannot be nested this means that the template MSBs are converted to Observation components within the generated MSB. The whole survey area will then be covered with such 2-tile-3-filter generated MSBs. In this example the number of filters (3) is determined by the number of template MSBs. The number of tiles (2) depends on the MSB_DURATION set in the sdt/cfg/sdt.cfg file.

6. The backtracking window

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.

7. 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.

8. 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 are
BASE_TAG=Base
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
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 will still 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.
If you want to change jsky.catalog.skycat.config make sure 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.684
OFFSETS_Y = 0 792.684
NEXT_PATTERN_X = 3170.736
NEXT_PATTERN_Y = 3170.736
Their meaning is described in the file itself. The default values are used for a filled in WFCAM tile.

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

9. Installing and running the SDT and OT

Requirements

  1. java 1.4 or higher. This can be downloaded at Sun.
  2. Only needed for OT telescope position editor: Java Advanced Imaging (version 1.1.1 or higher).

Installation

Download the sdt_ot.tar.gz file. Then type
gunzip sdt_ot.tar.gz
tar xf sdt_ot.tar

Running the SDT and OT

Make sure java is in your PATH environment variable. To start the applications use:

sdt_ot/sdt/bin/sdt to run the Survey Definition Tool under UNIX/Linux
cd sdt_ot/sdt/bin
sdt.bat

(or double click)
to run the Survey Definition Tool under Windows
sdt_ot/ot/bin/ukirtot
or
sdt_ot/ot/bin/ot -omp ukirt
to run the OT under UNIX/Linux
cd sdt_ot/ot/bin
ukirtot.bat

(or double click on ukirtot.bat)
or
sdt_ot/ot/bin/ot.bat -omp -nointernalframes ukirt
to run the OT under Windows

If less common operating systems (e.g. True64) are used you might get error messages such as Unrecognized option: -Xoss5m. In that case edit the file sdt_ot/ot/bin/ot and remove the unrecognized option from the java command line options.

10. Missing features and known bugs

  1. Old bug: Delays when accessing a guide star catalog.
    There used to be a bug which sometimes caused a long delay when a guide star catalog was first accessed after starting up the SDT, i.e. after the "Start" button was pressed. The SDT is now (March 2006) using jsky-2.5 instead of jsky-1.0 and it is hoped that this made the problem disappear.
  2. Faulty backtracking display (see above).
  3. Sometimes it is neccessary to hit the stop button on the progress panel more than once in order to interrupt the algorithm.

11. 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).

11. MsbFactory Missing

If you got the error meassage:
Exception while trying to load plugin survey.msb.MsbFactory: java.lang.ClassNotFoundException: survey.msb.MsbFactory
then you are running the SDT in WFCAM mode without the libraries and classes needed to interface with the JAC OT. In this case you can open and save your surveys but you cannot export them to the JAC OT.
Change Log