Cutouts Service

Introduction and Instructions

[ Overview | How to use Cutouts | Output ]

Overview:

The IRSA Cutouts Service is a general tool which can be used to create small "cutout" FITS images (and JPEGs) from large images and mosaics at IRSA.

Input:

Single Location:

Select the "Single Location" radio button on the input form, and enter a coordinate or astronomical object name. Your entry can be any valid coordinates, or an object name to be automatically resolved by NED or SIMBAD. If you want your cutouts to be a size other than the default, enter it in the Cutout Size field.

Multiple Positions:

Select the "Multiple Positions" radio button, and then enter name of a table on your local file system which contains a list of coordinates or astronomical object names. You can click on the "Browse" button to help you select your table.

Most of IRSA's services allow users to enter single objects or coordinates into a web form, or they can upload a file containing multiple objects and coordinates. The latter method is called "Table Upload," for which IRSA accepts four ASCII table formats:

IPAC ASCII Column-Aligned (Download template)
Comma-Separated Values (CSV) or Comma-Delimited (Download template)
Tab-Delimited (Download template)
A Simple List of Objects (such as astronomical source names) (Download template)

There are two ways to ensure your tables will work with IRSA's services:

Run your tables through IRSA's Table Reformat and Validation tool to identify possible errors.
Read and follow the Using Tables With IRSA Services help document to learn and troubleshoot table formats, including:
- Detailed descriptions of the four acceptable table formats
- A description of how sexagesimal and Galactic coordinates are handled by IRSA services
- Best practices for creating tables
- Troubleshooting solutions for common error messages

Please note, space-delimited files are only valid if using IPAC table format.

Your table must:

Conform to one of the above four allowed formats
Contain columns with values for ra and dec OR object name
Optionally, the user can include a "size" column (exact name of this column can be specified on the form input) to request different sizes at different locations. If you are using this functionality, you MUST DELETE the value from the Uniform Cutout size field, which will take precedence over any size values found in your table. Also if using the cutouts size column in your table, please abide by the allowed cutout size maximum range, which is specified at each Cutout Size text box. The program will error if any of the requested cutout sizes are outside the allowed range; no cutouts will be created. See example table containing a size column, which can be used as input

Data Sets:

Some collections are comprised of multiple data sets; in this case, the user is given the option to choose which data sets to generate cutouts from. Each data set is listed next to a checkbox; the default data sets are checked.

Results:

Whether you chose a Single Location or the Multiple Positions option, hit the Submit button once you're done specifying the request. A status page is returned with an approximate estimate as to how long it will take the service to perform the cutouts (in seconds, minutes or hours). For large jobs which take more than five minutes, an estimated finish time will be displayed. The Status button can be used to check whether or not the request is finished. If the request is not finished, the status page is repeated, if the request is done, the results page will be displayed. You MUST CLICK on the Status button to get the results page; results do not load automatically.

The final results page contains a summary of the cutouts that were generated. Up to 50 cutouts are displayed as previews on the results page in table form. To display more than 50 cutouts can slow down many browsers; there is currently no way to preview all the cutout results if there are more than 50 of them, although all the cutouts can still be downloaded.

The preview table contains:

A Quicklook JPEG image of the cutout (click for full-size image)
RA and Dec of the center of the cutout
Name of the cutout's Dataset
Original_Filename of the FITS image mosaic from which the cutout was created
Links to download the FITS file to disk, or send it to IRSA's FITS viewer.

Gray scales alternate in the preview table based on a change in value in the RA, to distinguish a group of cutouts at the same location (same grey scale background).

Note: If no cutouts are presented on the results page, it may be because:

The requested position did not match any of the selected data sets
The cutout generated was completely blank (i.e., generated from data containing gaps or padded with zeros). The number of blank cutouts will be displayed. Note these blank cutouts are skipped in the creation process; they are not available for download.

Instructions are given regarding bulk download of all the results, using tools such as 'Wget'. There is also the option to download everything within one TAR file.

Wget Instructions:

Wget is a GNU Unix tool which can be used to retrieve all the cutouts from the IRSA server to your local disk. If you do not have 'Wget' installed on your machine, follow these download instructions. If you have 'Wget' (or have just installed it) do the following to download the cutouts:

Create a local directory to contain the downloaded images
cd into that location
Use the wget command as printed on the results page to download the FITS cutouts into the current location
- To retrieve JPEG files instead of FITS files, substitute "-A fits" with "-A jpg"
- To retrieve JPEG files in addition to FITS files, add "-A jpg" to the command

Below is a sample Wget command (using GNU Wget v1.5.3), which may display on two lines:

wget -r -nd -A fits -1 2 https://irsa.ipac.caltech.edu:443/work/TMP_AAAuiaaGd/Cutouts/0_0_ga.v0034/results

-r: recursive mode (since results is a directory)
-nd: "no directories" keeps Wget from creating a directory named "irsa.ipac.caltech.edu:443/work/TMP_AAAuiaaGd/Cutouts/0_0_ga.v0034" (you may choose to leave this out)
-A fits: retrieve only files that end in "fits" - without this option, you will retrieve unnecessary files that are located in the directory on the server.
-l 2: (that's a lowercase 'L') - retrieve files within two directory levels, since that is how IRSA structures the results
https...: is the location of the cutouts; this location is unique for every run of the Cutouts service

For more options and information on using wget, such as specifying an output directory location for the FITS cutouts, type 'wget --help' on the command line.

TAR File:

If you choose to request a TAR file of all the results (cutouts in FITS and jpeg formats), click the "DOWNLOAD TAR FILE" button. NOTE: the results will no longer be accessible! Instead, there will be a link to the TAR file to download it to disk, and 'wget' instructions on how to get the tar file without using a browser.

Click on the Download TAR file link to get the results. Important note about the TAR file download link option: some browers, like Safari, have stalled when downloading huge cutouts TAR files (using the tar file link provided). In this case, use the 'wget' command displayed on the tar download page, to get the TAR file instead.

Coordinate/Object Example

Examples of input coordinates for the Coordinate/Object field are provided for each of the cutout services, in a variety of coordinate systems. Each example coordinate is separated by a "|" character. Only one is necessary as input in the "Coordinate/Object" field, without the "|" character. The default coordinate system is (RA DEC) Equatorial J2000, in decimal degrees (1st example below).

EXAMPLES OF INPUT COORDINATES:
Equatorial J2000 (eq): "290.971773 11.774474 eq"
Local Equatorial J2000 (Equ): "19h23m53.23s +11d46m28.1s Equ J2000"
Galactic (ga): "47.09669 -1.71325 ga"
Object Name: "M 16"

In the 2nd example above, "Local Equatorial J2000 (Equ)" is also known as "sexagesimal" (hours, minutes, seconds; degrees, minutes, seconds). The abbreviation "eq" and "Equ" stands for equinox of the coordinate system; typically equinox is "J2000" (which is the default when the user does not enter the equinox) and of course could also be "B1950", etc.