Cutouts: fitscut.cgi interface

fitscut.cgi is a simple Python wrapper that parses the script arguments and runs the fitscut C program. This script is used throughout the HLA interface for previews, tiles in the interactive display, etc. The SIAP interface generates fitscut links for JPEG images. The URL for this service is http://hla.stsci.edu/cgi-bin/fitscut.cgi.

All parameter names are insensitive to case (so you can use either SIZE or size for the parameter name.) Values are also case-insensitive except for the dataset names (Red, Green, Blue), which must match the filenames. Use the Caseless parameter to make the dataset names case-insensitive as well.

Here are some sample URLs for some common cases:

  1. Get a grayscale JPEG image of the Antennae binned down by a factor of 7 (zoom=0.14):
    http://hla.stsci.edu/cgi-bin/fitscut.cgi?red=hst_10188_10_acs_wfc_f814w&size=ALL&zoom=0.14
  2. Get a color JPEG image of the Antennae binned down to 1024 pixels (in the longest direction):
    http://hla.stsci.edu/cgi-bin/fitscut.cgi?red=hst_10188_10_acs_wfc_f814w&green=hst_10188_10_acs_wfc_f550m&blue=hst_10188_10_acs_wfc_f435w&size=ALL&output_size=1024
  3. Get a 64×64 pixel JPEG cutout at RA=180.4894958, Dec=-18.8688861 binned up to 512x512 pixels:
    http://hla.stsci.edu/cgi-bin/fitscut.cgi?red=hst_11577_20_wfc3_uvis_f814w&RA=180.4894958&Dec=-18.8688861&size=64&output_size=512

Note that Boolean parameters (Caseless, Align, etc.) can be specified using a variety of input formats, including yes/no, 1/0, true/false, and t/f.

Script parameters for fitscut.cgi:

Parameter Description
Red Name of the image for the red band
Green Name of the image for the green band
Blue Name of the image for the blue band.
At least one image must be specified (in which case a monochrome image is produced.) If more than one is given then a color image is generated. The image names may be MAST datasets (which are located using rules based on the name), paths in the web server space (so /file.fits would be a file in the web server's home directory) or an absolute path name on the server. Filenames must be resolvable to FITS files (though .fits and some other extensions may be omitted). Filenames can include a FITS extension identifier in brackets (e.g, [1] or [SCI]); the default is to use the primary data or the first image extension if the primary is null. Note that fitscut does support compressed FITS images and transparently uncompresses them if required (though that may be slow for some compression algorithms.)
Caseless If set to a true Boolean value, the image names are matched ignoring the case of characters. The default is to require the case of the name to match exactly (so "HST_10188_10_ACS_WFC_F814W" is not the same as "hst_10188_10_acs_wfc_f814w").
Align If set to a true Boolean value, the green and blue images are resampled using the FITS header world coordinates to match the red image pixels. By default the red/green/blue images are assumed to have matched coordinates so that the color images can be created pixel-by-pixel without any resampling. The only exceptions (at the moment) are the PHAT HLSP images, where Align is True by default because those images are known to be misaligned. The Align parameter can be used to generate color images when the red/green/blue images are not on the same coordinate grid. Note however that (1) this can be somewhat time-consuming compared with the usual fitscut color images, and (2) the HLA coordinates for images are not necessarily well-aligned for independent visits, so the color images may still not be well aligned after resampling. This parameter works with the Tile parameter, which is used by the interactive display.
Qext Number of extension with data quality/weight information. This is an optional parameter that is needed only for images where bad pixels have non-zero values (e.g., the current version of the WFPC2 combined images). The program assumes that the specified FITS extension is an image of the same size as the primary data array with zeros indicating bad pixels. For the usual drizzled WFPC2 images, Qext=4 is a good value. FITS extension numbers start at 0 for the primary header-data unit, 1 for the first extension, etc.
For color images this can also be a comma-separated list of integers (Qext=4,3,2), although that is probably rarely needed.
Badpix Boolean parameter indicating whether the BADPIX FITS header keyword is used to identify bad pixels in the image. The default is Badpix = True for most HLSP images and False for other images.
Badvalue Floating point value for pixels that should be treated as missing values in the image. Default is Badvalue=0; if the image has real data values that are exactly zero, Badvalue should be set to some other value.
Parameters that select cutout location and image output size
Size Size in pixels for cutout (default 512). May either be a single integer for square cutouts or ncolumns,nrows for a rectangular cutout. May also be the special value ALL, in which case the entire image is extracted rather than a subset.
RA, Dec Central position in degrees for the cutout. These are ignored if Size=ALL is specified.
X, Y Central position in pixels for the cutout (both default to 500). These are ignored if Size=ALL or RA, Dec are specified.
WCS If set to a true Boolean value, then the X,Y values are interpreted as RA and Dec in degrees. Default is X,Y in pixels. If set, X,Y are converted from degrees to pixels using WCS information in the FITS header. Note that it is better to use the RA,Dec parameters to specify positions in degrees. This parameter is retained for backward-compatibility.
Corner If set to a true Boolean value, then the X,Y or RA,Dec positions specify the lower left corner of the cutout section rather than the center position.
Zoom Zoom factor for image (default 1). Values smaller than unity shrink the image (useful for large cutouts), and values larger than unity expand the image (possibly useful for very small cutouts). This is rounded to the nearest integral factor, so useful values are 1, 0.5, 0.33, 0.25, etc.
Output_Size Exact output size for image in pixels. If specified this overrides the Zoom factor in determining the image size. Default is to use the zoom factor and the Size to produce an output image of Size x Zoom pixels. If the cutout image is rectangular, the longest dimension (width or height) will be Output_Size pixels.
ApplyOmega (Relevant only for HLA images.) If set to a true Boolean value, the image rotation and shift determined in the construction of the Hubble Source Catalog are applied to the HLA image to determine a more accurate position for the cutout extraction. This should be used when extracting cutouts based on HSC source positions. If set to a false Boolean value, the original (uncorrected) HLA image coordinates are used. The default is true, so that the coordinates used have the HSC corrections applied.
Parameters that determine contrast (for JPEG or PNG format images)
Autoscale Contrast adjustment: Percentage of image histogram to retain (default 99.5). Smaller values turn up the contrast. For Autoscale=99.5, the image is scaled from the 99.5 percentile (bright) to the 0.5 (= 100-99.5) percentile (dark).
Asinh If set to a true Boolean value, use the Lupton asinh contrast algorithm. This is similar to a logarithmic scale but is usable for both positive and negative pixels. Default is on.
Invert If set to a true Boolean value, invert the display scale so that the brightest pixels are black and the faintest pixels are white. Default is False.
AutoscaleMax, AutoscaleMin Alternative contrast adjustment. These can set the lower and upper percentiles separately (e.g., 99.5 at the top and 1.5 at the bottom instead of the default 99.5,0.5). These can also be comma-separated triples to set different autoscale values for the red,green,blue band images. These parameters allow more flexbility in the contrast and color balance.
UserMax, UserMin If given, use these value as the maximum/minimum for mapping the pixel values to grayscales. Default is to use the autoscale values. These may be single values or three comma-separated values to specify independent values for the red,green,blue bands. These parameters provide maximum control over the contrast but also require knowing the dynamic range of the image pixel values. Note that the Range parameter (described below) can be used to query the image to determine good values for the UserMax and UserMin parameters.
Additional parameters
Format Specify the image format. Options are jpg (the default), png, fits, json, or range. FITS images have a copy of the header from the original FITS file with the WCS keywords modified to describe the cutout regions. JSON format is used to get the pixel values for a small region of the image (e.g., for the pixel value readout in the HLA interactive display). The RANGE format uses the specified contrast parameters (autoscale, etc.) to compute the min/max values for the image, which are returned in a JSON value. Note that the RANGE return values can be used in a later fitscut call as UserMax, UserMin parameters to set the contrast.
Callback If specified, wrap the JSON return result in a callback to the named JavaScript function. This applies only to JSON format returns.
Compass If set to a true Boolean value, draws compass arrows showing north and east.
Palette Specify color palette used for single-filter (non-color) images. Options are gray (default), heat, cool, rainbow, red, green, or blue. * (png format only) *
getWCS If set to a true Boolean value, returns a JSON format dictionary containing the FITS world-coordinate system rather than an image. This is a utility function useful for the interactive display. Here is a sample URL that shows the return format:
http://hla.stsci.edu/cgi-bin/fitscut.cgi?red=hst_10188_10_acs_wfc_f814w&getWCS=yes
Download If set to a true Boolean value, the HTTP header is set to force the output JPEG/PNG image to be downloaded rather than displayed in the browser. By default FITS format images are downloaded and other formats are handled by the browser. This parameter is relevant only if the image URL is embedded within a web page.
Tile If given, the image is being accessed in "tile" mode. This is used for the interactive display (and is unlikely to be useful in other contexts). The parameter is of the form "tile-zoom-x-y" where the zoom, x, y parameters are indices into the tiled image. See Rick White if you need the details. The same contrast is used for all tiles. The returned tile size is 256×256 pixels. A special HTTP redirect to a blank image is returned if the requested tile is off the edge of the image or if the parameter is "tile-none".
MaxZoom In Tile mode, sets the highest zoom-out level (compared to the default 1:1 scale.) See Rick White if you need the details.
TextErrors If set to a true Boolean value, on failure produces a simple text error message. The default is to produce an HTML error message.

2016 December 23