diff options
Diffstat (limited to 'noao/astcat/doc/agetim.hlp')
| -rw-r--r-- | noao/astcat/doc/agetim.hlp | 242 |
1 files changed, 242 insertions, 0 deletions
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 |