Initial commit

1 files changed, 253 insertions, 0 deletions

diff --git a/noao/astcat/doc/agetcat.hlp b/noao/astcat/doc/agetcat.hlp
new file mode 100644
index 00000000..291a6fbb
--- /dev/null
+++ b/noao/astcat/doc/agetcat.hlp
@@ -0,0 +1,253 @@
+.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