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