idlastro / Web Socket Procedures: QUERYDSS

[Source code]

NAME
QueryDSS
PURPOSE
Query the digital sky survey (DSS) on-line at  the STSCI (or ESO) server
EXPLANATION
The script can query the DSS survey and retrieve an image and FITS 
header either from the the Space Telescope Science Institute (STScI) or 
European Space Observatory (ESO) servers.
See http://archive.eso.org/dss/dss and/or 
http://archive.stsci.edu/dss/index.html for details.
CALLING SEQUENCE
QueryDSS, targetname_or_coords, Im, Hdr, [IMSIZE= , /ESO, Outfile= ]
INPUTS
TARGETNAME_OR_COORDS - Either a scalar string giving a target name, 
    (with J2000 coordinates determined by SIMBAD (default) or NED), or 
    a 2-element numeric vector giving the J2000 right ascension in 
    *degrees* and the target declination in degrees.
OPTIONAL INPUTS
None
OPTIONAL KEYWORD PARAMETERS
ImSize - Numeric scalar giving size of the image to be retrieved in 
            arcminutes.    Default is 10 arcminute.
/ESO - Use the ESO server for image retrieval.    Default is to use
       the STScI server 
/NED - Query the Nasa Extragalactic Database (NED) for the
       target's coordinates.  The default is to use Simbad for
       the target search.
OUTFILE  - scalar string specifying name of output FITS file.    
       If set, then the output IDL variables are not used.
/STSCI - obsolete keyword, now does nothing, since STSCI is the default
         Server.     
SURVEY - Scalar string specifying which survey to retrieve.  
     Possible values are 
     '1' - First generation (red), this is the default
     '1b' - First generation (blue)
     '2b' - Second generation blue
     '2r' - Second generation red
     '2i' - Second generation near-infrared
TIMEOUT - numeric scalar giving the time in seconds to wait for a server
        response.   Default is 20 seconds
 Note that 2nd generation images may not be available for all regions
 of the sky.   Also note that the first two letters of the 'REGION'
 keyword in the FITS header gives the bandpass 'XP' - Red IIIaF, 
 'XJ' - Blue IIIaJ, 'XF' - Near-IR IVN
 /VERBOSE - If set, then the query sent to the DSS server is displayed
OUTPUTS
Im - The image returned by the server. If there is an error, this 
      contains a single 0.
Hdr - The FITS header of the image. Empty string in case of errors.
      This header will contain a "best" tangent approximation to the 
      Guide Star astrometry as the default.     However, the original 
      Guide Star astrometry keywords with up to 20 parameters will also 
      be present.
If the OutFile keyword is set then no outputs are returned (only the
file is written).
SIDE EFFECTS
If Im and Hdr exist in advance,  they are overwritten.     A temporary file
may be written.
RESTRICTIONS
Relies on a working network connection. 
PROCEDURE
Construct a query-url,  fetch file with IDLNetURL object, and optionally 
read the file into IDL variables.
EXAMPLE
Retrieve an 10'  image surrounding the ultracompact HII region
 G45.45+0.06.   Obtain the 2nd generation blue image.
 IDL> QueryDSS, 'GAL045.45+00.06', image, header, survey = '2b'
 IDL> tvscl, image
 IDL> hprint, header
 IDL> writefits,'dss_image.fits', image, header
Note that the coordinates could have been specified directly, rather than
giving the target name.
IDL> QueryDSS, [288.587, 11.1510], image, header,survey='2b'
To write a file directly to disk, use the OutFile keyword
IDL> QueryDSS, [288.587, 11.1510], survey='2b', out='gal045_2b.fits'
PROCEDURES CALLED
QUERYSIMBAD
MODIFICATION HISTORY
Written by M. Feldt, Heidelberg, Oct 2001 
Option to supply target name instead of coords  W. Landsman Aug. 2002
Added OUTFILE, /NED keywords W. Landsman   April 2003
Don't abort on Simbad failure W. Landsman/J. Brauher  June 2003
Added /VERBOSE keyword W. Landsman   Jan 2009
Make /STScI server the default  W. Landsman June 2010
Fix OUTPUT option  W. Landsman June 2010
Major rewrite to use IDLNetURL object W. Landsman September 2016