.help agetcat Mar00 astcat
.ih
NAME
agetcat -- Extract objects from astrometric catalogs
.ih
USAGE
agetcat 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 around coordinates ra = "00:00:00.0" and
dec = "+00:00:00" in the query coordinate system is extracted.
.le
.le
.ls output 
The list of output astrometry 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 files are assigned names of
the form "reg#[.cat#].cat.#" if the region definition source is "pars" or
a file e.g. "reg002.cat.1", or "image[.cat#].cat.#" if the region
definition source is an image list, e.g. "image.cat.1". The catalog number
is only inserted if there is more than one catalog in the catalog 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 catalogs = ")_.catalogs"
The list of input astrometry catalogs. By default the catalog name is set to the
value of the package parameter catalogs. 
.le
.ls standard = yes
Output a standard astrometry file ? If standard = yes then a header describing
the format of the astrometry file is written to the output file. The
astcat package
tasks use this information to decode the file. If standard = no, no
header is written and the user must instruct the astcat tasks how to decode the
file.
.le
.ls filter = no
Filter the results of the catalog query before writing the final results
to the output astrometry file ?
.le
.ls afiltpars = ""
The astrometry file filtering parameter set. These parameters permit the user
to sort the output on a field or field expression, select or reject
catalog records using a boolean expression, select or reject fields
to output, add new fields that are expressions of existing fields to
the output, and perform simple coordinate transformations.
.le
.ls update = no
Update the default values of the algorithm parameters, e.g. aregpars and
afiltpars, at task termination ?
.le
.ls verbose = yes
Print status messages on the terminal as the task proceeds ?
.le
.ls catdb = ")_.catdb"
The catalog configuration file. Catdb defaults to the value of the
package parameter catdb. The default catalog configuration file is
"astcat$lib/catdb.dat".
.le

.ih
DESCRIPTION

Agetcat extracts astrometry files from local or remote astrometry catalogs
\fIcatalogs\fR using a list of region definitions \fIregions\fR supplied by
the user and writes the results of each catalog query to the output astrometry
files \fIoutput\fR.

A region 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 image they are read from the FITS world coordinate
system in the image header.  If \fIregions\fR is a file name they are
read from a 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 catalog query system is
J2000.0 then all four region definitions are equivalent, since J2000.0
is assumed in examples 1 and 2, is specified in example 3, and example 4
is same region as example 3 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 astrometry catalog in \fIcatalog\fR agetcat loops through the
regions list, formats the catalog query, makes a local or remote
connection to the catalog server using the catalog description in the
catalog configuration file \fIcatdb\fR, and captures the results.
Catalog names must be of the forms catalog@site, e.g. usno2@noao.
Catalog names without entries in the catalog configuration file
are skipped.

If \fIfilter\fR = yes, the captured results are filtered using the
values of the parameters in the filtering parameter set \fIafiltpars\fR.
The afilterpars parameters permits the user to sort the query results by setting
the sort field parameter \fIfsort\fR, select or reject
catalog records by setting the selection expression parameter \fIfexpr\fR,
select or reject fields for output by setting the output field
list parameter \fIfields\fR, and change the coordinate system, units,
and format of the catalog coordinates by setting the \fIfosystem\fR,
\fIforaunits\fR, \fIfodecunits\fR, \fIforaformat\fR, and \fIfodecformat\fR
parameters. A more detailed description of the region filtering
parameters can be obtained by typing "help afiltpars".

If \fIstandard\fR = yes a header is written to the output astrometry file which
defines the contents and format of the output object list. The astcat
tasks use this header to decode the input catalog files. If it is
missing or has been modified by non-astcat tasks the user must use
the \fIacatpars\fR parameters to define the astrometry file format. Most
non-astcat tasks will interpret the astrometry file header as documentation
and skip it.

If \fIupdate\fR = yes the values of the \fIaregpars\fR and \fIafilterpars\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 catalog using the default region definition
and page the results to determine the catalog format, i.e. the number and
names of the default output fields.

.nf
cl> agetcat pars default
cl> page reg001.cat.1
.fi

2. Repeat the previous example but sort the output on the sort field "mag1".

.nf
cl> agetcat pars default filter+ fsort=mag1
cl> page reg001.cat.2
.fi

3. Repeat example 2 but output only those records for which mag <= 16.0.

.nf
cl> agetcat pars default filter+ fsort=mag1 fexpr="mag1 <= 16.0"
cl> page reg001.cat.3
.fi

4. Repeat example 3 but output a new field equal to mag2 - mag3.

.nf
cl> agetcat pars default filter+ fsort=mag1 fexpr="mag1 <= 16.0" \
fields="f[*],mag2-mag1"
cl> page reg001.cat.4
.fi

5. Run agetcat on the text file regions which contains a list of region
definitions. Note that the coordinate system and coordinate units default
to those expected by the catalog query. The latter information can be
determined by running aclist on the default catalog.

.nf
cl> 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> agetcat regions default
cl> page reg001.cat.5
cl> page reg002.cat.1
cl> page reg003.cat.1
cl> page reg004.cat.1
cl> page reg005.cat.1
cl> page reg006.cat.1
cl> page reg007.cat.1
.fi

6. Repeat example 5 but find data for two catalogs the usno2@noao and
gsc@cadc.

.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> agetcat regions default catalogs="usno2@noao,gsc@noao"
.fi

7. Run agetcat 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> agetcat @imlist default
cl> page wpix.cat.1
.fi

.ih
TIME REQUIREMENTS
.ih
BUGS
.ih
SEE ALSO
aclist, adumpcat, aregpars, afiltpars
.endhelp
