2MASS Image Inventory Program Interface Help

The 2MASS Image Inventory Program Interface allows program friendly access to lists of 2MASS Image sets covering a specific region, position, or target object via the VO SIA protocol. It consists of a single CGI program conforming to the VO SIA specification; accordingly, it returns lists of image sets in VOTable form.

Essentially, SIA defines a set of query parameters (and in some cases allowable values) that can be passed to a service via HTTP GET or POST. The service — in this case http://irsa.ipac.caltech.edu/cgi-bin/2MASS/IM/nph-im_sia — returns an XML table (in VOTable format) of metadata and links for the images satisfying the query parameters.

These images (and their associated artifact locations) can be downloaded programmatically by parsing the output VOTable and issuing HTTP GET requests for the embedded URLs using one of many freely available libraries (for example, C code to do this could use libxml2 and libcurl).

A full description of the SIA and VOTable standards is beyond the scope of this document. Interested readers are encouraged to refer to the official SIA and VOTable specifications. However, a minimal query will typically involve a position or search region (specified using the POS and SIZE parameters) and a 2MASS data set (via the ds parameter). The full set of recognized parameters is listed below, allowing for constraints on date, hemisphere, scan number and image band, as well as other criteria.

Examples

nph-im_sia?FORMAT=METADATA
Returns a VOTable describing service parameters and returned columns
nph-im_sia?POS=-245.0,33.5&SIZE=0.1
Searches for 2MASS All Sky Survey images overlapping a circular region of interest with radius 0.1 deg centered on -245.0 33.5 (J2000). Links to both FITS images and preview pages will be returned.
nph-im_sia?ds=sx&POS=m31&SIZE=0.1&FORMAT=image/fits
Searches for 2MASS 6X Catalog images overlapping a circular region of interest with radius 0.1 deg centered on m31 (short for MESSIER 31), and returning only FITS image links.

Parameters

POS
The position of the region of interest, expressed as the right-ascension and declination of the region center, in decimal degrees using the ICRS coordinate system. A comma should delimit the two values; embedded whitespace is not permitted. As an extension of the standard, object names are also accepted. Names are mapped to search positions via the NED and SIMBAD name resolvers.
SIZE
The angular size of the region given in decimal degrees. Only one value is allowed. A special case is SIZE=0, which is equivalent to searching for all images which cover the given search position. This parameter can be omitted if the INTERSECT parameter is equal to CENTER.
INTERSECT
A parameter that indicates how matched images should intersect the region of interest (ROI). Allowed values are:
COVERS
The candidate image covers or includes the entire ROI.
ENCLOSED
The candidate image is entirely enclosed by the ROI.
CENTER
The candidate image overlaps the center of the ROI.
OVERLAPS (default)
The candidate image overlaps some part of the ROI.
If this parameter is omitted, INTERSECT=OVERLAPS is assumed. Note that the ROI edges (as well as the image boundaries) are approximated using great circles. Coverage computations of the resulting sky-polygons are exact.
FORMAT
Requested format of images. Allowed values are:
ALL (default)
Return URIs for image FITS files and image preview web pages
image/fits
Return URIs for image FITS files
text/html
Return URIs for image preview web pages
METADATA
Return a description of service parameters and returned columns
type
Sets the type of 2MASS image (Atlas or Quicklook) to search for. Atlas Images contain photometric zero point information in their headers and are suitable for quantitative photometric measurements. Quicklook Images are restored from lossy-compressed versions of the Atlas Images and may be used for position measurements, finding charts and visual inspection of the near-infrared sky. Only Atlas Images should be used for quantitative photometric measurements because of the information lost during the Quicklook compression process.
at (default)
Search for Atlas Images
ql
Search for Quicklook Images
ds
The 2MASS data set to search for images in.
asky (default)
2MASS All Sky Release Survey Images
askyw
2MASS Full Survey Images
sx
2MASS 6X Catalog Images
sxw
2MASS Full 6X Images
cal
2MASS Calibration Images
band
Limits 2MASS images returned to those with the given 2MASS Band. If omitted, no restrictions are placed on the 2MASS band of the images returned. Allowed values are:
A (default)
All 2MASS Bands
J
2MASS J-Band
H
2MASS H-Band
K
2MASS Ks-Band
xdate
Limits 2MASS images to those with the given reference date, specified in yymmdd format (yy: last 2 digits of the observation year, mm: integer month, dd: integer day). This can differ by one day from the actual UT observation date. If omitted, no restrictions are placed on the reference date of the images returned.

Note: date is frequently a database manager reserved word, so the column name xdate is used instead.

hem
The hemisphere of the 2MASS observatory where the FITS images to return were taken. There are only two possible values:
n
north (Mt. Hopkins)
s
south (Cerro Tololo)
If omitted, no restrictions are placed on the observatory hemisphere of the images returned.
scan
The nightly scan number (a positive integer) of the FITS images to return. If omitted, no restrictions are placed on the nightly scan number of the images returned.

Output table columns

Column nameUCDColumn description
nameVOX:Image_TitleConcise description of the image returned.
downloadVOX:Image_AccessReferenceImage access reference URL.
center_raPOS_EQ_RA_MAINICRS right-ascension of the image center.
center_decPOS_EQ_DEC_MAINICRS declination of the image center.
naxesVOX:Image_NaxesNumber of Image Axes.
naxisVOX:Image_NaxisAn array giving the length in pixels of each image axis.
scaleVOX:Image_ScaleAn array giving the scale in degrees per pixel of each image axis.
formatVOX:Image_FormatMIME-type of the object pointed to by the image access reference URL.
crpixVOX:WCS_CoordRefPixelAn array specifying the image pixel coordinates of the WCS reference pixel.
crvalVOX:WCS_CoordRefValueAn array specifying the world coordinates of the WCS reference pixel.
crota2VOX:BandPass_IDTwist in degrees about Image Center, +AXIS2 West of North (J2000)
band2MASS Image Band
brefVOX:BandPass_RefValueThe reference wavelength of the 2MASS Image Filter (meters).
bhiVOX:BandPass_HiLimitUpper wavelength limit of the 2MASS Image Filter (meters).
bloVOX:BandPass_LoLimitLower wavelength limit of the 2MASS Image Filter (meters).
pers_artURL for a VOTable of persistence artifacts potentially affecting the image
glint_artURL for a VOTable of filter glint artifacts potentially affecting the image
typeType of Image (Q=Quicklook; A=Atlas)
datasetThe 2MASS dataset the image belongs to, one of: 'asky' (All-Sky Release Survey), 'askyw' (Full Survey), 'sx' (6X Catalog), 'sxw' (Full 6X), 'cal' (Calibration)
pixflagsVOX:Image_PixFlagsPixel flags of source image
idReserved
scntrReserved
xdateThe reference date of the FITS image, in yymmdd format (yy: last 2 digits of the observation year, mm: integer month, dd: integer day). This can differ by one day from the actual UT observation date.
hemThe hemisphere of the 2MASS observatory where the FITS image was taken. There are only two possible values: 'n' = north (Mt. Hopkins), and 's' = south (Cerro Tololo).
scanThe nightly scan number of the FITS image.
imageThe image number of the FITS image.
ut_dateUT when the FITS image was taken, in yymmdd format (yy: last 2 digits of the observation year, mm: integer month, dd: integer day). This can differ by one day from the actual UT observation date.
coadd_keyThe coadd_key value of the FITS image. This is a unique identifier for the observation date, observatory hemisphere, nightly scan number, and image number of the FITS image. Each source in the 2MASS All-Sky Point and Extended Source Catalogs is tagged with a coadd_key value identifying the 2MASS Image Set it was extracted from.
seeshSeeing Full Width Half Maximum (in arcseconds)
magzpPhotometric zero-point magnitude of the FITS image.
msnr10Approximate SNR=10 magnitude of the FITS image.
binThe ID of the HTM triangle (subdivision level 7) containing the FITS image reference location.

References