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.
Here is a sample URL that makes 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
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. |
| 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 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 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 does not work with with the Tile parameter. |
| 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 HLSP images and False for other images. Note that all boolean parameters can be specified using a variety of input formats, including yes/no, 1/0, true/false, and t/f. |
| 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. |
| X, Y | Central pixel position for the cutout (both default to 500). These are ignored if Size=ALL is specified. |
| WCS | If set to a true Boolean value, then the X,Y values are 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. |
| Corner | If set to a true Boolean value, then the X,Y 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. |
| 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 a true boolean value, the HTTP header is specified so that the output JPEG/PNG image is 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 RLW 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 RLW 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. |