| agetim | astcat | agetim |
agetim -- extract fits images from image surveys
agetim regions output
Agetim extracts fits images from local or remote image surveys imsurveys using a list of region definitions supplied by the user regions and writes the results of each image survey query to the output images output .
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 regions = "pars" these quantities are read from the aregpars parameters rcra , rcdec , rcrawidth , rcdecwidth rcraunits , rcdecunits ., and rcsystem . If regions is an input image list they are read from the FITS world coordinate system in the image header. If regions is a file name they are read from file whose format is the following.
# Optional comment ra1 dec1 xwidth1 ywidth1 [raunits1 [decunits1 [system1]]] ra2 dec2 xwidth2 ywidth2 [raunits2 [decunits2 [system2]]] ... .... ....... ....... [........ [......... [.......]]] raN decN xwidthN ywidthN [raunitsN [decunitsN [systemN]]]
Quantities in square brackets are optional. If system is undefined the coordinate system defaults to the query coordinate system, i.e. if the catalog query expects coordinates in J2000.0 then ra and dec will be interpreted as though they were in the J2000.0 system. If undefined the ra and dec units default to the preferred units of the coordinate system, i.e. hours and degrees for equatorial coordinate systems, and degrees and degrees for ecliptic, galactic, and supergalactic coordinate systems.
A sample regions file is shown below. If the 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.
# List of targets 13:29:53.27 +47:11:48.4 10.0 10.0 13:29:53.27 +47:11:48.4 10.0 10.0 hours degrees 13:29:53.27 +47:11:48.4 10.0 10.0 hours degrees J2000.0 13:27:46.90 +47:27:16.0 10.0 10.0 hours degrees B1950.0
For each specified image survey in imsurvey 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 imdb , 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 wcsedit = 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 wxref , wyref , wraref , wdecref , wraunits , wdecunits , and wsystem , and the scale, orientation, and projection information wxmag , wymag , wxrot , wyrot , and wproj . For more information on how these quantities are defined in the image surveys configuration file type "help imsurveys".
If hdredit = 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: edatamin , edatamax , egain , and erdnoise , and those required for transforming mean place coordinates to observed plate coordinates as may be required to compute very accurate image scales, observat , \Iesitelng, esitelat , esitealt , esitetz , emjdobs , ewavlen , etemp , and epress . 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 update = yes the values of the aregpars parameters will be updated at task termination. If verbose = yes then detailed status reports are issued as the task executes.
1. Extract data from the default image survey using the default region definition, display the resulting image, and examine its header.
cl> agetim pars default cl> display reg001.1.fits 1 fi+ cl> imheader reg001.1.fits lo+ | page
2. Repeat the previous example but convert the DSS WCS to a FITS WCS. The DSS WCS is unaltered.
cl> agetim pars default wcsedit+ cl> display reg001.2.fits 1 fi+ cl> imheader reg001.2.fits
3. Repeat example 2 but extract data for two surveys.
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
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.
cl> agetim pars default wcsedit+ hdredit+ cl> display reg001.4.fits 1 fi+ cl> imheader reg001.4.fits
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.
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
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.
cl> page imlist dev$pix dev$ypix cl> agetim @imlist default
If output file is not a fits file, as may be the case if an error occurred in the network transfer, and heasder 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.
