path: root/noao/astcat/doc/surveys.hlp

.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