diff options
Diffstat (limited to 'noao/astcat/doc')
| -rw-r--r-- | noao/astcat/doc/acatpars.hlp | 264 | ||||
| -rw-r--r-- | noao/astcat/doc/aclist.hlp | 59 | ||||
| -rw-r--r-- | noao/astcat/doc/adumpcat.hlp | 153 | ||||
| -rw-r--r-- | noao/astcat/doc/adumpim.hlp | 125 | ||||
| -rw-r--r-- | noao/astcat/doc/afiles.hlp | 106 | ||||
| -rw-r--r-- | noao/astcat/doc/afiltcat.hlp | 167 | ||||
| -rw-r--r-- | noao/astcat/doc/afiltpars.hlp | 357 | ||||
| -rw-r--r-- | noao/astcat/doc/agetcat.hlp | 253 | ||||
| -rw-r--r-- | noao/astcat/doc/agetim.hlp | 242 | ||||
| -rw-r--r-- | noao/astcat/doc/ahedit.hlp | 181 | ||||
| -rw-r--r-- | noao/astcat/doc/aimfind.hlp | 148 | ||||
| -rw-r--r-- | noao/astcat/doc/aimpars.hlp | 141 | ||||
| -rw-r--r-- | noao/astcat/doc/aregpars.hlp | 106 | ||||
| -rw-r--r-- | noao/astcat/doc/aslist.hlp | 60 | ||||
| -rw-r--r-- | noao/astcat/doc/awcspars.hlp | 113 | ||||
| -rw-r--r-- | noao/astcat/doc/catalogs.hlp | 295 | ||||
| -rw-r--r-- | noao/astcat/doc/ccsystems.hlp | 210 | ||||
| -rw-r--r-- | noao/astcat/doc/surveys.hlp | 275 |
18 files changed, 3255 insertions, 0 deletions
diff --git a/noao/astcat/doc/acatpars.hlp b/noao/astcat/doc/acatpars.hlp new file mode 100644 index 00000000..b64cadad --- /dev/null +++ b/noao/astcat/doc/acatpars.hlp @@ -0,0 +1,264 @@ +.help acatpars Mar00 astcat +.ih +NAME +acatpars -- edit the default astrometry file format parameters +.ih +USAGE +acatpars +.ih +PARAMETERS +.ls ftype = "stext" +The astrometry file format. The current options are: +.ls stext +Simple text. Records are newline delimited and fields are whitespace delimited. +.le +.ls btext +Blocked text. Records are newline delimited and fields are offset and +size delimited. +.le +.le +.ls ccsystem = "j2000" +The default celestial coordinate system. The coordinate systems of most +interest to users are "icrs", "j2000", and "b1950". For more detailed +information on all the celestial coordinate system options type +"help ccsystems". +.le +.ls standard astrometry file fields +The following parameters define the standard astrometry file fields. The +parameter names are the same as the standard field names. The parameter +values are the standard field descriptions. +.sp +Every astrometry file returned by +a catalog query or created by the user must contain the standard fields ra and +dec. The remaining fields are optional and may or may not be present +in either the original catalog or the astrometry file produced by a +catalog query. +.sp +The format of the standard fields is "fieldno [units [format]]" for simple +text files and "foffset fsize [units [format]]" for blocked text files +where the quantities in "[]" are optional. Standard fields with "" valued +field descriptions are assumed to be undefined. +.sp +.ls id = "" +The standard id field. The data type is character. The default units and +format values are "INDEF" and "%20s". +.le +.ls ra = "1 hours" +The standard right ascension / longitude field. The data type is double. The +default units and format values are "hours"and "%11.2h". +.le +.ls dec = "2 degrees" +The standard declination / latitude field. The data type is double. The default +units and format values are "degrees"and "%11.1h". +.le +.ls era = "" +The standard right ascension / longitude error field. The data type is double. +The default units and format values are "asecs" and "%6.3f". +.le +.ls edec = "" +The standard declination / latitude error field. The data type is double. +The default units and format values are "asecs" and "%6.3f". +.le +.ls pmra = "" +The standard right ascension / longitude proper motion field. The data type +is double. The default units and format values are "masecs/yr" and "%7.3f". +.le +.ls pmdec = "" +The standard declination / latitude proper motion field. The data type +is double. The default units and format values are "masecs/yr" and "%7.3f". +.le +.ls epmra = "" +The standard right ascension / longitude proper motion error field. The data +type is double. The default units and format values are "masecs/yr" and "%7.3f". +.le +.ls epmdec = "" +The standard declination / latitude proper motion error field. The data +type is double. The default units and format values are "masecs/yr" and "%7.3f". +.le +.ls catsystem = "" +The standard celestial coordinate system field. The data type is character. +The default units and format field values are "INDEF" and "%15s". If defined +the value of this field overrides the coordinate system defined by the +\fIcsystem\fR parameter. Supported values of catsystem are "icrs", "fk5", +"fk4", "fk4-noe", "ecliptic", "galactic", and "supergalactic". +.le +.ls equinox = "" +The standard celestial coordinate system equinox field. The data type is +character. The default units and format field values are "INDEF" and +"%15s". Equinoxes are typical expressed as Julian epochs e.g. "J2000.0", +Besselian epochs e.g. "B1950.0", or years "2000.0". +.le +.ls epoch = "" +The standard celestial coordinate system epoch field. The data type is +character. The default units and format field values are "INDEF" and +"%15s". Epochs are typical expressed as Julian epochs e.g. "J2000.0", +Besselian epochs e.g. "B1950.0", years "2000.0", or Julian date if the +epoch value > 3000.0. +.le +.ls px = "" +The standard parallax field. The data type is double. The default units +and format values are "msecs" and "%6.3f". +.le +.ls rv = "" +The standard radial velocity field. The data type is double. The default units +and format values are "km/sec" and "%6.3f". +.le +.ls epx = "" +The standard parallax error field. The data type is double. The default units +and format values are "msecs" and "%6.3f". +.le +.ls erv = "" +The standard radial velocity error field. The data type is double. The default +units and format values are "km/sec" and "%6.3f". +.le +.ls mag = "" +The standard magnitude field. The data type is real. The default units +and format field values are "mags" and "%8.3f". +.le +.ls color = "" +The standard color field. The data type is real. The default units +and format field values are "mags" and "%8.3f". +.le +.ls emag = "" +The standard magnitude error field. The data type is real. The default units +and format field values are "mags" and "%8.3f". +.le +.ls ecolor = "" +The standard color error field. The data type is real. The default units +and format field values are "mags" and "%8.3f". +.le +.ls xp = "" +The predicted x coordinate field. The data type is double. The default units +and format field values are "pixels" and "%9.3f". +.le +.ls yp = "" +The predicted y coordinate field. The data type is double. The default units +and format field values are "pixels" and "%9.3f". +.le +.ls xc = "" +The centered x coordinate field. The data type is double. The default units +and format field values are "pixels" and "%9.3f". +.le +.ls yc = "" +The centered y coordinate field. The data type is double. The default units +and format field values are "pixels" and "%9.3f". +.le +.ls exc = "" +The centered x coordinate error field. The data type is double. The default +units and format field values are "pixels" and "%9.3f". +.le +.ls eyc = "" +The centered y coordinate error field. The data type is double. The default +units and format field values are "pixels" and "%9.3f". +.le +.ls imag = "" +The standard instrumental magnitude field. The data type is real. The default +units and format values are "mags" and "8.3f". +.le +.ls eimag = "" +The standard instrumental magnitude error field. The data type is real. The +default units and format values are "mags" and "8.3f". +.le +.le + +.ih +DESCRIPTION + +The acatpars parameters define the default astrometry file format. These +parameters are used if the input astrometry file does not contain a standard +header describing the file format. By default standard headers are written +by all astcat package tasks which create astrometry files. If the +astrometry file does not have a header the acatpars parameters +are used to define one. + +By default acatpars assumes that the input astrometry file is a +simple text file, \fIftype\fR = "stext", with newline delimited records +and whitespace delimited fields. In this case users can define +the fields by setting the appropriate standard file parameters +to a string with the following format, e.g. + +.nf +parname = "fieldno [units [format]]" + + ra = "1 hours" + dec = "2 degrees" +.fi + +where fieldno is the field or column number in the record. The +units and format strings are optional and reasonable defaults are +supplied if they are missing. Currently the units information is +only used for decoding coordinate fields. For other fields the +units should be left at their default values. The format information +is used when an application has to decode a field into a numeric value +modify it in some way and rewrite it. + +If \fIftype\fR is set to "btext" for blocked text the input astrometry file +is assumed to be a text file with newline delimited records and fixed size +fields. This format can be used to describe astrometry files with +fields containing embedded blanks such as id fields. In this case users +define the fields by setting the appropriate standard file parameters to +a string with the following format, e.g. + +.nf +parname = "foffset fsize [units [format]]" + ra = "1 15 hours" + dec = "16 15 degrees" +.fi + +where foffset and fsize are the field offset and size in characters. +Formats and units are treated in the same way as they for simple text files. + +The fundamental coordinate system of the astrometry file is set by +the \fIcsystem\fR parameter. This is a global parameter applying to the +entire astrometry file . Its value is overwritten if the "catsystem" standard +field is defined, in which case the astrometry file may contain entries in +many different fundamental coordinate systems. + +.ih +EXAMPLES +1. List the astrometry file format parameters. + +.nf +cl> lpar acatpars +.fi + +2. Edit the astrometry file format parameters. + +.nf +cl> acatpars +... edit the parameters in the usual way +... type :wq to quit and save the edits +.fi + +3. Edit the astrometry file format parameters from the afiltcat task. + +.nf +cl> epar afiltcat +... edit the afiltcat parameters +... move to the acatpars parameter line and type :e +... edit the acatpars parameters +... type :wq to quit and save the acatpars edits +... continue editing the remaining afiltcat parameters +... type :go to execute the task +.fi + +4. Save the current acatpars parameter values in a text file called +acat1.par. Use the saved parameter set in the next call to the afiltcat +task. + +.nf +cl> epar acatpars +... edit some parameters in the usual way +... type :w acat1.par +... type :q to quit +cl> afiltcat ... acatpars=afilt1.par ... +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +afiltcat +.endhelp diff --git a/noao/astcat/doc/aclist.hlp b/noao/astcat/doc/aclist.hlp new file mode 100644 index 00000000..7a917572 --- /dev/null +++ b/noao/astcat/doc/aclist.hlp @@ -0,0 +1,59 @@ +.help aclist Feb00 astcat +.ih +NAME +aclist -- list the supported astrometric catalogs +.ih +USAGE +aclist catalogs +.ih +PARAMETERS +.ls catalogs +The names of the astrometric catalogs to be listed. If catalogs = "*" then +all the astrometric catalogs in the catalog configuration file are listed. +.le +.ls verbose = no +List the catalog query and output formats after the catalog name ? +.le +.ls catdb = ")_.catdb" +The catalog configuration file. The value of catdb defaults to the value +of the package parameter of the same name. The default catalog configuration +file is "astcat$lib/catdb.dat". +.le +.ih +DESCRIPTION +Aclist lists the supported astrometric catalogs specified by the +\fIcatalogs\fR parameter. If catalogs = "*" then all the supported catalogs +are listed, otherwise only the catalog names specified by the user are +listed. Valid catalog names have the form "catalog@site", e.g. "usno2@noao". +If \fIverbose\fR = "yes", then the catalog query and output formats are +listed after the catalog name. + +The catalog names, addresses, query formats, and query output formats are +specified in the catalog configuration file \fIcatdb\fR. By default the catalog +configuration file name defaults to the value of the package parameter catdb. +The default catalog configuration file is "astcat$lib/catdb.dat". +Users can add records to this file or create their own configuration +file using catdb as a model. +.ih +EXAMPLES + +1. List all the astrometric catalogs in the catalog configuration file. + +.nf +cl> aclist * +.fi + +2. List the query format and the output format for the usno2@noao catalog. + +.nf +cl> aclist usno2@noao verbose+ +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +aslist +.endhelp diff --git a/noao/astcat/doc/adumpcat.hlp b/noao/astcat/doc/adumpcat.hlp new file mode 100644 index 00000000..46302a64 --- /dev/null +++ b/noao/astcat/doc/adumpcat.hlp @@ -0,0 +1,153 @@ +.help adumpcat Mar00 astcat +.ih +NAME +adumpcat -- query a catalog and capture the results +.ih +USAGE +adumpcat catalog output ra dec size +.ih +PARAMETERS +.ls catalog +The name of the catalog to be queried. Catalog names have the form +catalog@site, e.g. "usno2@noao". The catalog address and query format are +stored in a record called catalog in the catalog configuration file. +.le +.ls output +The name of the output query results file. The query results are written +to the output file without modification, i.e. they may contain comments, +HTML markup, etc as well as the object list. +.le +.ls ra +The right ascension of the field center in the units expected by the catalog +query. The value of ra replaces the default value of the ra query parameter. +.le +.ls dec +The declination of the field center in the units expected by the catalog query. +The value of dec replaces the default value of the dec query parameters. +It may be necessary to add or remove a leading + to make the query work +correctly. +.le +.ls size +The field size in units expected by the catalog query. The value of size +replaces the default value of the width, ra/xwidth, dec/ywidth, +hwidth, x/rahwidth, y/dechwidth, or radius query parameters as appropriate. +.le +.ls catdb = ")_.catdb" +The catalog configuration file. The name of the catalog configuration file +defaults to the value of the package parameter of the same name. The +default configuration file is "astcat$lib/catdb.dat". +.le +.ih +DESCRIPTION +Adumpcat is a simple catalog access debugging task which queries the +astrometric catalog \fIcatalog\fR, captures the results, and writes them +to the file \fIoutput\fR without modification. + +The user must supply values for the query parameters ra, dec, and one or +more of the size query parameters width, ra/xwidth, dec/ywidth, hwidth, +ra/xhwidth, dec/yhwidth, or radius by +specifying appropriate values for the \fIra\fR, \fIdec\fR, and \fIsize\fR +parameters in the units expected by the catalog query. These values are +treated as strings and passed directly to the catalog query without +coordinate transformations or units conversions. + +The catalog configuration file \fIcatdb\fR contains a record for each +supported \fIcatalog\fR. This record contains the catalog address, +the query format, and the output format. The default configuration file +is "astcat$lib/catdb.dat". + +The output of adumpcat can be used to refine the catalog record in the +catalog configuration file. + +.ih +EXAMPLES + +1. List the supported catalogs, select a catalog to query, make the query, +and capture the results. The aclist task is used to list the supported +catalogs, as well as to list the query and output formats for the selected +catalog as shown below. The query format tells the user that the input +ra and dec must be entered in J2000 sexagesimal hours and degrees and +that the size parameter is a halfwidth in minutes. In this case the +results containing leading and trailing comments and +HTML markup as shown below. + +.nf +cl> aclist * +... +usno2@noao +... + +cl> aclist usno2@noao verb+ +Scanning catalog database astcat$lib/catdb.dat +Listing the supported catalogs +usno2@noao +nquery 4 + ra 00:00:00.00 hours %0.2h + dec 00:00:00.0 degrees %0.1h + hwidth 5.0 minutes %0.1f + qsystem J2000.0 INDEF %s +nheader 1 + csystem J2000.0 +nfields 4 + ra 1 0 d hours %12.3h + dec 2 0 d degrees %12.2h + mag1 3 0 r INDEF %4.1f + mag2 4 0 r INDEF %4.1f + +cl> adumpcat usno2@noao2 m51.res 13:29:53.27 +47:11:48.4 10.0 + +cl> page m51.res + +HTTP/1.1 200 OK^M +Date: Mon, 27 Mar 2000 20:59:46 GMT^M +Server: Apache/1.2.6^M +Connection: close^M +Content-Type: text/html^M +^M + +<HTML><HEAD><TITLE>USNO search results</TITLE><BODY> +<body bgcolor="#FFF9E6"><H1>USNO extraction (00:00:00.0 :00:00:00)</H1><P> +Output columns are RA, DEC, Red mag. (E/F) , and Blue mag. (O/J)<P> +<P><H2>Region number Z= 825 RA( 0: 60000) SPD( 32339999: + 32460000)</H2><P> + 00:00:01.443 -0:06:57.52 13.5 15.2<BR> + 00:00:01.574 -0:05:33.26 16.1 18.0<BR> + ... + 00:00:39.326 -0:00:47.83 14.6 16.9<BR> + 00:00:39.650 -0:02:02.64 18.8 19.4<BR> +<P><H2>Region number Z= 825 RA( 129539999: 129600000) SPD( 32339999: + 32460000)</H2><P> + 23:59:20.351 -0:09:34.07 18.3 19.5<BR> + 23:59:21.065 -0:01:18.44 17.4 19.1<BR> +... + 23:59:59.737 -0:03:54.75 10.5 12.4<BR> + 23:59:59.930 -0:01:57.84 18.1 18.6<BR> +<P><H2>Region number Z= 900 RA( 0: 60000) SPD( 32400000: + 32460000)</H2><P> + 00:00:00.503 0:06:07.90 18.0 19.5<BR> + 00:00:02.568 0:05:07.93 18.3 19.4<BR> +... + 00:00:39.056 0:02:11.91 18.4 19.2<BR> + 00:00:39.978 0:09:54.59 18.6 19.5<BR> +<P><H2>Region number Z= 900 RA( 129539999: 129600000) SPD( 32400000: +32460000)</H2><P> + 23:59:21.198 0:07:43.82 18.7 19.3<BR> + 23:59:21.364 0:08:05.09 18.4 19.6<BR> +... + 23:59:57.729 0:03:36.13 18.0 19.2<BR> + 23:59:59.460 0:08:42.02 19.2 19.7<BR> +<HR><P><P> Found 193 Entries<P><HR> +<address> + Central Computer Services, National Optical Astronomy Observatories, + 950 N. Cherry Ave., P.O. Box 26732, + Tucson, AZ 85726, Phone: 520-318-8000, FAX: 520-318-8360 + <P>Updated: 04Aug1998</address></body></html> +.fi +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +aclist, agetcat +.endhelp diff --git a/noao/astcat/doc/adumpim.hlp b/noao/astcat/doc/adumpim.hlp new file mode 100644 index 00000000..56270143 --- /dev/null +++ b/noao/astcat/doc/adumpim.hlp @@ -0,0 +1,125 @@ +.help adumpim Mar00 astcat +.ih +NAME +adumpim -- query an image survey and capture the results in a fits file +.ih +USAGE +adumpim imsurvey output ra dec size +.ih +PARAMETERS +.ls imsurvey +The name of the image survey to be queried. Image survey names have the form +survey@site, e.g. "dss2@cadc". The image survey address and query format are +stored in a record called imsurvey in the image survey configuration file. +.le +.ls output +The name of the output query results file. The query results are written +to the output file without modification, but at present they are implicitly +assumed to be in fits format. Users should append a ".fits" extension to +the output file name if they wish the output file to be visible to IRAF +as a FITS image. +.le +.ls ra +The right ascension of the field center in the units expected by the image +survey query. The value of ra replaces the default value of the ra query +parameter. +.le +.ls dec +The declination of the field center in the units expected by the image +survey query. The value of dec replaces the default value of the dec query +parameters. It may be necessary to add or remove a leading + sign from +in order to make the query function correctly. +.le +.ls size +The field size in units expected by the image survey query. The value of size +replaces the default value of the width, xwidth, ywidth, hwidth, hxwidth, +and hywidth query +parameters as appropriate. +.le +.ls imdb = ")_.imdb" +The image survey configuration file. The name of the image survey configuration +file defaults to the value of the imdb package parameter. The default +configuration file is "astcat$lib/imdb.dat". +.le +.ih +DESCRIPTION +Adumpim is a simple image survey access debugging task which queries the +image survey \fIimsurvey\fR, captures the results, and writes them +to the file \fIoutput\fR without modification. + +The user must supply values for the query parameters ra, dec, and one or +more of the size query parameters width, xwidth, ywidth, hwidth, xhwidth, +or yhwidth, by +specifying appropriate values for the \fIra\fR, \fIdec\fR, and \fIsize\fR +parameters in the units expected by the image survey query. These values are +treated as strings and passed directly to the image survey query without +coordinate transformations or units conversions. + +The image survey configuration file \fIimdb\fR contains a record for each +supported \fIimsurvey\fR. This record contains the image survey address, +the query format, and the output format. The default image survey configuration +file is "astcat$lib/imdb.dat". + +The output of adumpim can be used to refine the image survey record in the +image survey configuration file. + +.ih +EXAMPLES + +1. List the supported image surveys, select an image survey to query, make +the query and capture the results. The aslist task is used to list +the supported image surveys and the query and output formats for the selected +image survey as shown below. The query format tells the user that the input +ra and dec must be in sexagesimal hours and degrees and in the J2000 +coordinate system that the size parameter is a radius in minutes. + +.nf +cl> aslist * +... +dss2@cadc +... + +cl> aslist dss2@cadc verb+ +Scanning image surveys database astcat$lib/imdb.dat +Listing the supported image surveys +dss2@cadc +wcs dss +nwcs 10 + wxref INDEF INDEF d pixels + wyref INDEF INDEF d pixels + wxmag INDEF 1.009 d arcsec/pixel + wymag INDEF 1.009 d arcsec/pixel + wxrot INDEF 180.0 d degrees + wyrot INDEF 0.0 d degrees + wraref OBJCTRA INDEF d hms + wdecref OBJCTDEC INDEF d dms + wproj INDEF tan c INDEF + wsystem INDEF J2000 c INDEF +nkeys 13 + observat INDEF Palomar c INDEF + esitelng INDEF +116:51:46.80 d degrees + esitelat INDEF +33:21:21.6 d degrees + esitealt INDEF 1706 r meters + esitetz INDEF 8 r INDEF + emjdobs INDEF INDEF c INDEF + edatamin INDEF INDEF r ADU + edatamax INDEF INDEF r ADU + egain INDEF INDEF r e-/ADU + erdnoise INDEF INDEF r e- + ewavlen INDEF INDEF r angstroms + etemp INDEF INDEF r degrees + epress INDEF INDEF r mbars + +cl> adumpim dss2@cadc m51.fits 13:29:53.27 +47:11:48.4 10.0 + +cl> imheader m51.fits + +.fi +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +aslist, agetim +.endhelp diff --git a/noao/astcat/doc/afiles.hlp b/noao/astcat/doc/afiles.hlp new file mode 100644 index 00000000..83f08791 --- /dev/null +++ b/noao/astcat/doc/afiles.hlp @@ -0,0 +1,106 @@ +.help afiles Mar00 astcat +.ih +NAME +afiles -- describe the standard astrometry files +.ih +USAGE +help files + +.ih +ASTROMETRY FILES + +An astrometry file is any text file containing celestial coordinate information +for a small region of the sky. A minimal astrometry file consists of a list +of celestial coordinate pairs one pair per line. Most astrometry files also +contain additional non- positional information, e.g. proper motions, +magnitudes, colors, etc. + +A standard astrometry file as an astrometry file containing a standard header +describing the contents and format of the file. The astcat tasks use the +header to decode the file. Normally the astrometry file header is derived +from the parent astrometric catalog description in the catalog configuration +file. If the astrometry file header is missing one may be constructed +after the fact by setting the standard field description parameter +in the \fIacatpars\fR parameter set and running the \fIafiltcat\fR task. + +A set of standard field names is reserved for describing the format of +astrometry files. The current list of standard field names is: +id, ra, dec, era, edec, pmra, pmdec, epmra, epmdec, catsystem, equinox, +epoch, px, rv, epx, erv, mag, color, emag, ecolor, xp, yp, xc, yc, exc, +eyc, imag, and eimag. For more information about these fields type +"help acatpars". + +.ih +SAMPLE STANDARD ASTROMETRY FILE + +A sample astrometry file in standard format is shown below. + +.nf +# BEGIN CATALOG HEADER +# type stext +# nheader 1 +# csystem J2000 +# nfields 4 +# ra 1 0 d hours %12.3h +# dec 2 0 d degrees %12.2h +# mag1 3 0 r INDEF %4.1f +# mag2 4 0 r INDEF %4.1f +# END CATALOG HEADER + + 00:00:01.443 -0:06:57.52 13.5 15.2 + 00:00:01.574 -0:05:33.26 16.1 18.0 + 00:00:01.904 -0:09:48.51 18.2 19.6 + 00:00:02.529 -0:04:21.53 13.4 14.4 + 00:00:04.154 -0:01:56.32 17.1 18.3 + 00:00:04.438 -0:05:00.03 11.4 13.5 + 00:00:04.697 -0:03:24.59 16.9 17.7 + 00:00:05.989 -0:02:46.36 15.1 17.6 + 00:00:07.118 -0:09:03.53 19.1 19.8 + 00:00:07.260 -0:06:47.95 17.0 17.7 + 00:00:07.314 -0:00:22.35 15.3 16.8 + 00:00:07.818 -0:02:25.90 12.2 12.4 +.fi + +.ih +SAMPLE ASTROMETRY FILE + +A sample headerless astrometry file is shown below where ra, dec, mag1 +and mag2 are stored in columns 1 through 4 respectively. + +.nf + 00:00:01.443 -0:06:57.52 13.5 15.2 + 00:00:01.574 -0:05:33.26 16.1 18.0 + 00:00:01.904 -0:09:48.51 18.2 19.6 + 00:00:02.529 -0:04:21.53 13.4 14.4 + 00:00:04.154 -0:01:56.32 17.1 18.3 + 00:00:04.438 -0:05:00.03 11.4 13.5 + 00:00:04.697 -0:03:24.59 16.9 17.7 + 00:00:05.989 -0:02:46.36 15.1 17.6 + 00:00:07.118 -0:09:03.53 19.1 19.8 + 00:00:07.260 -0:06:47.95 17.0 17.7 + 00:00:07.314 -0:00:22.35 15.3 16.8 + 00:00:07.818 -0:02:25.90 12.2 12.4 +.fi + +This file can be converted to standard form with the afiltcat task as follows + +.nf +cl> agetcat input output filter- ra="1 hours %12.3h" dec="2 degrees %12.2h" \ +mag="1-2 INDEF %4.1f" +.fi + +or by editing in a header of the form shown in the previous section. The +lines + +.nf +# BEGIN CATALOG HEADER +# END CATALOG HEADER +.fi + +delimit the header. The header must contain the type, nheader, and +nfields keyword value pairs and accurate descriptions of file the format. + +.ih +SEE ALSO +help catalogs, agetcat, afiltcat, acatpars +.endhelp diff --git a/noao/astcat/doc/afiltcat.hlp b/noao/astcat/doc/afiltcat.hlp new file mode 100644 index 00000000..447891de --- /dev/null +++ b/noao/astcat/doc/afiltcat.hlp @@ -0,0 +1,167 @@ +.help afiltcat Mar00 astcat +.ih +NAME +afiltcat -- filter astrometry files +.ih +USAGE +afiltcat input output +.ih +PARAMETERS +.ls input +The list of input astrometry files. Astrometry files may be created by +other astcat tasks, e.g. agetcat, in which case they are preceded by a +header describing the format of the input astrometry file, or by +other IRAF or user tasks in which case the \fIacatpars\fR parameter set +must be used to describe them. +.le +.ls output +The list of output astrometry files. The number of output astrometry files +must be equal to the number of input astrometry files. If the output file +name equals the input file name then the original astrometry file is +overwritten. +.le +.ls acatpars = "" +The default input astrometry file format parameters. The acatpars parameters +are used only if the input astrometry file does not have a header. Type +"help acatpars" for a detailed description of the acatpars parameters. +.le +.ls catalogs = "filename@noao" +The dummy input catalog name. Afiltcat task users should leave this +parameter at its default setting. +.le +.ls standard = yes +Output a standard astrometry file ? If standard = yes then a header describing +the format of the output astrometry file is written to the output file. +Astcat package tasks use this information to decode the astrometry file. If +standard = no, no header is written and astcat tasks must use the acatpars +parameters to decode the astrometry file. +.le +.ls filter = yes +Filter rather than copy the input astrometry file to the output astrometry +file ? +.le +.ls afiltpars = "" +The astrometry file filtering parameter set. Afiltpars 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 to the output that are expressions of existing +fields, and perform simple coordinate transformations. +.le +.ls update = no +Update the default values of the algorithm parameter sets, e.g. acatpars and +afiltpars, on 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 parameters catdb. The default catalog configuration file is +"astcat$lib/catdb.dat". +.le + +.ih +DESCRIPTION + +Afiltcat filters the list of input astrometry files \fIinput\fR +and writes the results to the output files \fIoutput\fR. The number of input +astrometry files must equal the number of output astrometry files. + +The format of the input astrometry files is defined by the file header +if the file was written by an astcat package task, or by the +\fIacatpars\fR parameter set. The acatpars parameters \fIftype\fR and +\fIcsystem\fR define the input astrometry file type and coordinate system. +The position, size, and units of the standard astrometry file fields +the associated error fields are defined by the parameters: +\fIid\fR, \fIra\fR, \fIdec\fR, \fIpmra\fR, \fIpmdec\fR, \fIcatsystem\fR, +\fIequinox\fR, \fIepoch\fR, \fIpx\fR, \fIrv\fR, \fImag\fR, \fIcolor\fR, +\fIxp\fR, \fIyp\fR, \fIxc\fR, \fIyc\fR, and \fIimag\fR, and: + \fIera\fR, \fIedec\fR, +\fIepmra\fR, \fIepmdec\fR, \fIepx\fR, \fIerv\fR, \fIemag\fR, \fIecolor\fR, +\fIexc\fR, \fIeyc\fR, \fIeimag\fR. More detailed information on astrometry +files and the acatpars parameters can be found by typing "help files" +and "help acatpars". + +If \fIfilter\fR = yes, the input astrometry file is filtered before being +written to the outputfile. The filtering parameters are defined by the +filtering parameter set \fIafiltpars\fR. +The afilterpars parameters permit 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 \fIafields\fR, and change the coordinate system, units, +and format of the output coordinates by setting the \fIfosystem\fR, +\fIforaunits\fR, \fIfodecunits\fR, \fIforaformat\fR, and \fIfodecformat\fR +parameters. A more detailed description of the filtering +parameters can be obtained by typing "help afiltpars". + +If \fIstandard\fR = yes a header is written to the output file which +defines the contents and format of the output astrometry file. The astcat +tasks use this header to decode the astrometry files. If the header is +missing or has been modified by non-astcat tasks the user must set +standard = no, and use the \fIacatpars\fR parameters to define the +astrometry file format. Most non-astcat tasks will interpret the catalog +header as documentation and skip it. + +If \fIupdate\fR = yes the values of the \fIacatpars\fR and \fIafiltpars\fR +parameters are updated at task termination. If \fIverbose\fR = yes +then detailed status reports are issued as the task executes. + +.ih +EXAMPLES + +1. Sort the input astrometry file using the value of the magnitude field. + +.nf +cl> page reg001.cat.1 +... examine catalog header to determine name of magnitude field +cl> afiltcat reg001.cat.1 reg001.cat.2 fsort=mag1 +.fi + +2. Repeat example 1 but only output records for which mag1 <= 16.0. + +.nf +cl> afiltcat reg001.cat.1 reg001.cat.3 fsort=mag1 fexpr="mag1 <= 16.0" +.fi + +3. Repeat example 2 but since the input astrometry file has 2 magnitude +columns output a new color field equal to "mag2 - mag1". + +.nf +cl> afiltcat reg001.cat.1 reg001.cat.4 fsort=mag1 fexpr="mag1 <= 16.0" \ +fields="f[*],mag2-mag1" +.fi + +4. Repeat example 1 but overwrite the input astrometry file. + +.nf +cl> page reg001.cat.1 +... examine catalog header to determine name of magnitude field +cl> afiltcat reg001.cat.1 reg001.cat.1 fsort=mag1 +.fi + + +5. Filter a list of input astrometry files by extracting columns 1-4 +but reversing the order of fields 3 and 4. Overwrite the input files. + +.nf +cl> afiltcat @inlist @inlist fields="f[1-2],f4,f3" +.fi + +6. Repeat the previous example for a list of text files which have no catalog +headers but contain the ras and decs in hours and degrees in J2000 +coordinates of a list of source in columns 1 and 2 of a simple text file. + +.nf +cl> afiltcat @inlist @inlist ftype="stext" csystem=j2000 ra="1 hours" \ + dec="2 degrees" mag="3-4" fields="f[1-2],f4,f3" +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +aclist, agetcat, acatpars, afiltpars +.endhelp diff --git a/noao/astcat/doc/afiltpars.hlp b/noao/astcat/doc/afiltpars.hlp new file mode 100644 index 00000000..673f2185 --- /dev/null +++ b/noao/astcat/doc/afiltpars.hlp @@ -0,0 +1,357 @@ +.help afiltpars Mar00 astcat +.ih +NAME +afiltpars -- edit the catalog filtering parameters +.ih +USAGE +afiltpars +.ih +PARAMETERS +.ls fsort = "" +The field or field expression on which to sort the catalog / file records. +The sort may be numeric or character. Sort fields may be expressed by name, +e.g. "mag1" or field number, e.g. "f3". Sort expressions must be a combination +of existing fields, e. g. "mag2 - mag1" or "f4 - f3". By default the records +are not sorted. +.le +.ls freverse = no +Sort in descending order ? +.le +.ls fexpr = yes +The boolean record selection expression. By default all catalog / file records +are selected, otherwise only records matching the selection expression +are selected. Selection expressions must be combination of existing fields +and field expressions, e.g. "mag1 < 16.0", or "(f4 - f3) < 1.5". +.le +.ls fields = "f[*]" +The list of output fields and field expressions. By default the sorted and +selected records are output as is. Output fields may be field names, e.g. +"mag1", field numbers e.g. "f3", or field ranges e.g. "f[1-4]". Output field +expressions must be a combination of existing fields, e.g. "mag2 - mag1", +or "f4 - f3". +.le +.ls fnames = "" +The list of new field names separated by commas. By default new fields, e.g. +fields that are expressions of existing fields are assigned names of the form +"f#" where # is the field sequence number. Field names must be valid tokens, +i.e. they cannot be expressions or contain embedded blanks. +.le +.ls fntypes = "" +The list of new field types separated by commas. By default new fields are +assigned type real. Permitted field types are "s" for string, "i" for +integer, "r" for real, or "d" for double". +.le +.ls fnunits = "" +The list of new field units separated by commas. By default new fields are +assigned units of INDEF. Units specifications may not contain embedded blanks. +.le +.ls fnformats = "" +The list of new field formats. By default string, integer, and floating +point fields are assigned formats of "%10s", "%10d", and "%10g" respectively. +.le +.ls fosystem = "" +The output celestial coordinate system. If fosystem is undefined +it defaults to the catalog celestial coordinate system. Popular options +are "icrs", "j2000.0", "b1950.0". The full set of options can be examined +by typing "help ccsystems". +.le +.ls fira = "ra" +The name of the catalog field containing the right ascension / longitude +of an object. Most users should leave fira set to "ra". If the user knows +the number of the right ascension / longitude field the generic field name +"f#", e.g. "f1" can be used. +.le +.ls fidec = "dec" +The name of the catalog field containing the declination / latitude +of an object. Most users should leave fidec set to "dec". If the user knows +the number of the declination / latitude field the generic field name "f#", +e.g. "f2" can be used. +.le +.ls foraunits = "" +The units of fira. Permitted values are "hours", "degrees", and "radians". If +foraunits is undefined it defaults to the preferred units of the +output celestial coordinate system fosystem, e.g. hours for equatorial +coordinate systems and degrees for ecliptic, galactic, and super-galactic +coordinate systems. +.le +.ls fodecunits = "" +The units of fidec. Permitted values are "degrees" and "radians". If +fodecunits is undefined it defaults to the preferred units of the +output celestial coordinate system fosystem, e.g. degrees for all systems. +.le +.ls foraformat = "" +The format of fira. If undefined foraformat defaults to the equivalent catalog +format. +.le +.ls fodecformat = "" +The format of fidec. If undefined fodecformat defaults to the equivalent +catalog format. +.le +.ls fixp = "xp" +The name of the catalog field containing the predicted x coordinate +of an object. Most users should leave fixp set to "xp". If the user knows +the number of the predicted x coordinate field the generic field name +"f#", e.g. "f1" can be used. +.le +.ls fiyp = "yp" +The name of the catalog field containing the predicted y coordinate +of an object. Most users should leave fiyp set to "yp". If the user knows +the number of the predicted y coordinate field the generic field name +"f#", e.g. "f2" can be used. +.le +.ls fixc = "xc" +The name of the catalog field containing the centered x coordinate +of an object. Most users should leave fixc set to "xc". If the user knows +the number of the centered x coordinate field the generic field name +"f#", e.g. "f1" can be used. +.le +.ls fiyc = "yc" +The name of the catalog field containing the centered y coordinate +of an object. Most users should leave fiyc set to "yc". If the user knows +the number of the centered y coordinate field the generic field name +"f#", e.g. "f2" can be used. +.le +.ls foxformat = "%10.3f" +The format of fixp and fixc. +.le +.ls foyformat = "%10.3f" +The format of fiyp and fiyc. +.le + +.ih +DESCRIPTION +The catalog / file filtering parameters are used to filter the results +of a catalog query before writing the results to disk. Catalog / file filtering +options include: sorting on a field or field expression, +selecting and rejecting records by evaluating a boolean expression +for each record, selecting a subset of the fields for output, +transforming the coordinates from the catalog / file celestial coordinate +system to a user specified celestial coordinate system, and computing new +fields from existing fields. + +\fIfsort\fR and \fIfreverse\fR define the sort field or field expression and +the sort order. Sort fields may be field names or field numbers, e.g. +"mag1" or "f3". By default the sort order is ascending. + +Records are selected or rejected based on the value of the boolean expression +\fIfexpr\fR. By default all catalog / file records are selected. The boolean +selection expression must be function of existing catalog fields, e.g. +the expression "mag1 <= 16.0" will select all records for which the mag1 +field is <= 16.0, and the expression "(f4 - f3) >= 0.0 && (f4 - f3) <= 1.0" +will select all records for which the difference between fields 4 and 3 +is >= 0.0 but <= 1.0. + +The \fIfields\fR parameter defines the list output fields and field +expressions. By default all the +input fields are output. By setting \fIfields\fR appropriately the user +can select a subset of the input fields for output, rearrange the order +of the input fields, and compute new fields. For example setting +fields to "f[2-5]" selects fields 2 to 5 for output; setting fields +to "f[2-3],f5,f4" select fields 2 to 5 but reverses the order of fields +4 and 5; setting fields to "f[2-5],f5-f4" selects fields 2 to 5 and +adds a new field which is the difference between fields 5 and 4. + +By default new fields are assigned names of the form "f#" where # is the field +number, a data type of real, units of INDEF, and formats of %10s, %10d, or +%10g if they are character, integer, or real respectively. Users can define +names, data types, units, and formats for the new fields by setting +the \fIfnames\fR, \fIfntypes\fR, \fIfnunits\fR, and \fIfnformats\fR +parameters. + +The coordinate system, units, or format of the output coordinates may +be changed by setting one or more of the \fIfosystem\fR, \fIforaunits\fR, +\fIfodecunits\fR, \fIforaformat\fR, \fIfodecformat\fR. By default the +filtering code expects the input coordinates to be located in fields +called "ra" and "dec". If these fields do not have valid names then +generic field names of the form "f#" can be substituted. + +The names and format of any newly computed pixel coordinate fields may +be specified by setting one or more of the \fIfixp\fR, \fIfiyp\fR, +\fIfixc\fR, \fIfiyc\fR, \fIfoxformat\fR, or \fIfoyformat\fR parameters. +By default the filtering code expects the pixel coordinates to be located +in fields called "xp", "yp", 'xc", and "yc". If these fields do not have +standard names then generic field names of the form "f#" can be substituted. +.ih +EXPRESSIONS + +The output records are selected on the basis of the input boolean +expression \fIfexpr\fR whose variables are the field names specified +in the configuration file or the generic equivalents f#. If after +substituting the values associated with a particular record into the +field name variables the expression evaluates to yes, that record is +included in the output catalog. Numeric expressions can also be used +to define the sort expression \fIfsort\fR or to define new fields in +\fIfields\fR. + +The supported operators and functions are briefly described below. A detailed +description of the boolean expression evaluator and its syntax can be found +in the manual page for the images package hedit task. + +The following logical operators can be used in the boolean expression. + +.nf + equal == not equal != + less than < less than or equal <= + greater than > greater than or equal >= + or || and && + negation ! pattern match ?= + concatenation // +.fi + +The pattern match character ?= takes a +string expression as its first argument and a pattern as its second argument. +The result is yes if the pattern is contained in the string expression. +Patterns are strings which may contain pattern matching meta-characters. +The meta-characters themselves can be matched by preceding them with the escape +character. The meta-characters listed below. + +.nf + beginning of string ^ end of string $ + one character ? zero or more characters * + white space # escape character \ + ignore case { end ignore case } + begin character class [ end character class ] + not, in char class ^ range, in char class - +.fi + +The expression may also include arithmetic operators and functions. +The following arithmetic operators and functions are supported. + +.nf +addition + subtraction - +multiplication * division / +negation - exponentiation ** +absolute value abs(x) cosine cos(x) +sine sin(x) tangent tan(x) +arc cosine acos(x) arc sine asin(x) +arc tangent atan(x) arc tangent atan2(x,y) +exponential exp(x) square root sqrt(x) +natural log log(x) common log log10(x) +minimum min(x,y) maximum max(x,y) +convert to integer int(x) convert to real real(x) +nearest integer nint(x) modulo mod(x) +.fi + +.ih +FORMATS + +A format specification has the form "%w.dCn", where w is the field +width, d is the number of decimal places or the number of digits of +precision, C is the format code, and n is radix character for +format code "r" only. The w and d fields are optional. The format +codes C are as follows: + +.nf +b boolean (YES or NO) +c single character (c or '\c' or '\0nnn') +d decimal integer +e exponential format (D specifies the precision) +f fixed format (D specifies the number of decimal places) +g general format (D specifies the precision) +h hms format (hh:mm:ss.ss, D = no. decimal places) +m minutes, seconds (or hours, minutes) (mm:ss.ss) +o octal integer +rN convert integer in any radix N +s string (D field specifies max chars to print) +t advance To column given as field W +u unsigned decimal integer +w output the number of spaces given by field W +x hexadecimal integer +z complex format (r,r) (D = precision) + +Conventions for w (field width) specification: + + W = n right justify in field of N characters, blank fill + -n left justify in field of N characters, blank fill + 0n zero fill at left (only if right justified) +absent, 0 use as much space as needed (D field sets precision) + +Escape sequences (e.g. "\n" for newline): + +\b backspace (not implemented) +\f formfeed +\n newline (crlf) +\r carriage return +\t tab +\" string delimiter character +\' character constant delimiter character +\\ backslash character +\nnn octal value of character + +Examples + +%s format a string using as much space as required +%-10s left justify a string in a field of 10 characters +%-10.10s left justify and truncate a string in a field of 10 characters +%10s right justify a string in a field of 10 characters +%10.10s right justify and truncate a string in a field of 10 characters + +%7.3f print a real number right justified in floating point format +%-7.3f same as above but left justified +%15.7e print a real number right justified in exponential format +%-15.7e same as above but left justified +%12.5g print a real number right justified in general format +%-12.5g same as above but left justified + +%h format as nn:nn:nn.n +%15h right justify nn:nn:nn.n in field of 15 characters +%-15h left justify nn:nn:nn.n in a field of 15 characters +%12.2h right justify nn:nn:nn.nn +%-12.2h left justify nn:nn:nn.nn + +%H / by 15 and format as nn:nn:nn.n +%15H / by 15 and right justify nn:nn:nn.n in field of 15 characters +%-15H / by 15 and left justify nn:nn:nn.n in field of 15 characters +%12.2H / by 15 and right justify nn:nn:nn.nn +%-12.2H / by 15 and left justify nn:nn:nn.nn + +\n insert a newline +.fi + +.ih +EXAMPLES +1. List the catalog / file filtering parameters. + +.nf +cl> lpar afiltpars +.fi + +2. Edit the catalog / file filtering parameters. + +.nf +cl> afiltpars +... edit the parameters in the usual way +... type :wq to quit and save the edits +.fi + +3. Edit the catalog filtering parameters from the agetcat task. + +.nf +cl> epar agetcat +... edit the agetcat parameters +... move to the afiltpars parameter line and type :e +... edit the afiltpars parameters +... type :wq to quit and save the afiltpars edits +... continue editing the remaining agetcat parameters +... type :go to execute the task +.fi + +4. Save the current afiltpars parameter values in a text file called +afilt1.par. Use the saved parameter set in the next call to the agetcat +task. + +.nf +cl> epar afiltpars +... edit some parameters in the usual way +... type :w afilt1.par +... type :q to quit +cl> agetcat ... afiltpars=afilt1.par ... +.fi +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +agetcat, afiltcat +.endhelp 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 diff --git a/noao/astcat/doc/agetim.hlp b/noao/astcat/doc/agetim.hlp new file mode 100644 index 00000000..1809f3f9 --- /dev/null +++ b/noao/astcat/doc/agetim.hlp @@ -0,0 +1,242 @@ +.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 diff --git a/noao/astcat/doc/ahedit.hlp b/noao/astcat/doc/ahedit.hlp new file mode 100644 index 00000000..fd39c10c --- /dev/null +++ b/noao/astcat/doc/ahedit.hlp @@ -0,0 +1,181 @@ +.help ahedit Mar00 astcat +.ih +NAME +ahedit -- Add wcs and / or standard keywords to the image header +.ih +USAGE +ahedit images imsurveys +.ih +PARAMETERS +.ls images +The list of input images to be edited. +.le +.ls imsurveys +The input image survey that is the source of the input images. If imsurveys +is defined then the wcs status and the wcs and standard keyword parameter names +and values are read from the image survey configuration file \fIimdb\fR. If +imsurveys is undefined these quantities are read from the \fIwcs\fR parameter +and the default \fIawcspars\fR and \fIaimpars\fR parameter sets. +.le +.ls hupdate = yes +Update the image headers ? If hupdate = no the image header edits are +listed but the headers are not updated. +.le +.ls wcsedit = no +Convert a DSS WCS to a FITS WCS or add an approximate FITS style WCS to the +input image headers ? If \fIimsurveys\fR is defined the WCS status of the +survey images plus approximate image center coordinates, scale, orientation, +and projection information are read from the image surveys configuration file +\fIimdb\fR. If \fIimsurveys\fR is undefined these quantities are read +from the \fIwcs\fR parameter and \fIawcspars\fR parameter set. +.le +.ls wcs = "none" +The default wcs status of the input images if \fIimsurveys\fR is undefined. +The options are: +.ls fits +The input image is assumed to have a FITS WCS. No new FITS WCS is written. +.le +.ls dss +The input image is assumed to have a DSS WCS. The equivalent FITS WCS +is added, but the DSS WCS is left unchanged. +.le +.ls none +The input image is assumed to have no WCS. The parameters in \fIawcspars\fR +are used to create an approximate FITS WCS. +.le +.le +.ls awcspars = "" +The default WCS parameter set. If \fIwcsedit\fR = yes and \fIimsurveys\fR +is undefined then the awcspars parameters are used to create an approximate +FITS WCS. For more information about the awcspars parameters type +"help awcspars". +.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. +If \fIimsurveys\fR is undefined the standard keyword names and values +are read from the images surveys configuration file \fIimdb\fR. If +\fIimsurveys\fR is defined they are read from the \fIaimpars\fR parameter set. +.le +.ls aimpars = "" +The default standard image header keywords parameter set. If \fIhdredit\fR = +yes and \fIimsurveys\fR is undefined the parameter names and values +in \fIaimpars\fR are used to write the standard image header keywords. For more +information about these parameters type "help aimpars". +.le +.ls update = no +Update the default values of the algorithm parameter sets, e.g. aregpars, +\fIawcspars\fR, and \fIaimpars\fR 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 + +Ahedit adds an approximate FITS WCS and / or a standard set of keyword value +pair to the list of images \fIimages\fR extracted from the image survey +\fIimsurveys\fR. If hupdate = no the image edits are listed but not +implemented. + +If \fIwcsedit\fR = yes then either an existing DSS WCS is converted to +a FITS WCS or an approximate FITS WCS is added to the input image. If +\fIimsurveys\fR is undefined the current WCS status and WCS information +is read from the image surveys configuration file \fIimdb\fR. If +\fIimsurveys\fR is undefined the WCS status and coordinate information +are read from \fIwcs\fR parameter and the default WCS parameter set +\fIawcspars\fR. In both cases 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 image 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 or the awcspars parameter set type "help imsurveys" and / or +"help awcspars". + +If \fIhdredit\fR = yes then a standard set of keyword equal value +pairs are added to the image headers. If \fIimsurveys\fR is defined +the standard keyword name and value pairs are read from the image surveys +configuration file. If \fIimsurveys\fR is undefined they are read from +the standard image keywords parameter set \fIaimpars\fR. In both cases 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, +\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 then the fIawcspars\fR, +and \fIaimpars\fR parameter sets are updated at task termination. If +\fIverbose\fR = yes then detailed status reports are issued as the task +executes. + +.ih +EXAMPLES + +1. List the header edits required to create a FITS WCS from a DSS WCS +for a set of images extracted from the dss1@cadc. + +.nf +cl> ahedit @imlist dss1@cadc hupdate- wcsedit+ hdredit- +.fi + +2. Repeat the previous example but actually do the edits. + +.nf +cl> ahedit @imlist dss2@cadc hupdate+ wcsedit+ hdredit- +.fi + +3. Repeat the previous example but get the current WCS stats from the user +rather than from the image survey configuration file. + +.nf +cl> ahedit @imlist "" hupdate+ wcsedit+ wcs=dss hdredit- +.fi + +4. Add an approximate FITS WCS to an image for which the coordinates +of the image center in hours and degrees are stored in the keywords +RA and DEC, the epoch of the image center coordinates is stored in EQUINOX, +the image scale is 0.261" per pixel and east is left and north is down. + +.nf +cl> ahedit image "" wcsedit+ wcs="none" wraref="RA" wdecref="DEC" \ +wxmag=0.26 wymag=0.26 wxrot=270 wyrot=90 wsystem="EQUINOX" hdredit- + +.fi + +5. Add the standard keyword name and values pairs for a list +of images extracted from the dss1@cadc. + +.nf +cl> ahedit @imlist dss1@cadc hupdate+ wcsedit- hdredit+ +.fi + +6. Store the CCD saturation limit in the image header in the EDATAMAX +keyword. Set the minimum good data limit at the same time. + +.nf +cl> ahedit image "" hupdate+ wcsedit- hdredit+ edatamin=-100.0 \ +edatamax=32000 +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +aslist, adumpim, aregpars, awcspars, aimpars +.endhelp diff --git a/noao/astcat/doc/aimfind.hlp b/noao/astcat/doc/aimfind.hlp new file mode 100644 index 00000000..04d1a46e --- /dev/null +++ b/noao/astcat/doc/aimfind.hlp @@ -0,0 +1,148 @@ +.help aimfind Mar00 astcat +.ih +NAME +aimfind -- Select images containing catalog data and predict pixel coordinates +for the catalog objects +.ih +USAGE +aimfind images output imfile +.ih +PARAMETERS +.ls images +The input image list. The input images must contain a valid fits world +coordinate system which is used to determine the catalog extraction region. +.le +.ls output +The list of output astrometry file names. The number of output file names +must be equal to the number of input images. Output files are only created +if at least one catalog object is in the image. By default the output files +are assigned names of the form "image.cat.#", e.g. "image.cat.1". +.le +.ls imfile +The list of images containing catalog data. +.le +.ls catalogs = ")_.catalogs" +The input astrometry catalog. 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 append = no +By default the predicted pixel coordinates are prepended to each selected +output file record. If append = yes they are appended to each selected +record instead. +.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 + +Aimfind selects those images from the input image list \fIimages\fR +which contain one or more catalog \fIcatalogs\fR objects and writes +the resulting catalog records along with predicted pixel coordinates to +\fIoutput\fR and the selected image name to \fIimfile\fR. The input images +must contain a valid FITs wcs. + +For each input image aimfind determines the region of the sky covered +by the image, formats the appropriate 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 form catalog@site, e.g. lan92@noao. + +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 permit 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. At present the names, data types, units, and format of the +predicted pixel coordinates computed by aimfind are fixed at "xp,yp", +"d,d", "pixels,pixels", and "%10.3f,%10.3f" respectively. 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 \fIappend\fR = no then the values of the predicted pixel coordinates +are prepended to each selected catalog record. If append = tes they +are appended instead. + +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. Determine which images in the input image list contain Landolt standards. + +.nf +cl> aimfind *.imh "" imlist catalogs=lan92@noao +cl> page imlist +.fi + +2. Repeat the previous example but write an output astrometry file for +each selected image. + +.nf +cl> aimfind *.imh default imlist catalogs=lan92@noao +.fi + +3. Repeat example 2 but sort the output on a field called v. + +.nf +cl> aimfind *.imh default filter+ fsort="v" +.fi + +4. Repeat example 2 but transform the catalog coordinates to the B1950 +system. + +.nf +cl> aimfind *.imh default filter+ fosystem="B1950" +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +aclist, adumpcat, agetcat, afiltpars +.endhelp diff --git a/noao/astcat/doc/aimpars.hlp b/noao/astcat/doc/aimpars.hlp new file mode 100644 index 00000000..d699e05a --- /dev/null +++ b/noao/astcat/doc/aimpars.hlp @@ -0,0 +1,141 @@ +.help aimpars Mar00 astcat +.ih +NAME +aimpars -- Edit the standard image header keyword set +.ih +USAGE +aimpars +.ih +PARAMETERS +.ls observat = "OBSERVAT" +The image header keyword defining the observatory at which the data +was taken or the name of the observatory. If the observatory is defined then +the keyword "OBSERVAT" is written to the image header if it does not +already exist. +.le +.ls esitelng = "INDEF", esitelat = "INDEF" +The image header keywords defining the longitude and latitude of the +observatory in degrees or the longitude and latitude values in degrees. +If the longitude and latitude are defined the keywords "ESITELNG" and +"ESITELAT" are written to the image header if they do not already exist. +.le +.ls esitealt = "INDEF" +The image header keyword defining the altitude of the observatory in meters +or the altitude itself in meters. If the altitude is defined the keyword +"ESITEALT" is written to the image header if it does not already exist. +.le +.ls esitetz = "INDEF" +The image header keyword defining the timezone of the observatory +in hours from the Greenwich meridian or the timezone value +in hours from the Greenwich meridian. Positive values correspond to time +zones west of the meridian. If the time zone is defined the keyword +"ESITETZ" is written to the image header if it does not already exist. +.le +.ls emjdobs = "MJD-OBS" +The image header keyword defining the effective MJD of the observation +or the MJD. MJD-OBS normally defines the time of the beginning +of the observation. Users may wish to change this value to represent +the MJD at mid-exposure. If the effective MJD is defined the keyword +"EMJDOBS" is written to the image header if it does not already exist. +.le +.ls edatamin = "INDEF", edatamax = "INDEF" +The image header keywords defining the minimum and maximum good data +limits in ADU or the minimum and maximum good data values in ADU. +If these limits are defined the keywords "EDATAMIN" and "EDATAMAX" +are written to the image header if they do not already exist. +.le +.ls egain = "GAIN", erdnoise = "RDNOISE" +The image header keywords defining the effective gain in electrons per ADU +and readout noise in electrons or the gain and readout noise values in +electrons per ADU and electrons. If the gain and readout noise are defined +the keywords "EGAIN" and "ERDNOISE" are written to the image header if they do +not already exist. +.le +.ls ewavlen = "INDEF" +The image header keyword defining the effective wavelength in microns or +the effective wavelength value in microns. If the effective wavelength is +defined the keyword "EWAVLEN" is written to the image header if it does +not already exist. +.le +.ls etemp = "INDEF" +The image header keyword defining the effective temperature in degrees +or the effective temperature values in degrees. If the effective wavelength +is defined the keyword "ETEMP" is written to the image header it does +not already exist. +.le +.ls epress = "INDEF" +The image header keyword defining the effective pressure in millibars or +the effective pressure values in millibars. If the effective pressure is +defined the keyword "EPRESS" is written to the image header if it does +not already exist. +.le + +.ih +DESCRIPTION + +The standard image parameter set is used to encode quantities in the image +headers that may be required by the astrometric analysis tasks. The current +parameter set divides into two parameter groups: parameters +concerned with locating stars in an image and computing accurate pixel +coordinates and instrumental magnitudes \fIedatamin\fR, \fIedatamax\fR, +\fIegain\fR, and \fIerdnoise\fR, and parameters required to transform +from mean to observed place \fIobservat\fR, \fIesiteng\fR, +\fIesitelat\fR, \fIesitealt\fR, \fIesitetz\fR, \fIewavlen\fR, +\fIetem\fR, \fIepress\fR. The latter group of parameter is required for +astrometric analyses carried out in observed place rather than +mean place. + +If the quantity defined by the aimpars parameter is defined, i.e. the +parameter value is an image header keyword which defines a valid value, +or the parameter value is itself a valid value, then a keyword +with the same name as the parameter name is inserted into the image +header, if one with that name does not already exist. + +.ih +EXAMPLES + +1. List the default image header parameters. + +.nf +cl> lpar aimpars +.fi + +2. Edit the default image header parameters. + +.nf +cl> aimpars +... edit the parameters in the usual way +... type :wq to quit and save the edits +.fi + +3. Edit the default image header parameters from the agetim task. + +.nf +cl> epar agetim +... edit the agetim parameters +... move to the agetim parameter line and type :e +... edit the aimpars parameters +... type :wq to quit and save the aimpars edits +... continue editing the remaining aimpars parameters +... type :go to execute the task +.fi + +4. Save the current awcspars parameter values in a text file called +aimhdr1.par. Use the saved parameter set in the next call to the agetim +task. + +.nf +cl> epar aimpars +... edit some parameters in the usual way +... type :w aimhdr1.par +... type :q to quit +cl> agetim ... aimpars=aimhdr1.par ... + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +agetim +.endhelp diff --git a/noao/astcat/doc/aregpars.hlp b/noao/astcat/doc/aregpars.hlp new file mode 100644 index 00000000..68f56aff --- /dev/null +++ b/noao/astcat/doc/aregpars.hlp @@ -0,0 +1,106 @@ +.help aregpars Mar00 astcat +.ih +NAME +aregpars -- edit the region extraction parameters +.ih +USAGE +aregpars +.ih +PARAMETERS +.ls rcra = "00:00:00.0" +The right ascension / longitude of the center of the region to be extracted. +.le +.ls rcdec = "+00:00.00" +The declination / latitude of the center of the region to be extracted. +.le +.ls rrawidth = 10.0 +The right ascension / longitude width in minutes of arc of the region to +be extracted. +.le +.ls rdecwidth = 10.0 +The declination / latitude width in minutes of arc of the region to +be extracted. +.le +.ls rcsystem = "" +The input celestial coordinate system. This is the celestial coordinate system +of the region center. If the input celestial coordinate system is undefined it +defaults to the query celestial coordinate system. Popular options are +"icrs", "j2000.0", and "b1950.0". The full set of options can be examined +by typing "help ccsystems". +.le +.ls rcraunits = "" +The units of rcra. Permitted values are "hours", "degrees", and radians. If +rcraunits is undefined it defaults to the preferred units of the +input celestial coordinate system, e.g. hours for equatorial coordinate +system, degrees for ecliptic, galactic, and super-galactic coordinate +systems. +.le +.ls rcdecunits = "" +The units of rcdec. Permitted values are "degrees" and "radians". If rcdecunits +is undefined it defaults to the preferred units of the input celestial +coordinate system, e.g. degrees for all systems. +.le +.ih +DESCRIPTION +The region to extracted from the selected astrometric catalog or image survey +is defined by the aregpars parameters \fIrcra\fR, \fIrcdec\fR, \fIrcrawidth\fR, +and \fIrcdecwidth\fR. + +\fIrcra\fR and \fIrcdec\fR are defined in the input celestial coordinate system +specified by \fIrcsystem\fR. If \fIrcsystem\fR is undefined it defaults to the +query celestial coordinate system defined by the qsystem query parameter in +the catalog configuration file. + +\fIrcra\fR and \fIrcdec\fR are expressed in the units specified by +\fIrcraunits\fR, and \fIrcdecunits\fR. If undefined \fIrcraunits\fR and +\fIrcdecunits\fR are expressed in the preferred units of the input +celestial coordinate system, e.g. hours and degrees for equatorial coordinate +systems, and degrees and degrees for ecliptic, galactic, +and super-galactic coordinate systems. +.ih +EXAMPLES +1. List the region extraction parameters. + +.nf +cl> lpar aregpars +.fi + +2. Edit the region extraction parameters. + +.nf +cl> aregpars +... edit the parameters in the usual way +... type :wq to quit and save the edits +.fi + +3. Edit the region extraction parameters from the agetcat task. + +.nf +cl> epar agetcat +... edit the agetcat parameters +... move to the aregpars parameter line and type :e +... edit the aregpar parameters +... type :wq to quit and save the aregpars edits +... continue editing the remaining agetcat parameters +... type :go to execute the task +.fi + +4. Save the current aregpars parameter values in a text file called +areg1.par. Use the saved parameter set in the next call to the agetcat +task. + +.nf +cl> epar aregpars +... edit some parameters in the usual way +... type :w areg1.par +... type :q to quit +cl> agetcat ... aregpars=areg1.par ... +.fi +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +agetcat, agetim, help ccsystems +.endhelp diff --git a/noao/astcat/doc/aslist.hlp b/noao/astcat/doc/aslist.hlp new file mode 100644 index 00000000..6dea51aa --- /dev/null +++ b/noao/astcat/doc/aslist.hlp @@ -0,0 +1,60 @@ +.help aslist Feb00 astcat +.ih +NAME +aslist -- list the supported image surveys +.ih +USAGE +aslist catalogs +.ih +PARAMETERS +.ls imsurveys +The names of the image surveys to be listed. If surveys = "*" then +all the image surveys in the image survey configuration file are listed. +.le +.ls verbose = no +List the image survey wcs and keyword information after the image survey +name ? +.le +.ls imdb = ")_.imdb" +The image survey configuration file. The value of imdb defaults to the value +of the package parameter of the same name. The default image survey +configuration file is "astcat$lib/imdb.dat". +.le +.ih +DESCRIPTION +Aslist lists the supported image surveys specified by the +\fIimsurveys\fR parameter. If imsurveys = "*" then all the supported image +surveys are listed, otherwise only the image survey names specified by the +user are listed. Valid image survey names have the form imsurvey@site, e.g. +"dss1@cadc". If \fIverbose\fR = "yes", then the image survey wcs and +keyword information is listed after the image survey name. + +The image survey names, addresses, query formats, output formats, wcs formats, +and keyword formats, are specified in the image survey configuration file +\fIimdb\fR. By default the image survey configuration file names defaults to +the value of the imdb package parameters. The default image survey +configuration file is "astcat$lib/imdb.dat". Users can add records +to this file or create their own configuration file. +.ih +EXAMPLES + +1. List all the image surveys in the image survey configuration file. + +.nf +cl> aslist * +.fi + +2. List the wcs and keyword information for the dss1@cadc image survey. + +.nf +cl> aslist dss1@cadc verbose+ +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +aclist +.endhelp diff --git a/noao/astcat/doc/awcspars.hlp b/noao/astcat/doc/awcspars.hlp new file mode 100644 index 00000000..c6273d2c --- /dev/null +++ b/noao/astcat/doc/awcspars.hlp @@ -0,0 +1,113 @@ +.help awcspars Mar00 astcat +.ih +NAME +awcspars -- edit the default world coordinate system parameters +.ih +USAGE +awcspars +.ih +PARAMETERS +.ls wxref = "INDEF", wyref = "INDEF" +The image header keyword names or the numerical values of the x and y reference +point in pixels. If wxref = "INDEF" and wyref = "INDEF" the reference +point defaults to the center of the image. +.le +.ls wxmag = "INDEF", wymag = "INDEF" +The image header keyword names or the numerical values of the x and y scale +factors in arcseconds per pixel. If wxmag or wymag = are undefined a new +wcs cannot be created. +.le +.ls wxrot = "180.0", wyrot = "0.0" +The image header keyword names or the numerical values of the x and y rotation +angles in degrees measured counter-clockwise to the positive x and y image +axes. The default orientation is east=left, north=up. Wxrot values of 0.0, +90.0, 180.0, and 270.0 correspond to east=right, up, left, and down +respectively. Wyrot values of 0.0, 90.0, 180.0, and 270.0 correspond to +north=up, left, down, and right respectively. +.le +.ls wraref = "RA", wdecref = "DEC" +The image header keyword names or the numerical values of the reference +point in celestial coordinates. If wraref and wdecref are undefined +a new wcs cannot be created. +.le +.ls wraunits = "", wdecunits = "" +The units of the reference point celestial coordinates. The options are +"hours", "degrees", and "radians" for the ra coordinate and "degrees" +and "radians" for the dec coordinate. If wraunits and wdecunits are undefined +they default to the preferred units of the reference system. +.le +.ls wproj = "tan" +The sky projection geometry. The most commonly used projections are "tan", +"arc", "sin", and "lin". Other supported projections are "ait","car", "csc", +"gls", "mer", "mol", "par", "pco", "qsc", "stg", "tsc", and "zea". +.le +.ls wsystem = "EQUINOX" +The image header keyword name or string defining the celestial coordinate +system of the reference point. The most common values for wsystem are +"2000.0", "1950.0", "J2000.0", and "B1950.0". Type "help ccssytems" to get +a full list of options. +.le +.ih +DESCRIPTION +The default wcs parameters are used to create an approximate FITS wcs for +an images which do not have one. Creating an approximate header +from the telescope pointing position and the known scale and orientation +of the detector can make later steps like locating the catalog stars +for computing an accurate plate solution simpler. + +In coordinates of the reference point in pixels and celestial coordinates +\fIwxref\fR, \fIwyref\fR, \fIwraref\fR, \fIwdecref\fR, the scale factors +\fIwxmag\fR and \fIwymag\fR, and the orientation \fIwxrot\fR and \fIwyrot\fR +can be read from the image header or set by value. The coordinate system +and units of the celestial coordinates of the reference point \fIwsystem\fR +and \fIwraunits\fR and \fIwdecunits\fR must be set explicitly. The image +projection function \fIwproj\fR must also be set separately. + +.ih +EXAMPLES +1. List the default wcs parameters. + +.nf +cl> lpar awcspars +.fi + +2. Edit the default wcs parameters. + +.nf +cl> awcspars +... edit the parameters in the usual way +... type :wq to quit and save the edits +.fi + +3. Edit the default wcs parameters from the agetim task. + +.nf +cl> epar agetim +... edit the agetim parameters +... move to the agetim parameter line and type :e +... edit the awcspars parameters +... type :wq to quit and save the awcspars edits +... continue editing the remaining awcspars parameters +... type :go to execute the task +.fi + +4. Save the current awcspars parameter values in a text file called +awcs1.par. Use the saved parameter set in the next call to the agetim +task. + +.nf +cl> epar awcspars +... edit some parameters in the usual way +... type :w awcs1.par +... type :q to quit +cl> agetim ... awcspars=awcs1.par ... +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +agetim, ahedit +.endhelp diff --git a/noao/astcat/doc/catalogs.hlp b/noao/astcat/doc/catalogs.hlp new file mode 100644 index 00000000..6852d102 --- /dev/null +++ b/noao/astcat/doc/catalogs.hlp @@ -0,0 +1,295 @@ +.help catalogs Mar00 astcat +.ih +NAME +catalogs -- describe the catalog configuration file +.ih +USAGE +help catalogs +.ih +ASTROMETRIC CATALOGS + +An astrometric catalog is a remote or local catalog containing accurate +positional data for a large region of the sky, from which accurate positional +data for a small region of the sky may be extracted by specifying an extraction +region. + +Astrometric catalogs may be installed locally or accessed remotely. Each +supported catalog must have a record in the catalog configuration file +specifying the catalog network address, the catalog query format, +and the query output format. The default configuration file is +"astcat$lib/catdb.dat". A list of the supported catalogs can be obtained +by running the aclist task. + +.ih +THE CATALOG CONFIGURATION FILE + +The catalog configuration file specifies the network address, the query +format, and the output format for each supported catalog server. Each catalog +server record is accessed via a record name of the form catalog@site, +e.g. "usno2@noao". Adding support for a new catalog server requires adding +a new record to the configuration file. Responding to changes in the behavior +of a supported catalog server requires editing the existing record. In +either case no modification of the compiled code should be required. + +The server network address tells the catalog access code where and how to +connect to the network. Each network address has the syntax +domain:port:address:flags e.g. "inet:80:www.noao.edu:text". + +The query format specifies the form of the query server command, and the +names, default values, units, and formats of the query parameters. A set of +query parameter names are reserved for accessing astrometric catalogs +including "ra", "dec", "radius", "hwidth", "width", "xwidth", and "ywidth". The +astcat package recognizes the reserved query parameter names, +replaces the default query parameter values with the user supplied ones, +and sends the query to the catalog server. "ra" and "dec" always refer +to the center of the region to be extracted. The size parameter is +always input by the user as a width in ra and dec in arcminutes. This quantity +is translated into a radius like parameter or a width like parameter +depending on whether the query parameter is defined as "radius", "hwidth", +"width", "xwidth", "ywidth", "xhwidth", "yhwidth", "rawidth", "decwidth", +"rahwidth", "dechwidth", etc. Most catalogs use "radius", "hwidth", or +"width" in their queries. + +The server output format specifies the form of the expected server output: +the data stream type, the record size, and the name, location, +size, data type, units and format of each field in a record. A set of +standard field names is reserved for accessing the output of astrometric +catalog servers including "id", "ra", "dec", and "mag[1-n]". The astcat +package tasks recognize the reserved field names and use the query output +description to decode the catalog records. + +.ih +SAMPLE CATALOG RECORD + +The following two examples illustrate the main features of the catalog +configuration file record. Both records describe the same catalog server +but define the output query format in different ways. + +.nf +begin susno2@noao +address inet:80:www.noao.edu:text +query GET /cgi-bin/usno/usnoextract?search=yes&ra=%-s&dec=%-s&width=%-s HTTP/1.0 +\n\n +nquery 4 + ra 00:00:00.00 hours %0.2h + dec 00:00:00.0 degrees %0.1h + radius 5.0 minutes %0.1f + qsystem J2000.0 INDEF %s +type stext + hskip 10 + tskip 6 + recsize 0 + triml 0 + trimr 4 +nheader 1 + csystem J2000.0 +nfields 4 + ra 1 0 d hours %12.3h + dec 2 0 d degrees %12.2h + mag1 3 0 r INDEF %4.1f + mag2 4 0 r INDEF %4.1f +.fi + +.nf +begin busno2@noao +address inet:80:www.noao.edu:text +query GET /cgi-bin/usno/usnoextract?search=yes&ra=%-s&dec=%-s&width=%-s HTTP/1.0 +\n\n +nquery 4 + ra 00:00:00.00 hours %0.2h + dec 00:00:00.0 degrees %0.1h + radius 5.0 minutes %0.1f + qsystem J2000.0 INDEF %s +type btext + hskip 10 + tskip 6 + recsize 44 + triml 0 + trimr 4 +nheader 1 + csystem J2000.0 +nfields 4 + ra 1 13 d hours %12.3h + dec 14 14 d degrees %12.2h + mag1 28 6 r INDEF %4.1f + mag2 34 6 r INDEF %4.1f +.fi + +The beginning of a new catalog record is marked by a line which looks like +"begin catname" where catname is a unique name of the form catalog@site. +More than one name can access the same catalog server. Multiple entries for +the same catalog are used to define a different query format or to interpret +the query output in different ways. For example if the catalog server supports +output record selection by magnitude then the query can be defined to make use +this feature. In other cases it can be advantageous to interpret the server +output as blocked text rather than simple text. + +The \fIaddress\fR, \fIquery\fR and \fInquery\fR keywords are required and +define the network address, query command format and query parameters for +the catalog server. + +The \fIaddress\fR keyword "domain", "port", and "flags" fields are almost +always "inet", "80", and "text" respectively. The remaining field +is the address field "www.noao.edu" in this case. + +The \fIquery\fR keyword defines the query command. The form of the query command +is server dependent. Note the %-s formatting strings in the above examples. +These strings are replaced by the query parameter values supplied +by the user or by the default query parameter values. + +The number of query parameters is defined by the \fInquery\fR parameter. The +number of query parameters must be greater than or equal to the number of "-%s" +strings in the query keyword value. The name, default value, units, +and format of each query parameter is listed below the nquery keyword and value, +one query parameter description per line. Alert users will notice that in the +above examples the number of query parameters is 4, but there are only 3 "%-s" +strings in the query keyword value. In these examples the qsystem query +parameter, which defines the coordinate system of the ra and dec query +parameters, is fixed at J2000. For some servers qsystem may be a true query +parameter, i.e. the server may accept coordinates in B1950 or J2000 +or some other system. + +Users must use the standard query parameter names "ra", "dec", and "qsystem" +to define the extraction region center and its coordinate system, and one or +more of "radius", "hwidth", "xhwidth", "yhwidth", "width", "xwidth", and +"ywidth" to define the extraction +region size. Currently the units of "ra" may be "hours", "degrees", or +"radians", the units of dec may be "degrees" or "radians", and units of the +size query parameter may be "degrees" or "arcmin". +The qsystem parameter may be any one of the supported celestial coordinate +systems. The most popular values are "icrs", "J2000", and "B1950". +For more information on coordinate systems type "help ccsystems". The +query parameter formats are used to convert +the numerical values supplied by the user to string arguments that +can be passed to the query command. + +The \fItype\fR keyword defines the query output type. The current options +are "stext" for simple text and "btext" for blocked text. Simple text +contains newline delimited records and whitespace delimited fields. +Blocked text contains newline delimited records and fixed position and size +fields. If the type keyword is missing "stext" is assumed. + +The \fIrecsize\fR keyword is the maximum length of the record in characters +including the newline character. Records greater in length than recsize are +skipped. If undefined the recsize keyword defaults to 0 meaning the record +size may not be fixed. + +The \fIhskip\fR, \fItskip\fR, \fIltrim\fR, and \fItrim\fR keywords define +the number of header and trailer records in the server output to skip, and +the number of header and trailer characters in each record to skip. The +latter 2 keywords can be used to trim (actually replace with blanks) leading +and trailing characters in each record. If absent all 4 keywords default to +zero. + +The \fInheader\fR keyword defines the number of header keywords. Header +keywords are global keywords which apply to all the output records. +There may be any number of header keywords or none. The header keyword +and value pairs are copied to the headers of the astrometry files created +by astcat. For most astrometry catalog the only header parameter is +\fIcsystem\fR which specifies the coordinate system of the query output +coordinates. + +The \fInfields\fR keyword specifies the number of fields in each output record. +The name, offset, size, datatype, units, and format of each field follow +the nfields keyword and value pair, +one field description per line. For simple text files the offset is the field +or column number and the field size is 0. For blocked text files the +offset is the 1-indexed position of the first character in the field and +size is the field size in characters. Using a blocked text description can +be useful for dealing with fields containing embedded blanks. + +Users should use the reserved standard fields names "id", "ra", "dec", "mag#" +etc to define the standard field names. The current list of standard field +names is \fIid\fR, \fIra\fR, \fIdec\fR, \fIera\fR, \fIedec\fR, \fIpmra\fR, +\fIpmdec\fR, \fIepmra\fR, \fIepmdec\fR, \fIcatsystem\fR, \fIequinox\fR, +\fIepoch\fR, \fIpx\fR, \fIrv\fR, \fIepx\fR, \fIerv\fR, \fImag\fR, \fIcolor\fR, +\fIemag\fR, \fIecolor\fR, \fIxp\fR, \fIyp\fR, \fIxc\fR, \fIyc\fR, \fIexc\fR, +\fIeyc\fR, \fIimag\fR, and \fIeimag\fR. + +.ih +INSTALLING A NEW CATALOG RECORD + +Some users may wish to install a local version of a standard catalog, +or add support for a new catalog server. The procedure for doing this +is outlined below. + +To install a new catalog record. + +.ls [1] +Create a new configuration file by making a copy of the existing one. +.le + +.ls [2] +Determine a unique name for the catalog server. This name should be short and +have the form catalog@site, e.g. "usno2@noao". Existing names can be +reviewed with the aclist task. +.le + +.ls [3] +Determine the appropriate values for the address, query, and nquery +keywords and enter these quantities in the catalog record. Determine the name, +default value, units and format for each query parameter and enter these +quantities in the catalog record in the order they are requested by +the query parameter string. Make sure that all the query keyword value +parameter format strings are -%s, that the value of the nquery keyword +is greater than or equal to the number of %-s strings in the query keyword +value, and that standard query parameter names are used where possible. +.le + +.ls [4] +Determine the query output type. If the query output type is unknown set +type to "stext". Leave the recsize, hskip, tskip, ltrim, and rtrim parameters +undefined. +.le + +.ls [5] +Set the nheader keyword value to 1 and determine the appropriate value for +the csystem header keyword. +.le + +.ls [6] +Set the nfields keyword to 0. +.le + +.ls [7] +Run the adumpcat task. Adumpcat tests the address and query parts of the +catalog record but dumps the query results directly to a text file without +modification. If adumpcat fails either the network connection is bad +or the address and / or query format is incorrect. +.le + +.ls [8] +Examine the adumpcat results. Determine whether the output is simple text +or blocked text. Simple text is usually the best choice. However if the +record fields contain embedded blanks it may be necessary to set type +to blocked text. Are there fixed numbers of leading and trailing junk records ? +If so set hskip and tskip appropriately. Are there fixed numbers of leading and +trailing junk record characters ? If so set ltrim and rtrim +appropriately. If the record size in characters fixed or does it +have a maximum size ? If so set recsize appropriately but remember to +include the newline character in the record size. +.le + +.ls [9] +Use the adumpcat task results to determine the value of the nfields parameter +and the required field descriptions. +Determine the name, position, size, data type, units, and format for +each field in the output records. Use the standard field names +and the standard field data types if possible. It is +a good idea to set the data type of coordinate fields to double. Check that +the units of the coordinate fields are correct as these are used to do +coordinate conversions. +.le + +.ls [10] +Run the agetcat task using the new catalog record and catalog configuration +file. Examine the header of the output astrometry file to make sure +the header and field descriptions have been transferred correctly. Apply a +few filtering options, i.e. sort on a field, or select a subset of fields for +output, to test the correctness of the field descriptions. +.le + +.ih +SEE ALSO +aclist, files +.endhelp diff --git a/noao/astcat/doc/ccsystems.hlp b/noao/astcat/doc/ccsystems.hlp new file mode 100644 index 00000000..4e67c568 --- /dev/null +++ b/noao/astcat/doc/ccsystems.hlp @@ -0,0 +1,210 @@ +.help ccsystems Mar00 astcat +.ih +NAME +ccsystems -- list and describe the supported coordinate systems +.ih +USAGE +help ccsystems +.ih +CATALOG ACCESS COORDINATE SYSTEMS + +Astcat supports several catalog access coordinate systems and manages all the +required transformation between them based on input from the user and +information in the catalog configuration file. + +.ls The Input Coordinate System +The input coordinate system specifies the coordinate system +of the region center coordinates used to extract data from a +catalog. The input coordinate +system is normally defined by the user. If undefined, the input coordinate +system defaults to the query coordinate system. +.le +.ls The Query Coordinate System +The query coordinate system specifies the coordinate system of the coordinates +used to formulate a catalog query. The query coordinate +system is normally defined in the catalog configuration file. +If undefined the query coordinate system defaults to the catalog +coordinate system. Coordinates in the input coordinate system +must be transformed to the query coordinate system in order to formulate +a correct query. +.le +.ls The Catalog Coordinate System +The catalog coordinate system is the coordinate system of the astrometric +catalog. The catalog coordinate system is normally defined in the catalog +configuration file. If undefined it defaults to J2000. +.le +.ls The Output Coordinate System +The output coordinate system is the coordinate system of the output +catalog produced by the catalog query. Normally the output coordinate +system is defined by the user. If undefined it default to the catalog +coordinate system. Catalog coordinates are transformed from the catalog +coordinate system to the output coordinate system before they are +written to the output file. +.le + +.ih +IMAGE ACCESS COORDINATE SYSTEMS + +Astcat supports several image access coordinate systems and manages the +required transformation between them based on input from the user, and +information in the return image headers and the image survey configuration +file. + +.ls The Input Coordinate System +The input coordinate system specifies the coordinate system of the region +center coordinates used to extract data from an image survey. The input +coordinate system is normally defined by the user. If undefined, the input +coordinate system defaults to the query coordinate system. +.le +.ls The Query Coordinate System +The query coordinate system specifies the coordinate system of the coordinates +used to formulate an image survey query. The query coordinate system is +normally defined in the image survey configuration file. If undefined the +query coordinate system defaults to J2000. Coordinates in the input coordinate +system must be transformed to the query coordinate system in order to formulate +a correct query. +.le +.ls Image Coordinate System +The image coordinate system is the coordinate system stored in the header +of the fits image returned by an image survey query. The image coordinate +system type is specified in the image survey configuration file. The +currently recognized types are "fits", "dss", and "none". The default +image coordinate system type is none. The dss wcs is always in the +J2000 system. The fits headers may be in any supported coordinate systems, +but the most common system is J2000. +.le +.ls the output coordinate system +The output coordinate system is the coordinate system of the final image +stored in the image header in FITS format. The output coordinate system +may be the same as the image coordinate system but encoded differently +as when a dss coordinate system is converted to its fits equivalent, +or different as when an image without a coordinate system is assigned +one by the user. +.le + +.ih +CELESTIAL COORDINATE SYSTEMS + +The astcat package supports the equatorial ("fk4", "fk4-noe", "fk5", "icrs"), +ecliptic, galactic, and supergalactic celestial coordinate systems. In most +cases and unless otherwise noted users can input their coordinates in +any one of these systems as long as they specify the coordinate system +correctly. + +Considerable flexibility is permitted in how the coordinate systems are +specified, e.g. J2000.0, j2000.0, 2000.0, fk5, fk5 J2000, and fk5 2000.0 +all specify the mean place post-IAU 1976 or FK5 system. Missing equinox and +epoch fields assume reasonable defaults. In most cases the +systems of most interest to users are "icrs", "j2000", and "b1950" +which stand for the ICRS J2000.0, FK5 J2000.0 and FK4 B1950.0 celestial +coordinate systems respectively. The full set of options are listed below: + +.ls equinox [epoch] +The equatorial mean place post-IAU 1976 (FK5) system if equinox is a +Julian epoch, e.g. J2000.0 or 2000.0, or the equatorial mean place +pre-IAU 1976 system (FK4) if equinox is a Besselian epoch, e.g. B1950.0 +or 1950.0. Julian equinoxes are prefixed by a J or j, Besselian equinoxes +by a B or b. Equinoxes without the J / j or B / b prefix are treated as +Besselian epochs if they are < 1984.0, Julian epochs if they are >= 1984.0. +Epoch is the epoch of the observation and may be a Julian +epoch, a Besselian epoch, or a Julian date. Julian epochs +are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to the epoch type of +equinox if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. If undefined epoch defaults to equinox. +.le +.ls icrs [equinox] [epoch] +The International Celestial Reference System where equinox is +a Julian or Besselian epoch e.g. J2000.0 or B1980.0. +Equinoxes without the J / j or B / b prefix are treated as Julian epochs. +The default value of equinox is J2000.0. +Epoch is a Besselian epoch, a Julian epoch, or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Julian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. If undefined epoch defaults to equinox. +.le +.ls fk5 [equinox] [epoch] +The equatorial mean place post-IAU 1976 (FK5) system where equinox is +a Julian or Besselian epoch e.g. J2000.0 or B1980.0. +Equinoxes without the J / j or B / b prefix are treated as Julian epochs. +The default value of equinox is J2000.0. +Epoch is a Besselian epoch, a Julian epoch, or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Julian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. If undefined epoch defaults to equinox. +.le +.ls fk4 [equinox] [epoch] +The equatorial mean place pre-IAU 1976 (FK4) system where equinox is a +Besselian or Julian epoch e.g. B1950.0 or J2000.0, +and epoch is the Besselian epoch, the Julian epoch, or the Julian date of the +observation. +Equinoxes without the J / j or B / b prefix are treated +as Besselian epochs. The default value of equinox is B1950.0. Epoch +is a Besselian epoch, a Julian epoch, or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Besselian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. If undefined epoch defaults to equinox. +.le +.ls noefk4 [equinox] [epoch] +The equatorial mean place pre-IAU 1976 (FK4) system but without the E-terms +where equinox is a Besselian or Julian epoch e.g. B1950.0 or J2000.0, +and epoch is the Besselian epoch, the Julian epoch, or the Julian date of the +observation. +Equinoxes without the J / j or B / b prefix are treated +as Besselian epochs. The default value of equinox is B1950.0. +Epoch is a Besselian epoch, a Julian epoch, or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Besselian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian day. If undefined epoch defaults to equinox. +.le +.ls apparent epoch +The equatorial geocentric apparent place post-IAU 1976 system where +epoch is the epoch of observation. +Epoch is a Besselian epoch, a Julian epoch or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Besselian +epochs if the epoch value < 1984.0, Julian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. +.le +.ls ecliptic epoch +The ecliptic coordinate system where epoch is the epoch of observation. +Epoch is a Besselian epoch, a Julian epoch, or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Besselian epochs +if the epoch values < 1984.0, Julian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian day. +.le +.ls galactic [epoch] +The IAU 1958 galactic coordinate system. +Epoch is a Besselian epoch, a Julian epoch or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Besselian +epochs if the epoch value < 1984.0, Julian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. The default value of epoch is B1950.0. +.le +.ls supergalactic [epoch] +The deVaucouleurs supergalactic coordinate system. +Epoch is a Besselian epoch, a Julian epoch or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Besselian +epochs if the epoch value < 1984.0, Julian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. The default value of epoch is B1950.0. +.le + +Fields enclosed in [] are optional with the defaults as described. The epoch +field for the "icrs" , "fk5", "galactic", and "supergalactic" coordinate +systems is only used if the input coordinates are in the equatorial fk4, +noefk4, fk5, or icrs systems and proper motions are used to transform from +coordinate system to another. + +.ih +SEE ALSO +.endhelp diff --git a/noao/astcat/doc/surveys.hlp b/noao/astcat/doc/surveys.hlp new file mode 100644 index 00000000..2c5c4799 --- /dev/null +++ b/noao/astcat/doc/surveys.hlp @@ -0,0 +1,275 @@ +.help surveys Mar00 astcat +.ih +NAME +surveys -- describe the image survey configuration file +.ih +USAGE +help surveys +.ih +IMAGE SURVEYS + +An image survey is a collection of image data for a large region of +the sky from which image data for a small region of the sky can be extracted +by specifying an extraction region. + +Image surveys may be installed locally or accessed remotely. Each +supported survey must have a record in the image survey configuration file +defining the image survey network address, the image survey query format, +and the query output format. The default configuration file supplied with +the package is "astcat$lib/imdb.dat". A list of the supported surveys in the +configuration file can be obtained by running the aslist task. + +.ih +THE IMAGE SURVEY CONFIGURATION FILE + +The image survey configuration file specifies the network address, the query +format, and the output image format for each supported image server. Each +image survey record is accessed via a record name of the form +survey@site, e.g. "dss2@cadc". Adding support for a new image +server or responding to changes in the behavior of an existing image +server requires adding a new record to the configuration file or changing +an existing record. No modification to the code should be required. + +The image server network address tells the image survey access code where +and how to connect to the network. Each network address has the syntax +"domain:port:address:flags" e.g. "inet:80:www.noao.edu:text". + +The query format specifies the form of the query string, and the +names, default values, units, and format of the query parameters. A set of +query parameter names are reserved for accessing image surveys +including "ra", "dec", "width", "hwidth", "xwidth", "ywidth", "xhwidth", +and "yhwidth". The astcat package recognizes the reserved query parameter +names, replaces the default query parameter values with user supplied ones, +and sends the query to the image server. "ra" and "dec" always refer +to the center of the region to be extracted. The size parameter is +input by the user as a width in ra and dec in arcminutes. This value +is translated into a halfwidth or width like parameter +depending on whether the query parameter is defined as "hwidth", "width", +"xwidth", "ywidth", "hxwidth", or "hywidth" etc. + +The server output format specifies the form of the server query results: +including the image type, the world coordinate system type, and the +standard keyword set. At present the only supported image type is FITS, +the supported world coordinate system types are FITS and DSS, +and the standard keyword set includes keywords that are required or +useful for astrometric analysis tasks. + +.ih +SAMPLE IMAGE SURVEY RECORD + +The following example illustrates the main features of a image survey +configuration file record. + +.nf +begin dss1@cadc +address inet:80:cadcwww.hia.nrc.ca:text +query GET /cadcbin/dss-server?ra=%-s&dec=%-s&mime-type=application/x-fits&x=%-s +&y=%-s HTTP/1.0\n\n +nquery 5 + ra 00:00:00.00 hours %0.2h + dec +00:00:00.0 degrees %0.1h + xwidth 10.0 minutes %0.1f + ywidth 10.0 minutes %0.1f + qsystem J2000.0 INDEF %s +type fits +hread 1 +wcs dss +nwcs 10 + wxref INDEF INDEF d pixels + wyref INDEF INDEF d pixels + wxmag INDEF 1.701 d arcsec/pixel + wymag INDEF 1.701 d arcsec/pixel + wxrot INDEF 180.0 d degrees + wyrot INDEF 0.0 d degrees + wraref OBJCTRA INDEF d hms + wdecref OBJCTDEC INDEF d dms + wproj INDEF tan c INDEF + wsystem INDEF J2000 c INDEF +nkeys 13 + observat INDEF Palomar c INDEF + esitelng INDEF +116:51:46.80 d degrees + esitelat INDEF +33:21:21.6 d degrees + esitealt INDEF 1706 r meters + esitetz INDEF 8 r INDEF + emjdobs INDEF INDEF d INDEF + edatamin INDEF INDEF r ADU + edatamax INDEF INDEF r ADU + egain INDEF INDEF r e-/ADU + erdnoise INDEF INDEF r e- + ewavlen INDEF INDEF r angstroms + etemp INDEF INDEF r degrees + epress INDEF INDEF r mbars +.fi + +The beginning of a new image survey record is marked by a line +of the form "begin surveyname" where surveyname is a unique name of the +form survey@site. Any number of unique names can access the same +image survey. Multiple entries for the same survey +can be used to define a different query format or to interpret the +output in different ways. For example if the image server supports a +variety of image formats then the query can be set up to make +use of this facility. + +The \fIaddress\fR, \fIquery\fR and \fInquery\fR keywords are required and +define the network address, query command format, and query parameters for +the image survey. + +The \fIaddress\fR keyword "domain", "port", and "flags" fields are almost +always "inet", "80", and "text" respectively for image surveys, so +the only field that has to be set differently is the address +field :cadcwww.hia.nrc.ca" in this case. + +The \fIquery\fR keyword defines the query command whose form is server +dependent. Note the %-s formatting strings. These strings are replaced +by the query parameter values supplied by the user of the default query +parameter values. + +The number of query parameters is defined by the \fInquery\fR keyword. The +number of query parameters must be greater than or equal to the number of "-%s" +strings in the query keyword value. The name, default value, units, +and format of each query parameter is listed below the nquery keyword and value, +one parameter description per line. Alert users will notice that in the +example above the number of query parameters is 5 but there are only 4 "%-s" +strings in the query keyword value. In this case the qsystem query parameter +which defines the coordinate system of the ra and dec query parameters is +fixed at J2000. For some servers this could be a true query parameter, i.e. +the server may accept coordinates in B1950, J2000, or some other system. + +Users must use the standard query parameter names "ra", "dec", and "qysystem" +to define the extraction region center and its coordinate system, and one or +more of "width", "xwidth", "ywidth", "hwidth", "xhwidth", or "ywidth" to define +the extraction region size. Currently the units of "ra" may be "hours", +"degrees", or "radians", the units of dec may be "degrees" or "radians", +and units of the size query parameter may be "degrees" or "minutes". +The qsystem parameter may be any one of the supported celestial coordinate +systems. The most popular values are "icrs", "J2000", and "B1950". +For more details type "help ccsystems". The formats are used to convert +any numerical values supplied by the user to strings arguments that +can be passed to the query string. + +The \fItype\fR keyword defines the format of the output image file. At +present only fits data is supported. + +The \fIhread\fR keyword is the number of network reads to discard before +the image transfer begins. If undefined the hread keyword defaults to 0. +A related parameter \fIhskip\fR defines the amount of data to be skipped +in bytes. Hskip is not yet supported. + +The \fIwcs\fR parameter defines the wcs status of the image. The options +are "fits" for an image which already has a valid fits wcs, "dss" for an +image which has a dss WCS, and "none" for an image which has no wcs +information. The value of this parameter determines what if any fits wcs +information should be added to the output image headers. + +The \fInwcs\fR keyword defines the number of following wcs parameters. Each +parameter consists of a standard keyword name, the actual keyword name or INDEF +is no keyword exists, the default value or INDEF is there is no default value, +the data type which must be one of d(double), r(real), (i)integer, or +c(character), and the units which may be INDEF if they are undefined. + +Users should use the reserved wcs parameter names \fIwxref\fR, \fIwyref\fR, +\fIwxmag\fR, \fIwymag\fR, \fIwxref\fR, \fIwyref\fR, \fIwraref\fR, +\fIwdecref\fR, \fIwproj\fR, and \fIwsystem\fR to define the wcs parameter +pixel reference coordinates, pixel scale in "/ pixel, coordinate +system rotation and skew in degrees, reference coordinates in some celestial +coordinate system, projection scheme, and celestial coordinate system. At +present the units for all but the wraref and wdecref are fixed. + +The \fInkeys\fR keyword defines the number of following standard keyword +parameters. Each parameter consists of a standard keyword name, the actual +keyword name or INDEF is no keyword exists, the default value or INDEF is +there is no default value, the data type which must be one of d(double), +r(real), (i)integer, or c(character), and the parameter units which may be +INDEF if they are undefined. + +Users should use the reserved standard keyword names \fIobservat\fR, +\fIesitelng\fR, \fIesitelat\fR, \fIesitelat\fR, and \fIesitetz\fR to +define the site, \fIemjdobs\fR, \fIewavelen\fR, \fIetemp\fR, and \fIepress\fR +to define the time and physical conditions of the observation, and +\fIedatamin\fR, \fIedatamax\fR, \fIegain\fR, and \fIerdnoise\fR +to define the detector parameters. At present the units of all these +parameters should be regarded as fixed. The standard keyword set determines +what if any standard keyword and value information should be added to the +image headers. + +.ih +INSTALLING A NEW IMAGE SURVEY RECORD + +Some users may need to install a local version of an image survey , or +support a new image survey as it comes on line. The procedure for doing +this is outlined below. + +To install a new image survey record. + +.ls [1] +Create a new configuration file by making a copy of the old one. +.le + +.ls [2] +Determine a unique name for the image server. This name should be short and +have the form survey@site, e.g. "dss1@cadc". Existing names can be +reviewed with the aslist task. +.le + +.ls [3] +Determine the appropriate values for the address, query and nquery +keywords and enter these quantities in the survey record. +Determine the name, default value, units and format for each query parameter +and enter these quantities in the survey record in the order they are +requested by the query parameter string. Make sure that all the query keyword +value formatting strings are -%s, that the value of the nquery keyword is +greater than or equal to the number of %-s strings in the query keyword +value, and that standard query parameter names are used. +.le + +.ls [4] +Set the value of type to "fits". Note that image servers which do not +produce fits image files cannot be supported at present. +.le + +.ls [5] +Run the adumpim task. Adumpim tests the address and query parts of the +survey record but dumps the query results directly to a file without +modification. If adumpim fails either the network connection is bad +or the address and / or query format is incorrect. +.le + +.ls [6] +Examine the adumpim results with imhdr and imstat. Note that it may be +necessary to add a ".fits" extension to the output file name in order to +make IRAF think it is an image. If imheader or imstat fail it +may be because some leading junk header data got included with the image +data. Determine the size and type of this junk data, set hread or hskip +keywords appropriately, and run adumpim again. +.le + +.ls [7] +Examine the fits image header and determine the type of wcs information if +any in the header. For dss images set wcs to "dss", for images with fits +wcs information already present in the headers set wcs to "fits", for all +remaining images set wcs to "none". +.le + +.ls [8] +Fill in the wcs information using information in the returned image header +or apriori information about the survey, and one of the existing records +as a model. If no information is available set the nwcs keyword to 0. +.le + +.ls [9] +Fill in the standard keyword information using information in the image +header or apriori information about the survey, and one of the existing +records as a model. If no information is available set the nkeys keyword +to 0. +.le + +.ls [11] +Run the agetim task with and without the header editing options enabled +to check the accuracy of the survey record. +.le +.fi + +.ih +SEE ALSO +aslist +.endhelp |