.\" @(#)voatlas.1 1.0 Feb-2013 MJF
.TH VOATLAS 1 "Feb 2013" "VOClient Package"
.SH NAME
voatlas \- Query the SkyView Image service for an all-sky image

.SH SYNOPSIS
\fBvoatlas\fP [<opts>] [<field> | <pos>]

.SH OPTIONS
The \fIvoatlas\fP application accepts the following options:
.TP 6
.B \-h, --help
Print a help summary to the terminal and exit.  No processing is done 
following this flag.

.TP 6
.B \-b \fIBPASS\fP,--band \fIBPASS\fP
Bandpass of image to retrieve.  Allowed values are 'optical', 'infrared' (or
'ir'), 'x-ray', 'euv', 'gamma-ray', or 'radio'.  A minimal match to the 
bandpass name is used.
.TP 6
.B \-p,--survey \fISURVEY\fP
Survey program name.  The list of available surveys is described at
\fIhttp://skyview.gsfc.nasa.gov/cgi-bin/survey.pl\fP.
.TP 6
.B \-g,--graphic
Get a graphic image (i.e. a JPEG), the default is to get a FITS image.
.TP 6
.B \-n,--naxis \fINPIX\fP
Set returned image size.  The default image size returned is 512x512.

.TP 6
.B \-s,--size \fISIZE\fP
Field size to generate.  The SIZE value may be appended with an 's',
'm' or 'd' to specify the size in arcseconds, arcminutes or degrees
(default) respectively.  The default size is 0.25 degrees.
.TP 6
.B \-F,--field \fIFIELD\fP      
Name of the field (e.g. an object name like 'M33') to query.  The object
name must be resolvable with a task like VOSESAME, the position returned
will be the center of the query.
.TP 6
.B \-R \fIRA\fP,--ra \fIRA\fP
The RA position of the query.
.TP 6
.B \-D \fIDEC\fP,--dec \fIDEC\fP
The Dec position of the query.
.TP 6
.B \-P \fIRA,DEC\fP,--pos \fIRA,DEC\fP
Specify the query position as a comma-delimited string of RA and DEC.
.TP 6
.B \-S,--samp
Broadcast resulting image as a SAMP message.  The image will be broadcast
using the 'image.load.fits' mtype.
.TP 6
.B \-v,--verbose
Print verbose output during execution.
.TP 6
.B \-o \fINAME\fP, --output \fIoutput\fP
Specify the filename of the downloaded image.  If not specified a name
created from the field name or position will be used.

.SH DESCRIPTION
The \fIvoatlas\fP task queries the NASA SkyView all-sky survey data for 
an image of the requested sky position in the requested bandpass.  The
position may be given as the name of an object who's coordinate can be
resolved, or as an explicit position in RA and Dec (ICRS decimal degrees).
The default field of view will be 0.25 degrees but may be changed using
the \fI-s\fP option (with an optional 's', 'm' or 'd' on the value to
specify arcseconds, arcminutes or degrees respectively).  The default
image will be in FITS format unless the \fI-g\fP option is set to request
a graphic such as a JPEG, the default size will be 512x512 pixels unless the
\fI-n\fP option is used to set a different size (the image will always
be square so only one value is required).  The resulting image may be
broadcast using the SAMP 'image.load.FITS' mtype by setting the \fI-S\fP 
option. 
.PP
The \fI-b\fP flag is used to select the desired bandpass, if not set then
and optical image from the DSS2B survey is used by default.  Allowed values
for the bandpass string and their corresponding survey names are:

.in 9
\fIBandpass	    ShortName	Title\fP
.in 9
optical	    DSS		Digital Sky Survey
.in 9
infrared	    2MASSK	Two-micron All Sky Survey (K-band)
.in 9
x-ray	    PSPC2INT	ROSAT PSPC (2-deg cutoff)
.in 9
euv		    EUV83		EUV Explorer83A
.in 9
gamma-ray	    EGRET1000	Energetic Gamma-Ray Event Telescope: Hard
.in 9
radio	    4850MHZ	4850 MHz Survey - GB6/PMN

.in 7
If the \fI-p\fP option is used to specify a particular survey program, the
bandpass parameter is ignored.  The \fI-p\fP flag reserves the name 'list'
as a means to have the task return a list of available data for the field.
This list contains the survey name and the mime-type of the available image.
Script tasks can use this information to determine the best available 
image for the field.
.PP
If no input file is specified the VOTable will be read from the stdin,
results will be written to stdout unless the \fI\-o\fP (or \fI\--output\fP)
names an output file.  The task will only process a single VOTable and may
not be used to convert multiple files in a single call.

.SH RETURN STATUS
On exit the \fBvoatlas\fP task will return a zero indicating success, or a
one indicating an error.

.SH EXAMPLES
.TP 4
1)  Display an image of M83 on Aladin using SAMP

.nf
  % voatlas -S m83     or     % voatlas --samp m83
.fi
.TP 4
2)  Get a 256x256 JPEG image of the Sombrero galaxy

.nf
  % voatlas -o gal.jpg -n 256 --graphic sombrero
.fi
.TP 4
3)  Get a 20 arcmin Wise 2.2micron survey image of m101

.nf
  % voatlas -s 20m --survey=wise22 m101
.fi
.TP 4
4)  Get a radio image of 3c273, image will be '3c273.fits'

  % voatlas --band=radio 3c273
.fi
.TP 4
5)  List (verbose) the survey images available for ngc1234

.nf
  % voatlas --survey=list -v ngc1234
.fi
.SH BUGS
1) There is currently no convenient way to get a list of surveys without
specifying a position, this is due to the way Skyview is implemented.

2) There is currently no convenient way to select other than the first
available image.
.SH Revision History
Feb 2013 - First public release
.SH Author
Michael Fitzpatrick (fitz@noao.edu), Feb 2013
.SH "SEE ALSO"
vodata, vocatalog, voimage, vospectra