The MASK class and the use of bit mask images
in the Astronomy & Astrophysics package for MATLAB
Description:
The MASK class supports the use of bit mask images. A bit mask image is an image associated with a science image, with the same size as the science image. Each pixel in the bit mask image is an unsigned integer. Each bit in the unsigned integer corresponds to some "problem" that may be associated with the pixel. For example, if the first bit represents saturated pixel, then the value of the first bit in each pixel indicate if the pixel is saturated or not.
The MASK class is part of the SIM image class, but it can also be used on its own.
The bit mask image, as well as other meta data, is distributed with the SIM image, and each process that uses the SIM image can use or update the bit mask image corresponds to the image.
Credit
If you are using this code or products in your scientific publication please give a reference to Ofek (2014; ascl.soft 07005) and Zackay, Ofek & Gal-Yam (2016).
License
Unless specified otherwise this code and products are released under the GNU general public license version 3.
Installation
See http://weizmann.ac.il/home/eofek/matlab/doc/install.html for installation instruction and additional documentation.
Examples
The bit mask dictionary
The bit mask dictionary is a function that relates the index of a bit mask (e.g., the first bit) to its name (e.g., 'Bit_ImSaturated'). The default bit mask dictionary is MASK/def_bitmask_pipeline and it requires 32 bit unsigned integer.
For example, in order to see the dictionary associated with a MASK object:
M=MASK;
M.showdic;
The default mask was designed to include the most useful definition. However, if needed, the user can define his/her own dictionary function.
Bit mask names to values
To calculate the bit mask that corresponds to a bit mask name or several bit mask names:
M=MASK;
bitname2val(M,'Bit_BiasAnom')
% or for multiple names
Value=bitname2val(M,{'Bit_BiasAnom','Bit_Edge'})
% In order to see the status of the specific bits (right to left):
dec2bin(Value,32)
To convert a specific unsigned integer to the its corresponding bit names:
val2bitname(M,8193)
Operations on bit masks
To create a MASK object you can either
M=MASK
or define an object, like SIM, that contains a MASK object:
S=FITS.read2sim('/home/eran/matlab/data/TestImages/PTF_201608101725*.fits');
To set the value of specific pixels in the bit mask:
Flag = S.Im>40000;
S=bitmask_set(S,Flag,'Bit_ImSaturated')
Here Flag is a logical image whith ones in positions where the flux is above 40,000 and zeros otherwise. This operation will set the first bit in all the pixels identified by Flag to one. The output S will contain now a MASK image.
To search for pixels in which specific bits are true:
[Res,Count]=bitmask_find(S,{'Bit_ImSaturated'});
In this example, Count is a counter of the number of pixels in the image S in which the Bit_ImSaturated bit is on, while Res is a SIM object containing a logical flag image of the pixels in which the Bit_Imsaturated bit is on.
Given a MASK object that contains multiple mask images, you can combine the mask images using the MASK/mas_combine operation.
MASK/mask_add can be used to combine two MASK objects into the first MASK object.
MASK/mask_init can be used to initialize a MASK object.
MASK/mask2sim copies a MASK object into an existing SIM object.
MASK/mask4src can copy the values of the mask in some specific pixels to a vector.
Populating the bit mask
Many functions can populate and use the bit mask images. Some functions like the SIM/bias and SIM/flat methods will populate the bias and flat related bit masks.
Additional useful functions are SIM/flag_backgrad that look for large gradients in the background and populate the bit associated bit. SIM/flag_holes idenitify holes (e.g., due to flat field issues) in the imag, and SIM/flag_saturated identify saturated pixels.
SIM/mextractor can identify also diffraction spikes, and it can propogate all the bit mask to their associated sources.