process_mask

This code can be used to modify a binary mask by removing small clusters of bad or invalid pixels (hereafter 'holes') and by computing the distance of each valid pixel to the closest invalid one, with the purpose of, for instance, defining a new apodized mask

Location in HEALPix directory tree: src/f90/process_mask/process_mask.F90 

FORMAT

% process_mask [parameter_file]

QUALIFIERS

mask_file =

Input binary mask FITS file

hole_min_size =

Minimal size (in pixels) of invalid regions to be kept (can be used together with hole_min_surf_arcmin2 below, the result will be the largest of the two). default:0

hole_min_surf_arcmin2 =

Minimal surface area (in arcmin2) of invalid regions to be kept (can be used together with hole_min_size above, the result will be the largest of the two). default:0.0

filled_file =

Optional output FITS file to contain mask with filled-in small holes (as defined above). default:”, no output file

distance_file =

Optional output FITS file to contain angular distance (in radians) from valid pixel to the closest invalid one. default:”, no output file

DESCRIPTION

For a given input binary mask, in which pixels have either value 0 (=invalid) or 1 (=valid), this code produces a map containing for each valid pixel, its distance (in Radians, measured between pixel centers) to the closest invalid pixel.

This distance map can then be used to define an apodized mask.

Two pixels are considered adjacent if they have at least one point in common (eg, a pixel corner or a pixel side).

It is possible to treat small holes (=cluster of adjacent invalid pixels) as valid, by specifying a minimal number of pixels and/or minimal surface area (whichever is the largest), and the resulting new mask can be output.

The output FITS files have the same ordering as the input mask (even though the processing is done in NESTED ordering).

The algorithmic complexity of the distance calculation is expected to scale like $\propto N_{\mathrm{pix}}^p \propto N_{\mathrm{side}}^{2p}$ with p in [1.5,2] depending on the mask topology, even though the code has been optimized to reduce the number of calculations by a factor 10² to 10³ compared to a naive implementation, and the most computationally intensive loops are parallelized with OpenMP. On a 3.06GHz Intel Core 2 Duo, the distances on a N_side=512 Galactic + Point sources mask can be computed in a few seconds, while a similar N_side=2048 mask takes a minute or less to process. For totally arbitrary masks though, the return times can be multiplied by as much as 10.

SUPPORT

This section lists those routines and facilities (including those external to the HEALPix distribution) which can assist in the utilisation of process_mask.

mollview

IDL routine to view the input and output masks and the angular distance map.

mask_tools

F90 module containing the routines dist2holes_nest, fill_holes_nest, maskborder_nest, size_holes_nest used in process_mask and described in the ”Fortran Subroutines” document

EXAMPLE # 1:

process_mask

process_mask runs in interactive mode, self-explanatory.

EXAMPLE # 2:

process_mask filename

When `filename' is present, process_mask enters the non-interactive mode and parses its inputs from the file `filename'. This has the following structure: the first entry is a qualifier which announces to the parser which input immediately follows. If this input is omitted in the input file, the parser assumes the default value. If the equality sign is omitted, then the parser ignores the entry. In this way comments may also be included in the file. In this example, the file contains the following qualifiers:
mask_file= wmap_temperature_analysis_mask_r9_5yr_v3.fits
hole_min_size= 100
distance_file= !/tmp/dist_wmap.fits
process_mask computes the distance in Radians from each valid pixel to the closest invalid pixel for WMAP-5 mask 'wmap_temperature_analysis_mask_r9_5yr_v3.fits', ignoring the holes containing fewer than 100 pixels, and outputs the result in '/tmp/dist_wmap.fits'.

RELEASE NOTES

■ (Initial release HEALPix 3.00)