.help getimg Mar12 votools
.ih
NAME
getimg -- Query image data services in the VO
.ih
USAGE
getimg resource fields
.ih
PARAMETERS
.ls resource
List of the VO data services to query.  
.le
.ls fields
List of objects or images used to specify the position of the query.  An
object name will be resolved to a position using the \fISESAME\fR service
and the \fIsize\fR parameter will determine the query size.  If an image
name is given, the center position and image corners will be used to
determine the query position and size.
.le
.ls pos = ""
A string specifying the position of the query.  Positions are specified as
J2000 RA and Dec in decimal degrees separate by a comma.
.le
.ls size = 0.25
Query size in decimal degrees.
.le
.ls samp = no
If enabled, each result table is broadcast as a SAMP message to other 
VO applications.
.le
.ls plot = no
Plot the result table to the standard graphics stream?  
The \fIplot\fR parameter is ignored when using multiple resources or fields.
.le
.ls display = no
If enabled, an image of the \fIfield\fR will be displayed.  If the
\fIfield\fR is an object name, a DSS image of the field will be displayed,
if the \fIfield\fR is an image then the image will be displayed.  The
\fIdisplay\fR parameter is ignored when using multiple resources or fields.
.le
.ls overplot = no
If enabled, the objects in the result table will be overlayed on the
image display.  The \fIoverplot\fR parameter is ignored when using multiple
resources or fields.
.le
.ls output = "STDOUT"
Output filename.  If the \fIoutput\fR parameter is "STDOUT" the result table
will be written to the standard output stream.  If the output name is a 
null string, no result table will be printed or saved.
.le
.ls format = "ascii"
Format of the result table.  Allowed values are
.ls vot | xml
A new VOTable.
.le
.ls asv
Ascii separated values.
.le
.ls bsv
Bar separated values.
.le
.ls csv
Comma separated values.
.le
.ls tsv
Tab separated values.
.le
.ls html
Standalone HTML document.
.le
.ls shtml
Single HTML <table> element.  This format may be used to generate the <table>
code for inclusion in another HTML document.
.le
.ls fits
FITS binary table
.le
.le
.ls status = 0
Return status code.  A non-zero value indicates an error in the query.
.le

.ih
DESCRIPTION
The \fIGETIMG\fR task is used to retrieve data from one or more VO 
image services.  An individual \fIresource\fR name may be 
specified as a user-defined alias, a VO \fIShortName\fR, a VO \fIivorn\fR
identifier string, or as a base service URL.  If specified as a service URL, 
additional parameters to specify the position and size will be determined
from the \fIfields\fR, \fIpos\fR and \fIsize\fR parameters.  Multiple 
resources may be specified as a comma-delimited string or as an \fI@file\fR.

The position to be queried may be specified by the \fIfields\fR parameter
as either a list of object names that are resolved to equatorial coordinates
automatically, or as a list of images where the WCS footprint of the image is
used to determine the center and size.  For object names, the \fIsize\fR
parameter is specified in decimal degrees as the radius around the position
to query.  The \fIpos\fR parameter may be specified as a comma-separated
set of RA/Dec values given in decimal degrees.

Result tables may be broadcast to other VO applications using SAMP messaging
by enabling the \fIsamp\fR parameter.  If the \fIdisplay\fR parameter is
enabled then images used as input will be displayed, if object names are
used a DSS image of the field will be displayed.  The \fIoverplot\fR parameter
may be set to overlay the result catalog on the image display automatically.
The \fIdisplay\fR and \fIoverplot\fR parameters are only used for 
single-resource and single-object queries.

Results may be saved to disk in a format specified by the \fIformat\fR 
parameter (described above).  If the \fIoutput\fR parameter is the null
string then no local results will be saved or printed, the value "STDOUT"
may be used to print the result table to the standard output stream (except
in the case of FITS bintable output).

.ih
EXAMPLES
1. Find the HST GOODS images within 0.1 degrees of 3c273.  Display
the field and overlay the central image positions on the image display, 
do not print the results.  Then do the same, but plot the results instead
of overlaying the display, append the GSC2.3 catalog.

.nf
  votools> getimg hst.goods 3c273 size=0.1 display+ overplot+ output=""
  votools> getimg hst.goods 3c273 size=0.1 plot+ output=""
  votools> getimg gsc2.3 3c273 size=0.1 plot+ overplot+ output=""
.fi

2. Find the NVSS (all-sky 21-cm radio survey) images for each extension of a
NEWFIRM mosaic image, save the raw VOTable results:

.nf
  votools> getimg nvss @newfirm.fits format="raw" output="nf"
.fi


.ih
REVISIONS
.le
.ih
SEE ALSO
getcat, vodata
.endhelp