IPP Object Catalog Bit Masks

The IPP pipeline stores some information about object in the FLAGS value in the CMF file. These values represent "bit masks", not standard integer values. That is, individual bits within the value have meaning, rather than the value itself. The bit masks for CMF files are

typedef enum {
    PM_SOURCE_MODE_DEFAULT    = 0x0000, ///<
    PM_SOURCE_MODE_PSFMODEL   = 0x0001, ///< Source fitted with a psf model (linear or non-linear)
    PM_SOURCE_MODE_EXTMODEL   = 0x0002, ///< Source fitted with an extended-source model
    PM_SOURCE_MODE_FITTED     = 0x0004, ///< Source fitted with non-linear model (PSF or EXT; good or bad)
    PM_SOURCE_MODE_FAIL       = 0x0008, ///< Fit (non-linear) failed (non-converge, off-edge, run to zero)
    PM_SOURCE_MODE_POOR       = 0x0010, ///< Fit succeeds, but low-SN, high-Chisq, or large (for PSF -- drop?)
    PM_SOURCE_MODE_PAIR       = 0x0020, ///< Source fitted with a double psf
    PM_SOURCE_MODE_PSFSTAR    = 0x0040, ///< Source used to define PSF model
    PM_SOURCE_MODE_SATSTAR    = 0x0080, ///< Source model peak is above saturation
    PM_SOURCE_MODE_BLEND      = 0x0100, ///< Source is a blend with other sourcers
    PM_SOURCE_MODE_EXTERNAL   = 0x0200, ///< Source based on supplied input position
    PM_SOURCE_MODE_BADPSF     = 0x0400, ///< Failed to get good estimate of object's PSF
    PM_SOURCE_MODE_DEFECT     = 0x0800, ///< Source is thought to be a defect
    PM_SOURCE_MODE_SATURATED  = 0x1000, ///< Source is thought to be saturated pixels (bleed trail)
    PM_SOURCE_MODE_CR_LIMIT   = 0x2000, ///< Source has crNsigma above limit
    PM_SOURCE_MODE_EXT_LIMIT  = 0x4000, ///< Source has extNsigma above limit
    PM_SOURCE_MODE_SUBTRACTED = 0x8000, ///< XXX this flag is actually only used internally (move)
} pmSourceMode;

These are defined in the IPP code base in "ipp/psModules/src/objects/pmSource.h"

If I were in charge of the Transient Classification Server and only wanted to consider objects that were single PSF-like, I might use the following bitmasks to denote bad and good objects:

badbitmask = PM_SOURCE_MODE_FAIL + PM_SOURCE_MODE_POOR + PM_SOURCE_MODE_SATSTAR + 
PM_SOURCE_MODE_BLEND + PM_SOURCE_MODE_EXTERNAL + PM_SOURCE_MODE_BADPSF + PM_SOURCE_MODE_DEFECT + 
PM_SOURCE_MODE_SATURATED + PM_SOURCE_MODE_CR_LIMIT + PM_SOURCE_MODE_EXT_LIMIT

goodbitmask = PM_SOURCE_MODE_PSFMODEL + PM_SOURCE_MODE_FITTED

Intro to Bit Masks

[Paul Price] For an introduction to this idea, see: ​http://en.wikipedia.org/wiki/Bitmask

A real quick example may also help. Let's say I want to encode some boolean values about food. Below I list some food characteristics, and their mask value in binary and decimal:

DELICIOUS	0001 => 1
SPICY		0010 => 2
CHEAP		0100 => 4
MEAT		1000 => 8

Now, some typical dishes might be:

Lobster		MEAT => 1000 => 8
Chicken salad	CHEAP | MEAT => 1100 => 12
Chicken curry	DELICIOUS | SPICY | CHEAP | MEAT => 1111 => 15
Tofu curry	SPICY | CHEAP => 0110 => 6
Spaghetti	DELICIOUS | CHEAP => 0101 => 5

Here, the pipe ("|") between symbols means a bitwise OR operation on the mask values (i.e., do an OR for each bit).

Now, with such a list, say I want to find something to eat tonight. I'm in the mood for something spicy, so I go down the list, looking for lines that have the SPICY bit set. This is done using the "&" (bitwise AND) operation --- look for values for which "value & SPICY" is true. In this case, it could be either chicken curry (value 15) or tofu curry (value 6). Despite the fact that the values are very different, they both have the appropriate bit set, so they both match the filter.