path: root/noao/astcat/doc/agetim.hlp

.help agetim Mar00 astcat
.ih
NAME
agetim -- extract fits images from image surveys
.ih
USAGE
agetim regions output
.ih
PARAMETERS
.ls regions
The source  of the extraction region definitions. The options are:
.ls <filename>
The name of a text file containing a list of region definitions, one
region definition per line. The format of the regions file is described
in detail below.
.le
.ls <image list>
The list of images containing the region definition. The input images
must have a valid FITS world coordinate system in order to be used
for region definition.
.le
.ls pars
If regions is set to the reserved keyword "pars" then a single region
definition is read from the \fIaregpars\fR parameter set. By default a region
ten arc minutes in size centered on coordinates ra = "00:00:00.0" and
dec = "+00:00:00" in the query coordinate system is extracted.
.le
.le
.ls images
The list of output FITS image files. The number of output files must be equal
to the number regions in the regions list times the number of astrometry
catalogs in the catalog list. By default the output images are assigned names of
the form "reg#[.sv#].#.fits" if the region definition source is "pars" or
a file, e.g. "reg002.1.fits", or "image[.sv#].#.fits" if the region
definition source is an image list, e.g. "image.1.fits". The image survey
number is only inserted if there is more than one image survey
in the image survey list.
.le
.ls aregpars = ""
The region definition parameter set. The aregpars parameters define the
extraction region center, region width, region center units, and the region
center coordinate system. The region definition parameters are used if
\fIregions\fR = "pars".
.le
.ls imsurveys = ")_.imsurveys"
The list of input image surveys. By default the image survey name is set to the
value of the package parameter imsurveys. 
.le
.ls wcsedit = no
Convert a DSS WCS to a FITS WCS or add an approximate FITS style WCS to the
output image headers if they don't already possess one ?  The WCS status
of the survey images  plus approximate coordinate, scale, orientation, and
projection information is stored in the image surveys configuration
file \fIimdb\fR.
.le
.ls hdredit = no
Add a set of standard keywords to the image header which may be required or
useful in the later astrometric analysis steps ?  These parameters divide
into two groups, those concerned with locating objects in an image and
those required to transform from mean place to observed coordinates.
Default settings for these parameters are stored in the images surveys
configuration file.
.le
.ls update = no
Update the default values of the algorithm parameters, e.g. aregpars
on task termination ?
.le
.ls verbose = yes
Print status messages on the terminal as the task proceeds ?
.le
.ls imdb = ")_.imdb"
The image surveys configuration file. Imdb defaults to the value of the
package parameter imdb. The default image surveys configuration file is
"astcat$lib/imdb.dat".
.le

.ih
DESCRIPTION

Agetim extracts fits images from local or remote image surveys
\fIimsurveys\fR using a list of region definitions supplied by the user
\fIregions\fR and writes the results of each image survey query to the output
images \fIoutput\fR.

A regions definition consists of the coordinates of the field center,
the field size, the units of the field center, and the coordinate system of
the field center. If \fIregions\fR = "pars" these quantities are read
from the \fIaregpars\fR parameters \fIrcra\fR, \fIrcdec\fR, \fIrcrawidth\fR,
\fIrcdecwidth\fR \fIrcraunits\fR, \fIrcdecunits\fR., and \fIrcsystem\fR. 
If \fIregions\fR is an input image
list they are read from the FITS world coordinate system in the image header.
If \fIregions\fR is a file name they are read from file whose format is
the following.

.nf
# Optional comment

ra1 dec1 xwidth1 ywidth1 [raunits1 [decunits1 [system1]]]
ra2 dec2 xwidth2 ywidth2 [raunits2 [decunits2 [system2]]]
... .... ....... ....... [........ [......... [.......]]]
raN decN xwidthN ywidthN [raunitsN [decunitsN [systemN]]]
.fi

Quantities in square brackets are optional. If system is undefined the
coordinate system defaults to the query coordinate system, i.e. if the
catalog query expects coordinates in J2000.0 then ra and dec will be
interpreted as though they were in the J2000.0 system. If undefined 
the ra and dec units default to the preferred units of the coordinate
system, i.e. hours and degrees for equatorial coordinate systems,
and degrees and degrees for ecliptic, galactic, and supergalactic 
coordinate systems.

A sample regions file  is shown below. If the image query system is
J2000.0 then all four regions definitions are equivalent, since J2000.0
is assumed in examples 1 and 2, is specified in example 3, and example
is same target as example but expressed in the B1950.0 coordinate system.

.nf
# List of targets

13:29:53.27 +47:11:48.4 10.0 10.0 
13:29:53.27 +47:11:48.4 10.0 10.0 hours degrees 
13:29:53.27 +47:11:48.4 10.0 10.0 hours degrees J2000.0
13:27:46.90 +47:27:16.0 10.0 10.0 hours degrees B1950.0
.fi

For each specified image survey in \fIimsurvey\fR agetim loops through the
regions list, formats the image survey query, makes a local or remote
connection to the image server using the image survey description in the
image survey configuration file \fIimdb\fR, and captures the results.
Image survey names must be of the form imsurvey@site, e.g. dss1@cadc.
Image survey names without entries in the image survey configuration file
are skipped.

If \fIwcsedit\fR = yes  then DSS coordinate systems are converted
into FITS coordinate systems or an approximate FITS WCS is added
to the image using information in the image surveys configuration file.
The quantities of interest are the values, units, and coordinates
system of the reference point \fIwxref\fR, \fIwyref\fR, \fIwraref\fR,
\fIwdecref\fR, \fIwraunits\fR, \fIwdecunits\fR, and \fIwsystem\fR, and the
scale, orientation, and projection information \fIwxmag\fR, \fIwymag\fR,
\fIwxrot\fR, \fIwyrot\fR, and \fIwproj\fR. For more information on how these
quantities are defined in the image surveys configuration file 
type "help imsurveys".

If \fIhdredit\fR = yes then a standard set of keyword equal values
pairs will be added to the image headers using information in the
image surveys configuration file.  The parameters divide into two groups
those concerned with locating stars in the image and computing accurate
pixel centers: \fIedatamin\fR, \fIedatamax\fR, \fIegain\fR, and \fIerdnoise\fR,
and those required for transforming mean place coordinates to observed
plate coordinates as may be required to compute very accurate image scales,
\fIobservat\fR, \fIesitelng\fR, \fIesitelat\fR, \fIesitealt\fR, \fIesitetz\fR,
\fIemjdobs\fR, \fIewavlen\fR, \fIetemp\fR, and \fIepress\fR. New keyword
values are only added to the header if keywords of the same name do not
already exist and if appropriate values for the keywords exists, i.e.
"INDEF" valued parameters will not be added to the header.

If \fIupdate\fR = yes the values of the \fIaregpars\fR parameters will be
updated at task termination. If \fIverbose\fR = yes then detailed status
reports are issued as the task executes.

.ih
EXAMPLES

1. Extract data from the default image survey using the default region
definition, display the resulting image,  and examine its header.

.nf
cl> agetim pars default
cl> display reg001.1.fits 1 fi+
cl> imheader reg001.1.fits lo+ | page
.fi

2. Repeat the previous example but convert the DSS WCS to a FITS WCS.
The DSS WCS is unaltered.

.nf
cl> agetim pars default wcsedit+ 
cl> display reg001.2.fits 1 fi+
cl> imheader reg001.2.fits
.fi


3. Repeat example 2 but extract data for two surveys.

.nf
cl> agetim pars default wcsedit+ imsurveys="dss1@cadc,dss2@cadc"
cl> display reg001.3.fits 1 fi+
cl> imheader reg001.3.fits
cl> display reg002.1.fits 2 fi+
cl> imheader reg002.1.fits
.fi

4. Repeat example 2 but add the values of the standard astrometry image
keywords if these do not already exist in the image header and are defined.

.nf
cl> agetim pars default wcsedit+ hdredit+
cl> display reg001.4.fits 1 fi+
cl> imheader reg001.4.fits
.fi

5. Extract images for a list of regions in a text file.  Note that the
coordinate system and coordinate units are not specified in this regions
list and default to those expected by the image survey query.

.nf
page regions
00:00:00.0 -90:00:00 10.0 10.0 
00:00:00.0 -60:00:00 10.0 10.0 
00:00:00.0 -30:00:00 10.0 10.0 
00:00:00.0 +00:00:00 10.0 10.0 
00:00:00.0 +30:00:00 10.0 10.0 
00:00:00.0 +60:00:00 10.0 10.0 
00:00:00.0 +90:00:00 10.0 10.0 
cl> agetim regions default
.fi

6. Run agetim on a list of images containing valid FITS WCS information.
Note that in the following example the test image dev$pix does not
have a FITS WCS so no data is extracted for it.

.nf
cl> page imlist
dev$pix
dev$ypix
cl> agetim @imlist default
.fi

.ih
TIME REQUIREMENTS
.ih
BUGS
If output file is not a fits file, as may be the case if an error occurred
in the network transfer, and header editing is enabled agetim will
crash with a file seek error. The bug is due to missing error check 
statements in the FITS kernel and will be fixed for the next release.
.ih
SEE ALSO
aslist, adumpim, aregpars
.endhelp