From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 noao/astcat/doc/surveys.hlp | 275 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 275 insertions(+)
 create mode 100644 noao/astcat/doc/surveys.hlp

(limited to 'noao/astcat/doc/surveys.hlp')

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
-- 
cgit 

