Survey Areas Definition Tool (SADT) - User Manual


Introduction

This document details the use of the Survey Areas Definition Tool. The SADT version described here was implemented for VISTA but it can also be started in VST mode. The processes covered by this document are:
Some additional configuration information and notes on additional features are given at the end of the document.


Installing and running the SADT

Requirements

Installation

Download the sadt.tar.gz file into a directory.
Under UNIX/Linux cd into the directory and type

gunzip sadt.tar.gz
tar xf sadt.tar

Under Windows:

Double click on sadt.tar.gz.

Running the SADT

You might have to put java into your PATH environment variable. To start the SADT use:

UNIX/Linux Windows
VISTAsadt/bin/sadt cd sadt/bin
sadt.bat
(or double click)
VST sadt/bin/sadt -c vstcd sadt/bin
sadt.bat -c vst


How to use the SADT


Define Survey Areas

A list of survey areas is defined in the Survey Areas text box. Each of them is defined on a new line and can be a coordinate range, a rectangle or a circle.

Survey area table columns:

Type
Type of survey area: Rectangle, Coordinate Range, Circle.

RA (Long)
RA, Long, RA 1, Long 1 (depending on survey area type and coordinate system).
Use "H:M:S" or "H M S" or decimal degrees (not decimal hours).

Dec (Lat)
Dec, Lat, Dec 1, Lat 1 (depending on survey area type and coordinate system).
Use "D:M:S" or "D M S" or decimal degrees.

Width (Long 2)
Width, Circle diameter, RA 2, Long 2 (depending on survey area type and coordinate system).

For Width use decimal degrees. For RA 2, Long 2 use "H:M:S" or "H M S" or decimal degrees (not decimal hours).

Height (Lat 2)
Height, Dec 2, Lat 2 (depending on survey area type and coordinate system).

For Height use decimal degrees. For Dec 2, Lat 2 use "D:M:S" or "D M S" or decimal degrees.

Angle
Rotation angle of survey area with respect to the selected coordinate system (East of North in degrees).

System
Coordinate system

Exclude
Tick to exclude survey area.

Tooltips are diplayed when moving the mouse over the survey area table header.

Deleting a Survey Areas

Survey areas can be deleted from the table by selecting them with the mouse and pressing the delete key.


Select guidestar catalog

There is a catalog choice box underneath the survey areas text box.

Local USNO catalog

The Survey Areas Definition Tool can read locally installed USNO catalogs. The SADT 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 sadt/cfg/vista/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 SADT 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 SADT installation with one sadt/cfg/vista/sdt.cfg can be used for both UNIX/Linux and Windows. Only their start-up scripts differ: sadt/bin/sadt for UNIX/Linux and sadt/bin/sadt.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 standard skycat.cfg file were included in the skycat.cfg distributed with this SADT. Not all of them will be suitable as guide/aO star catalogs though. These catalogs will appear in the catalog choice box of the SADT.

Adding other catalogs

In principle the SADT 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 sadt/cfg/vista/skycat.cfg in this SADT distribution.
  2. Put all the catalogs you want to use into the skycat.cfg file.
  3. Edit the following entry in the sadt/cfg/vista/sdt.cfg file of this SADT 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.

Select tile pattern


Generate tiles/pawprints with guide/aO 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/aO stars tile by tile, pointing by pointing. As soon as a guide/aO star has been found for a pointing the pointing is displayed as pink dot. This pointing is provisional until guide/aO 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 SADT and delete all the pointings created. Make sure you save your results before changing the Survey Areas.

Display Coordinate System, Plot Type, Display Options

A right mouse click anywhere on the survey area display except on a selected tile (see below) makes a menu appear which allows the selection of different coordinate systems and plot types. If the display coordinate system is to be different from the coordinate system in which the survey area is defined then their can be display bugs.

The plot type should be chosen to be sensible, i.e. North Polar Plot for areas close to the North pole etc.

There is also an "Options" menu item which allows to switch off the fixed aspect ratio of the display.

Coordinates at mouse

You can find out the coordinates of the current mouse position in the survey area display by pressing the middle mouse button over a position and keeping it pressed. The coordinates are displayed in both the survey areas display coordinate system and the coordinate system in which the survey area (if any) of which the coordinates are part was originally defined.

Tile priorities

To set the priorities one or more tiles must be selected. Selected tiles appear in the color cyan. Tiles are can be selected and deselected with the mouse in a way similar to a file manager program on a computer:

Guide/aO detector footprint display

While the SADT is filling the survey areas with pointings it searches the selected catalog for suitable guide/aO stars. The catalog entries and the guide/aO detector footprint currently searched are displayed while this process goes on. The following colour coding is used:

Catalog entries

green The entries that are selected as the guide/aO stars. Note that no green entries are displayed if at the time of the display it is not yet known which entries will be selected as guide/aO stars. Example: First the SADT looks for suitable canditate entries for guide stars on both autoguider chips without displaying any as selected guide/aO stars. Only after that the SADT decides which of these are selected as guide stars.
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/aO star found yet. Backtracking.
____ ____ pink Backtracking was successful.
____ ____ red and yellow flash No guide/aO star found. Backtracking unsuccessful. Leaving this pawprint 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.

Inspecting catalog entries on the guide/aO detector footprint display

Catalog entries can be selected in the guide/aO detector footprint display. Click in the centre of any on the circles representing the catalog entries (being careful to be very close to the middle of the circle with the mouse). The catalog ID and the RA, DEC are then displayed as the frame title of the display window.

Guide/aO star settings

The way guide/aO stars are allocated for each pawprint is specified in the file sadt/cfg/vista/aux_pos.xml which looks as follows:
<?xml version="1.0" encoding="UTF-8"?>
<!-- Configuration file for auxiliary positions (guide/aO stars) -->
<position_requirements>

  <!-- Get a certain number of required positions regardless -->
  <!-- how many of them are on which AG detector. -->
  <aux_pos type="AG" numMin="1" numMax="5" magMin="4" magMax="17" sepMin="7.0">
    <detector detector_id="AG_PY" offset_x="-625.0" offset_y="2210.0" width="432.0" height="216.0" angle="0.0"/>
    <detector detector_id="AG_NY" offset_x="625.0" offset_y="-2210.0" width="432.0" height="216.0" angle="0.0"/>
  </aux_pos>

  <!-- Get one group of LOWFS stars from detector LOWFS PY -->
  <aux_pos type="LOWFS_PY" numMin="1" numMax="5" magMin="7" magMax="15" sepMin="10.0">
    <detector detector_id="LOWFS_PY" offset_x="0.0" offset_y="2352.0" width="432.0" height="432.0" angle="0.0"/>
  </aux_pos>

  <!-- Get another group of LOWFS stars from detector LOWFS NY -->
  <aux_pos type="LOWFS_NY" numMin="1" numMax="5" magMin="7" magMax="15" sepMin="10.0">
    <detector detector_id="LOWFS_NY" offset_x="0.0" offset_y="-2352.0" width="432.0" height="432.0" angle="0.0"/>
  </aux_pos>

  <!-- Specify the backtrack step by which a tile should be shifted in case -->
  <!-- if not enough guide/aO stars could be found -->
  <backtrack_step arcseconds="100.0"/>
</position_requirements>
Auxiliary position (guide/aO) attributes

type
This is the type of the auxiliary position (guide/aO), i.e. "AG", "LOWFS_PY", "LOWFS_NY". An auxiliary position types are names after the kind of detector they are needed for where multiple detectors can be associated with the same auxiliary position type, e.g. autoguider ("AG").

numMin
Minimum number of auxiliary positions required for a given type.

numMax
Maximum number of auxiliary positions required for a given type.

magMin
Minimum magnitude value required for an auxiliary position of this type.

magMax
Maximum magnitude value required for an auxiliary position of a this type.

sepMin
Minimum separation between neighbouring objects in the catalog required for an auxiliary position of this type.

Detector attributes

detector_id ("AG_PY", "AG_NY", "LOWFS_PY", "LOWFS_NY")
Identifies the detector.

offset_x, offset_y
Offsets of the detector from centre of the focal plane in arcseconds along the x and y axes of the focal plane.

width, height
Usable dimensions of the detector in arcseconds. This needs to be reduced in accordance with the jitter and microstep patterns for which the selected guide/aO star is required to stay in reach of the detector.

angle
The angle attribute in the detector element describes the rotation of the detector in the focal plane. This should remain fixed at 0 for VISTA.

backtrack_step arcseconds
The amount by which a the search algorithm shifts a tile back along the row of tiles if the guide/aO star requirements defined in the sadt/cfg/vista/aux_pos.xml file cannot be met at a tile position. The backtrack step is repeated until the guide/aO stars are found or the previous tile position is reached.

Suppressing guide/aO 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/aO star allocation off. To do that set SKIP_GUIDE_STARS=true in the sadt/cfg/vista/sdt.cfg file. You may have to re-start to SADT before this comes into effect.


Assign tile priorities

The SADT allows the user to assign individual tile priorities to the tiles. It has not yet been finalized how these tile priorities are used when the SADT output is read into the P2PP because there might be other priorities connected to different OBs within the same tile (e.g. Do the OB with filter Y before the OB with filter Z before). The SADT only deals with spatial priorities, i.e. priorities between different tile positions.

Tiles can be selected individually by clicking on them. The selection follows a similar principle as the selection of files in a file manager: Keep the control key pressed to not lose the previous selection. If closed loops of tiles are selected then all the tiles inside the loop will be selected as well. Unselect all tiles by clicking somewhere outside the survey area. Unselect individual tiles by keeping the control key pressed and clicking individual tiles.


Save the tiles/pawprints (.xml file)

Once the SADT 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 "*.xml" 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 ".xml" should be used.


Additional features.

View Areas

Press the View Areas button to view the survey areas defined in the survey area table.

Reset Tiles

Press the Reset button to delete existing tiles/pawprints.

Set survey area display coordinate system and plot type

Do a right mouse click anywhere in the survey area display window except in a selected tile (light blue) and a popup menu will appear that offers various display coordinate systems and plot types. A coordinate range defined in a particular coordinate system appears as a rectangle in the survey area display if the same coordinate system is selected as display coordinate system and the plot type is set to Cartesian Plot.

Define surveys in terms of pre-defined tile centers

Select the "Predefined Tile Coordinates" tab to load a list of predefined fixed tile centers from an ASCII file. The SADT will then look up guide/aO stars for the pawprints of these tiles without changing the coordinates of the tiles through backtracking or sidetracking.

The format of the ASCII file is as follows: There is one line per tile beginning with an optional tile name enclosed in double quotes followed by the RA in decimal degrees, the Declination in decimal degrees and the rotation angle in decimal degrees, all separated by one or more spaces. All coordinates are in FK5 (J2000).

Example containing lines with and without tile name

  "LMC-Bar Tile1"  75.1234 -71.3456  0.000
  "LMC-Bar Tile2"  75.4567 -71.3456  0.000
  75.79   -71.3456  0.000
  76.1233 -71.3456  0.000

Tooltips

Many input widgets of the SADT (buttons, tabs etc) have tooltips that are displayed when the user hovers with the mouse over them.

-debug option

This option is more usedful for developing the SADT and fixing its bugs and might not be very helpful for users.

If the debug option -debug is added after survey.app.SurveyDefinitionTool in the startup script (e.g. sdt/bin/sadt or sdt/bin/sadt.bat) then the file sdt/cfg/vista/aux_pos_debug.xml is used unstead of sdt/cfg/vista/aux_pos.xml. This means that the SADT will accept all stars in the range of the detector. The results can then be converted using the file menu option "Convert Existing XML File To Gnuplot ...". This results in a directory full of data files and a gnuplot script which can be used for debugging.


Menus

Options


Changing the configuration

Many configuration details can be changed. They are specified in the sadt/cfg/vista directory of this distribution. Make sure you make a copy of the original directory before changing things. Most properties are specified in the sadt/cfg/vista/sdt.cfg file. The default settings are
FORMAT=standard
PRIMITIVE_PATTERN=pattern.cfg
USNO_DIR=
USNO_DIR_WIN=
USNO_NAME=
DEFAULT_CATALOG_LONG_NAME=USNO at ESO
jsky.catalog.skycat.config=../cfg/skycat.cfg
HELP_URL = help/index.html
SKIP_GUIDE_STARS=false
TILING_COORD_SYS=
An explanation of all these properties is provided in the sadt/cfg/vista/sdt.cfg file. The SADT 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 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 both in the same directory (sadt/cfg/vista) their paths have to be specified differently. PRIMITIVE_PATTERN is specified relative to the sadt/cfg/vista directory whereas jsky.catalog.skycat.config must be specified either as an absolute path or relative to the sadt/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.

Primitive Pattern (Tile Configuration)

To change the primitive pattern (tile configuration) you can either make multiple copies of sadt/cfg/vista/pattern.cfg, modify them and then set PRIMITIVE_PATTERN in sadt/cfg/vista/sdt.cfg to the version you want or you can leave PRIMITIVE_PATTERN=pattern.cfg in sadt/cfg/vista/sdt.cfg unchanged and edit sadt/cfg/vista/pattern.cfg directly.

See comments in the sadt/cfg/vista/pattern.cfg file for more details.


Known Bugs


Change Log