MKMASK (l) | 23 May 2013 | MKMASK (l) |
Mkmask is a program to create or update a mask image using one or more regions lists in DS9 format, or in one of several IRAF-style pixel list formats (ASCII only), that may specify rectangular, circular, elliptical, or arbitrary polygonal regions in a corresponding science image. Mask images are flat FITS files, containing a single header and data unit (HDU), with 16-bit integer pixel values. The user may specify the value to assign unmasked ("good"; default=0) and masked ("bad"; default=1) pixels. These values, goodval and badval, will be cast to the nearest integer when not given as integer values. Up to 8 regions files may be specified at a time. When updating an existing mask image, the value of good[val] is ignored (assumed to have been initialized correctly when that mask was created); only new bad pixels will be flagged by adding badval to the affected pixels in the mask. This behavior allows creating binary flag masks, where pixel values have specific meanings (e.g., 1 = bad, 2 = persistent, 4 = saturated, 8 = near edge, etc.., and unique combinations thereof, e.g., 5 = bad and saturated).
Note that ncols=<axlen1> and nrows=<axlen2> must be specified when a new mask image is to be created, but must not be specified when updating an existing mask image, and that <axlen1> and <axlen2> must be integer valued. The only command-line options are -h or --help, which prints a short manual page, and -d or --debug, which turns on diagnostic messaging. Doubling the latter option (-d -d) raises the verbosity level of the program even more.
mkmask recognizes DS9-style regions lists with pixel regions specified in either physical, image, detector, or amplifier coordinates. Such coordinates are related to pixel coordinates (i,j) in the image pixel buffer either directly or through at most a linear translation in i and/or j, which the user must specify explicitly via the xoff and yoff parameters when non-zero. Often, when an image was trimmed as part of the data reduction process, and if the regions file was saved from DS9 using physical coordinates, the offsets to specify correspond to the values of the LTV1 and LTV2 keywords in the FITS header. Note, that wcs, fk4, fk5, icrs, b1950, j2000, linear, galactic, and ecliptic coordinates are not supported.
mkmask will interpret the following pixel list region specifiers:
DS9-style | IRAF/generic | Region shape and description |
point(x,y) | x y | Single pixel (x,y), where x and y will be rounded to the nearest integer |
line(x1,y1,x2,y2) | Line segment from (x1,y1) to (x2,y2) inclusive both end points | |
circle(x0,y0,radius) | x0 y0 radius | Circular region centered on (x0,y0) with radius radius |
box(x0,y0,da,db,angle) |
x1 x2 y1 y2 |
Rectangular region. For IRAF/generic pixel list format,
the region is aligned with the pixel grid, with lower left corner (x1,y1) and upper right corner (x2,y2), with coordinates rounded to the nearest integer. For DS9-style region format, the region is centered on (x0,y0), has sides of da and db, and is rotated over angle degrees counter-clockwise from the positive x-axis. |
ellipse(x0,y0,da,db,angle) |
x0 y0 da db angle |
Elliptical region centered on (x0,y0) with semi-major and semi-minor axis sizes of da and db, rotated over angle degrees counter-clockwise from the positive x-axis |
polygon(x1,y1,x2,y2,...,xN,yN) | x1 y1 x2 y2 ... xN yN | Arbitrary polygon with vertices (x1,y1), (x2,y2), ..., (xN,yN) for 3 ≤ N ≤ 256 |
Several routines from the CFITSIO [v3.0] I/O library ('libcfitsio.a') by
W.D. Pence, called using their f77 wrappers.
Note, that in some versions of the source code, wrapper file
f77_wrap1.c contained a typo (fixed in v3.14). If compilation of
mkmask warns about a missing symbol/routine ftexist, then
replace
FCALLSCSUB3(ffexist,FTEXIST,ftexest,STRING,PINT,PINT)
with FCALLSCSUB3(ffexist,FTEXIST,ftexist,STRING,PINT,PINT),
and recompile the CFITSIO library.
0. Download the gzip-compressed tar-ball mkmask0.9.tgz and unpack it (this will create a subdirectory named "mkmask0.9"):
$> cd /usr/local/src $> gtar -xvpzf mkmask0.9.tgz1. Compile the mkmask executable:
$> cd mkmask0.9/ $> make ; make clean2. Install symbolic links to the executable in /usr/local/bin/ , and to the man-page in /usr/local/man/ :
$> ln -s /usr/local/src/mkmask0.9/mkmask /usr/local/bin/mkmask $> ln -s /usr/local/src/mkmask0.9/man/mkmask.1 /usr/local/man/man1/mkmask.1Note: the default compiler in the three makefiles (in the main source directory, and in the 'generic/' and 'rjfits/' subdirectories thereof) is the GNU Fortran compiler (/usr/bin/gfortran); alternatively, the code was tested (on Redhat/CentOS5.x linux) to compile using the older GNU Fortran77 compiler (/usr/bin/g77) with its appropriate flags. Note2: if your default shell is tcsh, type rehash at the command prompt in your terminal window, or open a new terminal window. so your system learns about the new executable. This is not necessary if you are running bash.
Given two regions files in DS9-format of pixel regions affected by bright stars and of pixel regions affected by background galaxies, create a new mask image of size 4176×2180 pixels with default pixel value 0, in which pixels in the affected regions are set to a value of 1 (or 2, if a pixel affected by a bright star also belongs to a background galaxy):
$> mkmask smc136i5_mask.fits ncols=4176 nrows=2180 smc136i5brstarph.reg smc136i5bgobjph.regAdd to this a mask of pixels that are saturated:
$> mkmask smc136i5_mask.fits bad=4 smc136i5saturated.reg
R.A. Jansen <Rolf.Jansen@asu.edu>
©2013 R.A. Jansen. This software is provided as is; its use is free, but your mileage may vary; you may not even be able to compile this software without editing its make file(s) and/or source code, and satisfying its dependencies; if it compiles, the software may not produce the results you expect. This is a beta-version, with all that that implies, and should not be deemed free of bugs. That said, it was quite useful to the author, so enjoy!
Rev. 0.9 | 23 May 2013 | MKMASK (l) |