| agetcat | astcat | agetcat |
agetcat -- Extract objects from astrometric catalogs
agetcat regions output
Agetcat extracts astrometry files from local or remote astrometry catalogs catalogs using a list of region definitions regions supplied by the user and writes the results of each catalog query to the output astrometry files output .
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 regions = "pars" these quantities are read from the aregpars parameters rcra , rcdec , rcrawidth , rcdecwidth rcraunits , rcdecunits ., and rcsystem . If regions is an image they are read from the FITS world coordinate system in the image header. If regions is a file name they are read from a file whose format is the following.
# Optional comment ra1 dec1 xwidth1 ywidth1 [raunits1 [decunits1 [system1]]] ra2 dec2 xwidth2 ywidth2 [raunits2 [decunits2 [system2]]] ... .... ....... ....... [........ [......... [.......]]] raN decN xwidthN ywidthN [raunitsN [decunitsN [systemN]]]
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.
# 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
For each specified astrometry catalog in catalog 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 catdb , 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 filter = yes, the captured results are filtered using the values of the parameters in the filtering parameter set afiltpars . The afilterpars parameters permits the user to sort the query results by setting the sort field parameter fsort , select or reject catalog records by setting the selection expression parameter fexpr , select or reject fields for output by setting the output field list parameter fields , and change the coordinate system, units, and format of the catalog coordinates by setting the fosystem , foraunits , fodecunits , foraformat , and fodecformat parameters. A more detailed description of the region filtering parameters can be obtained by typing "help afiltpars".
If standard = 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 acatpars parameters to define the astrometry file format. Most non-astcat tasks will interpret the astrometry file header as documentation and skip it.
If update = yes the values of the aregpars and afilterpars parameters will be updated at task termination. If verbose = yes then detailed status reports are issued as the task executes.
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.
cl> agetcat pars default cl> page reg001.cat.1
2. Repeat the previous example but sort the output on the sort field "mag1".
cl> agetcat pars default filter+ fsort=mag1 cl> page reg001.cat.2
3. Repeat example 2 but butoutput only those records for which mag <= 16.0.
cl> agetcat pars default filter+ fsort=mag1 fexpr="mag1 <= 16.0" cl> page reg001.cat.3
4. Repeat example 3 but but output a new field equal to mag2 - mag3.
cl> agetcat pars default filter+ fsort=mag1 fexpr="mag1 <= 16.0" \ fields="f[*],mag2-mag1" cl> page reg001.cat.4
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.
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
6. Repeat example 5 but find data for two catalogs the usno2@noao and gsc@cadc.
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"
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.
cl> page imlist dev$pix dev$ypix cl> agetcat @imlist default cl> page wpix.cat.1
aclist, adumpcat, aregpars, afiltpars
