|
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 |
| VISTA | sadt/bin/sadt | cd sadt/bin sadt.bat (or double click) |
| VST | sadt/bin/sadt -c vst | cd sadt/bin sadt.bat -c vst
|
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.
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:
- Create/copy/edit a skycat.cfg file such as ~/.skycat/skycat.cfg
or sadt/cfg/vista/skycat.cfg in this SADT distribution.
- Put all the catalogs you want to use into the skycat.cfg
file.
- 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.
- 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.
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:
- Select Tiles.
Tiles can be selected in various ways. To add to an already existing selection press the Control button
and keep it pressed during while selecting new tiles.
- Click into a tile.
- Drag mouse along tiles.
- Drag mouse along a closed path to select all tiles inside the path.
- Deselect Tiles.
- To deselect a single tile press the Control key and click on the tile.
- To deselect all tiles click outside the survey area.
- Set priorities.
Click inside a selected tile with the right mouse button. An popup menu will appear to allow the selection
of a priority applicable to all currently selected tiles.
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.
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.
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.
Press the View Areas button to view the survey areas defined in the survey area table.
Press the Reset button to delete existing tiles/pawprints.
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.
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
Many input widgets of the SADT (buttons, tabs etc) have tooltips that are displayed when the user hovers with
the mouse over them.
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.
- File
- Open, Save, Save As ...
Open and save the SADT results using XML files.
- Export Tile Center List ...
Save only the tile centers to an ASCII format which can then be used as
pre-defined tile centers.
- Convert Existing XML file to Gnuplot ...
For debugging: writes the coordinates of the tile centers, pawprints and
guide stars to files that can be read by gnuplot and creates a gnuplot
script that reads all these files.
- Preferences
Specify a proxy server if required (e.g. in connection with firewall).
- Exit
Exit the SADT.
- Options
- Find Guide/aO Stars
If this option is switched off then the algorithm creates tiles/pawprints without any guide/aO stars.
This is useful of you want to see roughly how a survey area is filled with tiles without having to wait
the long time it takes to download guide/aO stars for all tiles from an online catalog.
- Fixed Aspect Ratio
Fixes the aspect ratio of the survey area display.
- Draw Pawprints
If this option is selected then the shape of all science detectors in the focal plane is drawn on the
survey area display. If the survey area is large then these detectors become very samll and it might
look better of there are not drawn.
- Include overlap
If this option is selected then tiles which lie partially in an included survey area and partially in
an excluded survey area are included. Otherwise they are excluded.
- Help
- User Guide
Displays this page.
Options
- View Areas
This allows you to view the
survey areas specified in the text box without starting the process of
generating the pointings and allocating the guide/aO stars.
- Find Guide/aO Stars
Switch guide/aO star allocation on and off.
- Fixed Aspect Ratio
Determines whether the survey area display uses fixed aspect ratio or not.
- Draw Pawprints
Determines whether the pawprints (individual detectors of multi-detector instruments)
are drawn in the survey area display or not.
- Include Overlap
If this is switched on then tile which are partially in an excluded survey area
and partially in an included survey area area used as well. Otherwise any tile
that has any overlap with an excluded survey area is excluded from the survey.
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.
- 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.)
- Avoiding of bright sources is not implemented yet.
- Display survey efficency at the end of the tiling process.
- Calculate the overall duration of the survey.
- Display at the end of the tiling process can contain misleading information if the
tiling process was interupted, partially saved, resumed etc.
- Sometimes guide/aO stars can be missed if there is a glitch in the online catalog access.
- Sometimes it is neccessary to hit the stop button on the progress panel more than once
in order to interrupt the algorithm.
Change Log