2MASS Batch Image Service Help

The 2MASS Batch Image Service is designed to allow retrieval of large sets of 2MASS Images. The service can retrieve both Atlas and Quicklook images - each "Quicklook" image corresponds to a 2MASS Atlas Image that has been lossy-compressed with hcompress, using scale = 4.0 and quant = 1.0 parameters. The Quicklook Images delivered by this service are restored from the lossy-compressed files in FITS format with full WCS information contained in the image headers. These images are suitable for position measurements, finding charts and visual inspection of the near-infrared sky.

There are five image retrieval modes provided by the Batch Service:

  1. Retrieve Images which overlap or cover or are enclosed by a Region
  2. Retrieve Images for a List of Positions
  3. Retrieve Images for a List of coadd_key values
  4. Retrieve Images for a Date, Hemisphere, and Scan
  5. Retrieve Images for a List of Date Hemisphere Scans

Each mode is described in more detail below.

The query inputs common to all of the retrieval modes are described in the Common Inputs section.

Help for creating table files, required as an input for several retrieval modes, is available here.

Finally, for a description of the image-meta data tables produced by this service, please visit the 2MASS Image Meta-Data Table Help webpage.

Each query is limited to retrieving a maximum of 1GB in image files. If this limit is exceeded, retrieved images are archived and returned to the user. An image-meta data table corresponding to those images which were found to satisfy the search criteria, but which were not retrieved is also created. The result page for the Batch Image Service query will contain a link allowing the user to submit this list of "unretrieved" images back to the Batch Image Service. This allows users to retrieve more than 1GB of images without having to manually split a query into manageable pieces.

Common Inputs

These are the inputs which are common to all of the batch image retrieval modes :

E-mail address

Because large numbers of images can be retrieved with the 2MASS Batch Image Service, queries typically don't run at interactive speeds. For this reason, a message is sent to the specified e-mail address when a query completes.

Image band(s) to retrieve

This input allows you to choose the 2MASS band(s) for which images are to be retrieved.

  • J: Selecting this option will cause only J-band images to be retrieved.
  • H: Selecting this option will cause only H-band images to be retrieved.
  • Ks: Selecting this option will cause only Ks-band images to be retrieved.
  • All: Selecting this option will cause images for all three bands to be retrieved.
Decompress Quicklook images

When this option is checked, Quicklook Images are decompressed with hcompress prior to retrieval. If unchecked, they are left in compressed form unless an operation requiring decompression (such as image subsetting) is requested. Note that 2MASS Quicklook Images take up approximately twenty times less disk space when compressed, so this option can result in significantly smaller downloads and faster query run times. To download the hcompress software for your platform, please visit the Hcompress Image Compression Software website.

CAUTION:

Always use 2MASS Atlas Images for photometric measurements -
2MASS Quicklook Images are restored from lossy-compressed files.

Retrieve Images overlapping or covering or enclosed by a Region

Description

This mode retrieves all the 2MASS Images which overlap or cover or are enclosed by the region with the specified center and diameter.

  • A 2MASS Image set overlaps the search region when a point P on the sky exists such that P is contained in both the image set and search region.
  • A 2MASS Image set covers the search region if it contains every point in the search region.
  • A 2MASS Image set is enclosed by the search region if every point in the image set is contained in the search region.
Query Inputs
Region Center (Coordinates or Object Name)

This input field must contain either a sky coordinate or an object name resolvable via IRSA, NED, or SIMBAD (2MASS object names are resolved by IRSA, all other names are resolved via NED/ SIMBAD). This coordinate or object name defines the center of the region for which 2MASS Image sets are to be retrieved.

If the input field contains a string which can be interpreted as a coordinate representation, it is used as such: both decimal degree and sexagesimal notations are supported. If not, the string is sent first to IRSA, then to NED, and finally to SIMBAD to attempt name resolution. The range of acceptable name formats is set by those projects.

Examples :

  • NGC 7479
  • 2MASXJ23045666+1219223
  • 23h04m56.63s 12d19m22.7s Equ J2000
  • m83
  • 17h 44m 34s -27d 59m 13s Equatorial J2000
  • 17h44m34s -27d59m13s
  • 00h42m44.3s +41d16m08s b1950
  • 00:42:44.3 -41:16:08
  • 00 42 44.3 -41 16 08 b1983
  • 004244.3 -411608
  • 17h -27d Equ J2000
  • 17h -27d
  • 34.5565 54.2321 gal
  • 34. 54. ecl
Region Diameter

This input field must be set to the diameter (in degrees) of the region for which 2MASS Image sets are to be retrieved.

The minimum allowed diameter is 0.05 degrees, and the maximum is 7.0 degrees. Values which do not fall into this range will automatically be clamped to lie in [0.05, 7.0].

CAUTION:

Always use 2MASS Atlas Images for photometric measurements -
2MASS Quicklook Images are restored from lossy-compressed files.

Retrieve Images for a List of Positions

Description

This mode retrieves 2MASS Image sets for each position in a given list. Each 2MASS Image set can optionally be subsetted according to the position it was retrieved for.

Query Inputs
Position list (ASCII table file)

This input must be set to the name of a table file local to the user. The table must be formatted according to the table file formatting rules. Furthermore, the table is assumed to contain column(s) corresponding to a search position, typically ra and dec. Acceptable values can be decimal degrees, sexagesimal, or even object names. See the table formatting documentation for details. Finally, note that tables can be submitted to the IRSA Table Reformat and Validation Service for validity checking prior to use in actual queries.

Three other columns, size, best, and id can optionally appear in the table. If present, size must contain a subimage size (in arcseconds) for each position in the table. If the value of size is non-null and positive, then the images returned for the corresponding position will be cropped to the desired width/height. If the value is empty, null, or zero, no cropping will occur.

If present, the best column must contain a boolean flag for each position indicating whether or not to retrieve only the "best" image for that position. A value of 'n' or 'N' indicates that all images covering the position should be retrieved, whereas 'y' or 'Y' will limit retrieval to the "best" image. If the column is not present, or a column value is null or empty, then behaviour is determined by the best query input.

If present, the id column should contain an identifier for each position in the table (positions are also uniquely identified by their table row numbers). This identifier, which may be at most 15 characters long, is stored in the id column of the image meta-data tables returned by the Batch Image Service, allowing each image to be associated with the position it was found/retrieved for.

Any other columns in the table are ignored by the 2MASS Batch Image Service.

The table must consist of no more than 2500 positions (rows). Note that if a 2MASS Image set covers more than one position in the table, a separate copy of the image is returned for each position. If in addition a size column is present, different subimages of the same underlying 2MASS Image set are returned.

Best Image Only

This input changes how 2MASS Image sets are retrieved for a position. When this option is checked, the 2MASS Image Service will return a single "best" image set for each search position in the input table. If the option is unchecked then all the image sets covering each search position will be returned.

Note that if the position table contains a column named best, then the value of this input is ignored for positions with a non-null and non-empty best column value.

The "best" image set out of the set of all 2MASS Image sets I1, I2, ... , In containing position P is selected as follows:

  1. For each image set Ij, 1 ≤ j ≤ n, the minimum distance dj between P and the 4 edges of Ij is computed.
  2. The image set Ik with the largest minimum distance (dk ≥ dj for 1 ≤ j ≤ n) is selected.

The "best" image set for P is therefore the most centered image set relative to P.

Example Position Tables

Uploading the following table :

|        ra|       dec|best|
|    double|    double|char|
|       deg|       deg|    |
|      null|      null|null|
  65.497627  19.535070    n

will return all the FITS images covering the given position, without subsetting them. Uploading this table : 

|       dec|        ra|best|
|    double|    double|char|
|       deg|       deg|    |
|      null|      null|null|
  19.535070  65.497627    y

will return only the "best" FITS image for that same position. Finally, uploading the next table will cause the returned FITS image to be cropped to a width of 50 arc seconds: 

|        ra|best|       dec|size|
  65.497627    y  19.535070   50

Here is one last example of a valid position table (partial output of a Gator query) : 

|        ra|       dec|   j_m|   h_m|   k_m|ph_qual|
|    double|    double|double|double|double|   char|
|       deg|       deg|   mag|   mag|   mag|       |
|      null|      null|  null|  null|  null|   null|
 218.793021 -29.988167 15.269 14.775 14.721 AAA
 218.889627 -23.928709 16.954 16.095 15.967 DDD
 219.026042 -25.927643 16.413 15.764 15.750 BCD

CAUTION:

Always use 2MASS Atlas Images for photometric measurements -
2MASS Quicklook Images are restored from lossy-compressed files.

Retrieve Images for a List of coadd_key values

Description

This mode retrieves 2MASS Image sets for each coadd_key value in a list.

Query Inputs
coadd_key list (ASCII table file)

This input must be set to the name of a table file local to the user. The table must be formatted according to the table file formatting rules. Furthermore, a column named coadd_key must appear in the table. This column must contain the integer coadd_key values of the images to retrieve.

Two other columns, band and id, may optionally be specified. If present, band must contain the band(s) of the 2MASS Image set to retrieve for a given coadd_key. Allowed values are :

  • 'j' or 'J': retrieve J-band image only
  • 'h' or 'H': retrieve H-band image only
  • 'k' or 'K': retrieve Ks-band image only
  • 'a' or 'A': retrieve images for all three 2MASS bands

If the band column is not present, the global input band determines which bands to retrieve.

If present, the id column should contain an identifier for each coadd_key in the table (which are also uniquely identified by their table row numbers). This identifier, which may be at most 15 characters long, is stored in the id column of the image meta-data tables returned by the Batch Image Service, allowing each image to be associated with the coadd_key it was retrieved for.

Any other columns in the table are ignored by the 2MASS Batch Image Service.

The table must consist of no more than 2500 2MASS Image sets. Since a 2MASS Image set is uniquely identified by a coadd_key, this means that the table can contain a maximum of 2500 rows.

If multiple rows (coadd_keys) reference the same 2MASS Image, redundant rows are discarded. This ensures that a 2MASS Image is never retrieved more than once per query.

Example coadd_key Tables

Uploading the following table :

|coadd_key|band|
|int      |char|
   1590591    J
   1590591    H
   1590591    K

will return 3 FITS images - the J, H, and Ks bands of the image set with a coadd_key value of 1590591.

The following table more succintly references the same images :

|coadd_key|band|
   1590591    A

Here is one more example of a valid coadd_key table :

|id  |coadd_key|band|my_column|
|char|int      |char|    char |
    1   1590591    A  these
   59   1230312    a    are my
    3   1590590    j    column
  200    699387    K    values

CAUTION:

Always use 2MASS Atlas Images for photometric measurements -
2MASS Quicklook Images are restored from lossy-compressed files.

Retrieve Images for a Date, Hemisphere, and Scan

Description

This mode retrieves all the 2MASS Image sets with the given observation date, observatory hemisphere, and nightly scan number.

Query Inputs
Date

The observation date of the image sets to retrieve. The date format used is strict: you must specify exactly 6 numeric characters corresponding to a date in yymmdd format (yy: last 2 digits of the observation year, mm: integer month, dd: integer day).

Examples :

  • August 4, 1997 : 970804
  • August 4, 2000 : 000804
  • August 4, 2001 : 010804
  • January 4, 2001 : 010104
  • February 4, 2001 : 010204
  • February 5, 2001 : 010205

Although the 2MASS Image Service verifies the date format before it attempts to retrieve images, the service will not check to see if there were any 2MASS observations on the specified date. If you enter a date on which no data was taken the service will simply notify you that it was unable to find any image sets matching your retrieval criteria.

Hemisphere

The hemisphere of the 2MASS observatory where the desired image sets were taken. There are only two possible values: north (Mt. Hopkins), and south (Cerro Tololo).

Scan

The nightly scan number of the image sets to retrieve. The value must be an integer between 1 and 999 (inclusive).

CAUTION:

Always use 2MASS Atlas Images for photometric measurements -
2MASS Quicklook Images are restored from lossy-compressed files.

Retrieve Images for a List of Date Hemisphere Scans

Description

This mode retrieves 2MASS Image sets for each observation date, observatory hemisphere, and nightly scan number in a given list.

Query Inputs
DHS List (ASCII table file)

This input must be set to the name of a table file local to the user. The table must be formatted according to the table file formatting rules. Furthermore, three columns named xdate, hem, and scan must appear in the table. Taken together, date, hem, and scan (DHS) must contain the the observation dates (in yymmdd format), observatory hemispheres ('n' or 'N' = north, 's' or 'S' = south), and nightly scan numbers for the images to retrieve.

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

Three other columns, band, image, and id, may optionally be specified. If present, band must contain the band(s) of the 2MASS Image set(s) to retrieve for a given DHS. Allowed values are:

  • 'j' or 'J': retrieve J-band image only
  • 'h' or 'H': retrieve H-band image only
  • 'k' or 'K': retrieve Ks-band image only
  • 'a' or 'A': retrieve images for all three 2MASS bands

If the band column is not present, the global input band determines which bands to retrieve.

The image column (if it appears in the DHS table), must contain image numbers for specific 2MASS Image sets. However, if a column value contains a null, empty, negative or zero value then all image sets for the corresponding DHS will be retrieved (i.e. the image number constraint is ignored).

If present, the id column should contain an identifier for each DHS in the table (which are also uniquely identified by their table row numbers). This identifier, which may be at most 15 characters long, is stored in the id column of the image meta-data tables returned by the Batch Image Service, allowing each image to be associated with the DHS it was found/retrieved for.

Any other columns in the table are ignored by the 2MASS Batch Image Service.

The table must consist of no more than 2500 2MASS Image sets. A 2MASS Image set is uniquely identified by xdate, hem, scan, and image number. Rows which do not have an image column value, or which have a null, empty, negative or zero image column value count as 23 2MASS Image sets. All other rows count as 1 2MASS Image set.

If multiple rows reference the same 2MASS Image, redundant rows are discarded. This ensures that a 2MASS Image is never retrieved more than once per query.

Example DHS Tables

Uploading the following table :

|xdate |hem |scan|image|band|
|char  |char|int |int  |char|
 971031    n   96   197    J
 971031    n   96   197    H
 971031    n   96   197    K
 981121    n   69   256    j
 981121    n   69   256    h
 981121    n   69   256    k

will return 6 FITS images - the three bands of image set 197 of scan 96 (northern observatory hemisphere, October 31, 1997), and the three bands of image set 256 of scan 69 (northern observatory hemisphere, November 21, 1998).

The following table more succintly references the same images :

|xdate |hem |scan|image|band|
|char  |char|int |int  |char|
 971031    n   96   197    A
 981121    n   69   256    a

This table :

|xdate |hem |scan|image|band|
 971031    n   96          A

references all images of scan 96 (northern observatory hemisphere, October 31, 1997), as does this table : 

|xdate |hem |scan|image|band|
 971031    n   96  null    A

and this one :

|xdate |hem |scan|band|
 971031    n   96    A

CAUTION:

Always use 2MASS Atlas Images for photometric measurements -
2MASS Quicklook Images are restored from lossy-compressed files.