IRSA Image Server - Cutouts

Overview

For files accessed via URL's starting with /ibe/data/, one can request a cutout of a FITS image (or gzipped FITS image) by simply appending a query string containing the center and size parameters to the image URL. Here are some sample FITS image URLs:

And here are a few cutout URLs for these same images:

By default, cutouts are automatically gzipped. However, adding gzip=false to the parameters will cause an uncompressed FITS image to be returned instead.

If the requested cutout does not intersect the parent image at all, an HTTP 400 Bad Request will be returned. If the cutout is not completely contained in the parent, it is clipped. In this latter case, the requested cutout center will not be the center of cutout returned - in fact, it may not even lie inside it!

Parameters

center=x,y[units]

The center parameter must consist of a comma separated coordinate pair followed by an optional units specification. If units is set to px, pix or pixels, then x,y are interpreted as the pixel space coordinates of the desired cutout center. If units are angular (rad, deg, etc...), then x,y are interpreted as the J2000 right ascension (x) and declination (y) of the desired cutout center. If no units are specified, degrees are assumed. Declinations outside of [-90, 90] degrees are illegal; right ascensions are range-reduced, so any value will do.

Examples:

  • center=10,10deg
  • center=10,10
  • center=3.141,1.56rad
  • center=300.5,120px
size=x[,y][units]

The size parameter consists of one or two (comma separated) values followed by an optional units specification. Units can be pixels (px, pix, pixels) or angular (arcsec, arcmin, deg, rad); the default is degrees. The first size value (x) is taken to be the full-width of the desired cutout along the first image axis (NAXIS1), and the second (y) is taken to be the full-height along the second axis (NAXIS2). If only one size value is specified, it is used as both the full-width and full-height. Negative sizes are illegal.

Examples:

  • size=0.1
  • size=200px
  • size=100,200px
  • size=3arcmin
  • size=30,45arcsec
gzip=flag

This parameter determines whether or not the cutout is returned in compressed (gzipped) form or not. If the parameter is omitted, then cutouts are gzipped. Compression can also be explicitly requested with:

  • gzip=1
  • gzip=on
  • gzip=t[rue]
  • gzip=y[es]

To download uncompressed images, pass:

  • gzip=0
  • gzip=off
  • gzip=f[alse]
  • gzip=n[o]

Parsing of unit specifications is fairly forgiving, e.g. radians, asec, ", arcminutes and ' are all recognized. Malformed unit specifications and illegal sizes or coordinates will result in an HTTP 400 Bad Request response.

Local file names

When downloading files or cutouts via most browsers, you will be prompted with a "Save As" dialog box including a suggested file name. This behavior is achieved by sending an HTTP Content-Disposition header containing the file name suggestion.

However, command-line clients for web access typically ignore this header by default. Unless instructed otherwise, wget will derive a local file name from the URL (including the query string), and curl will write to standard out. To obtain shorter file names that have the proper extension (.fits.gz if gzipped cutouts were requested, .fits otherwise), one can explicitly specify a local file name:

wget
wget -O file URL
wget --output-document=file URL

For example:

wget --output-document=mycutout.fits.gz "serverroot/data/wise/allsky/4band_p1bm_frm/6a/02206a/149/02206a149-w1-int-1b.fits?center=70,20&size=200pix"
curl
curl -o file URL
curl --output file URL
curl URL > file # uses the shell to redirect standard out to a file

One can also force both wget and curl to honor the file name suggestion in the Content-Disposition header:

wget
wget --content-disposition URL

For example:

wget --content-disposition "serverroot/data/wise/allsky/4band_p1bm_frm/6a/02206a/149/02206a149-w1-int-1b.fits?center=70,20&size=200pix"

will download a cutout to a local file named 02206a149-w1-int-1b.fits.gz. Note that the --content-disposition option is only available in wget versions 1.11.x or later.

curl

Using the -J/--remote-header-name option in conjunction with -O/--remote-name does the trick:

curl -O -J "serverroot/data/wise/allsky/4band_p1bm_frm/6a/02206a/149/02206a149-w1-int-1b.fits?center=70,20&size=200pix"

Getting Help

If you've run into a problem, think you've found a bug, or simply have questions, please contact IRSA User Support.