APT Exposure Map
For several classes of observations, for example mosaics or programs that
repeatedly cover the same region of sky, it is sometimes useful to make an
exposure map to determine the amount of exposure time for a particular
position in the region observed. APT has the capability of providing data that
will allow the user to create such a map (outside of APT) via the Export
Exposure Coverage option.
Once you have created the proposal, under the File menu, go to Export/Export
Exposure Coverage data. This will export the exposure information for the
entire proposal into the directory you last saved your proposal into. There
will be 2 files.
This file provides a breakdown of the region covered by each exposure in the
proposal, by recording all the positions of the corners of the detectors
within each exposure. Each line corresponds to a reference point within a
detector, thus one exposure will be represented by several consecutive lines.
The first field in each line is a unique "Name". The last five characters of
the Name constitute the point identifier, which specify the shape point under
consideration. Specifically, the point identifier has the form sh-vn, where
'sh' is the shape descriptor (a number followed by P for polygon and C for
circle), and 'vn' is the vertex identifier (a V followed by the vertex number
(origin 0)). For example, for a ACS/WFC exposure, you would have 2P-V0 for the
first vertex of the second polygon (the WFC2 chip)
The correspondence between exposures and lines is as follows:
- ACS/SBC, STIS: Each exposure corresponds to four lines, one for each
vertex of the detector. The point identifiers are
1P-V0 through 1P-V3.
- ACS/WFC, WFC3/UVIS: Each exposure corresponds to eight lines, four for Chip 1 and
four for Chip 2. The point identifiers are 1P-V0
through 1P-V3 and 2P-V0 through 2P-V3.
- WFC3/IR: Each exposure corresponds to five lines. The first four
describe the vertices of the detector, with point
identifiers P1-V0 through P1-V3. The fifth line is
labeled 2C-V0, and it refers to the center of the
so-called "death star" region, a circle where the
detector does not collect valid data. The position
given in this line is the center of the death star circle.
Each line in this file contains the following comma-separated fields:
- Name:A unique identifier for the position. It is of the form
- vv is the Visit Number.
- eee is the Exposure ID number.
- c is the Copy.
- s is the Split.
- pp is Primart Pattern Position.
- sp is the Secondary Pattern Position.
- sh is the shape number followed by a suffix of P or C for polygon or
- vn is the vertex number within the shape. A quadrilateral would have
values of V0 through V3.
- RA: The right ascension (in degrees) of the vertex (or circle center).
- DEC: The declination (in degrees) of the vertex (or circle center).
- Exp ID: A string of the format vv.eee where vv is the visit number, and eee is the
- Copy: An integer indicating which copy of Exp ID this line is. It can range from 1
to the Number of Iterations for the exposure.
- Split: An integer indicating which CR-SPLIT of Exp ID this line is. It is always 1 for
exposures without CR-SPLITs.
- Primary Pattern Position: An integer indicating which pattern point in the primary pattern
specification this line is. It is always 1 for exposures not in a pattern.
- Secondary Pattern Position: An integer indicating which pattern point in the secondary pattern
specification this line is. It is always 1 for exposures that don't have secondary
- Config: The Configuration specified for the exposure.
- Mode: The Operating Mode specified for the exposure.
- Aperture: The Aperture specified for the exposure.
- Spec Elt 1:The first Spectral Element specified for the exposure.
- Spec Elt 2: The second Spectral Element (if any) specified for the exposure.
- Exp Time: The exposure time (in seconds) specified for the exposure.
- MULTIACCUM exposures do not have an expsure time specified. For those
exposures, this column will be blank, and the SAMP-SEQ and NSAMP columns
will be filled.
- For exposure copies that have an Actual Duration value (possibly populated
by the Orbit Planner Auto-Adjust feature), that value will be used.
- For CR-SPLIT exposures that don't have an Actual Duration specified, this
value will be an appropriate fraction of the exposure time specified on the
- NSAMP: The value of the NSAMP optional parameter, if present. Otherwise blank.
- SAMP-SEQ: The value of the SAMP-SEQ optional parameter, if present. Otherwise blank.
- Prime/Parallel: A string value of either Parallel or Prime depending on whether the
exposure is a coordinated parallel or not.
- Target: The name of the target used by the exposure.
- Orient Used: The spacecraft U3 orientation (in degrees) used in calculating the aperture
position. For executed visits, this will be the executed orientation. For
visits with a fixed orient specified (or a Same Orient As a fixed orient
visit), the fixed orient will be used. For other visits with Orient Range(s)
specified, the center of the first specified range will be used. Otherwise 0
will be used.
- RA Center Rot: The Right Ascension (in degrees) of the center of rotation of the exposure.
This is typically the RA of the Target, but can be different for exposures in
a pattern with a Coordinate Frame of "Celestial".
- Dec Center Rot: The Declination (in degrees) of the center of rotation of the exposure.
This is typically the Dec of the Target, but can be different for exposures in a
pattern with a Coordinate Frame of "Celestial".
- STC-S Coverage:
This field is blank.
This file is formatted such that it can be loaded into Aladin after
replacing the commas with Tabs. Aladin
will plot the vertices in a plane as if each vertex were a star in a catalog.
When vertices are selected in the Aladin display, the column data is
displayed at the bottom.
This file provides detailed exposure information in a more compact format, one
line per exposure, and is recommended as the starting point to obtain an
exposure map. The columns are the same as for the coverage_catalog.csv file,
with the following exceptions:
- The first three columns (Name, RA, and Dec) are not included.
- The file cannot be read into Aladin.
- The column STC-S Coverage is populated and contains a Space Time
Coordinate (STC) string defining one or more shapes on the sky, which
together describe the celestial coverage of the exposure. A shape can be
either a Polygon or a Circle. For a Polygon, an RA and Dec (in degrees) is
given for each vertex. For a Circle, the RA and Dec (in degrees) of the
center point is given followed by the radius of the circle (also in
degrees). The STC-S format is discussed http://www.ivoa.net/Documents/Notes/STC-S/
In general, the coverage for an exposure is the union of the coverage for all
shapes in the STC descriptor. The exception is the circle for WFC3/IR, which
denotes an exclusion region and therefore must be *removed* from the coverage.
Using the APT Exposure Map files
In order to obtain the exposure time at a given location from the
exposure-coverage file, users will need to carry out the following steps:
If an exposure map is desired, users will need to write a module capable of
repeating the steps above for a grid of positions.
- Identify the lines corresponding to exposures of interest. For example, an
exposure map may be desired only for a specific instrument-filter combination,
or only for Prime exposures, and so on.
- Determine the exposure time corresponding to each line. This is given
explicitly for optical/UV imagers, and implicitly from NSAMP and SAMP-SEQ for
- Use the information in the STC-S Coverage descriptor to determine whether the
desired location is inside the detector coverage, taking into account the
exclusion circle for WFC3/IR images.
- Add up the exposure time for all images that qualify.