regionmask converts a FITS Region extension table to an image mask, either as a FITS image or as an ASCII list of pixels. The FITS Region extension format describes an arbitrary selection region in terms of set operations on basic geometrical shapes. This format has some virtues to recommend it (most particularly its compactness), and is becoming a standard representation, but at present it remains awkward and poorly supported for most users. Once converted to an image mask the region can be viewed without specialized software and can be used for image processing. An image mask is a raster image (array of pixels) with all pixels outside the region set to zero and all pixels inside the region set to one. This task uses the ShapeScanner module of rgslib to rasterize the region.
The mapping from the region coordinate system to image coordinates is established via the command line parameters: a template may be provided in the form of an existing FITS image or pair of FITS table columns, or the user may specify the mapping explicitly. These same parameters also define a clipping rectangle (the origin and extent of the output image), which engages by default. An alternative clipping rectangle, the “natural” bounding box of the region itself, may be substituted by setting parameter autosize=yes. The natural bounding box of a region is the smallest rectangle outside of which all pixels have identical value. However, some regions (sectors, for example) have no natural bounding box, and auto-sizing these will yield an output image of “infinite” size, which will not be aborted gracefully by regionmask. Note also that for a complex region the auto-sized clipping rectangle computed by regionmask is generally larger than its true natural bounding box. These problems do not seem to warrant solutions at this time.
Parameter whichpixdef activates one of the following specifications for the mapping from region coordinates to image coordinates:
This is the default. Parameter pixdefset is the name of a FITS image (PRIMARY array) with World Coordinate System (WCS) keywords defined on the first and second axes. The output image will use the same pixel size and alignment, and (unless auto-sized) the same origin and extent.
Parameters xcolumn and ycolumn are the names of FITS table columns with WCS and bounding keywords. The preferred bounding keywords are TLMIN and TLMAX, but in their absence TDMIN and TDMAX will be used instead. The WCS keywords specify the size and alignment of the pixels and the bounding keywords specify the clipping rectangle of the output image (unless auto-sized). Its first and second axes are specified by xcolumn and ycolumn respectively.
Parameters xrpix, xrval, xdelt, and xbins explicitly define the first axis of the output image. Parameters yrpix, yrval, ydelt, and ybins explicitly define its second axis. (rpix,rval,delt) is a WCS mapping: delt is the grid spacing, rval is a reference point in the region coordinate system, and rpix is the image coordinate associated with that reference point. Unless auto-sized, bins is the extent of the output image, and its origin is placed at the reference point.
The default output format (parameter withmaskset=yes) is a FITS image (PRIMARY array) of unsigned bytes. Its WCS keywords record the mapping from image coordinates back to the region coordinate system. Parameter maskset is the file name.
The alternate output format (parameter withmaskset=no) is sent to the tty standard out in three columns of ASCII text: pixel x-coordinate, low pixel y-coordinate, and high pixel y-coordinate. The latter two columns define a vertical span of pixels that are all inside the region. Multiple spans at the same x-coordinate are output on successive lines, such that the output is sorted in increasing order of pixel coordinates (x first, then y). The output is restricted to the clipping rectangle, and x-coordinates within that rectangle are skipped unless associated with at least one y-coordinate span. Note that these coordinates refer to the reference pixel of the given region-to-image coordinate mapping—not the lower-left corner of the clipping rectangle.
