Template Class Mask

Nested Relationships

Inheritance Relationships

Base Type

Class Documentation

template<typename MaskPixelT = lsst::afw::image::MaskPixel>
class Mask : public lsst::afw::image::ImageBase<MaskPixelT>

Represent a 2-dimensional array of bitmask pixels

Some mask planes are always defined (although you can add more with Mask::addMaskPlane):

  • BAD This pixel is known to be bad (e.g. the amplifier is not working)

  • CR This pixel is contaminated by a cosmic ray

  • DETECTED This pixel lies within an object’s Footprint

  • DETECTED_NEGATIVE This pixel lies within an object’s Footprint, and the detection was looking for pixels below a specified level

  • EDGE This pixel is too close to the edge to be processed properly

  • INTRP This pixel has been interpolated over

    Note

    should be called INTERPOLATED

  • SAT This pixel is saturated and has bloomed

    Note

    should be called SATURATED

  • SUSPECT This pixel is untrustworthy, and you may wish to discard any Source containing it

Public Types

typedef detail::MaskPlaneDict MaskPlaneDict
typedef detail::Mask_tag image_category

Public Functions

Mask(unsigned int width, unsigned int height, MaskPlaneDict const &planeDefs = MaskPlaneDict())

Construct a Mask initialized to 0x0

Parameters

  • width: number of columns

  • height: number of rows

  • planeDefs: desired mask planes

Mask(unsigned int width, unsigned int height, MaskPixelT initialValue, MaskPlaneDict const &planeDefs = MaskPlaneDict())

Construct a Mask initialized to a specified value

Parameters

  • width: number of columns

  • height: number of rows

  • initialValue: Initial value

  • planeDefs: desired mask planes

Mask(lsst::geom::Extent2I const &dimensions = lsst::geom::Extent2I(), MaskPlaneDict const &planeDefs = MaskPlaneDict())

Construct a Mask initialized to 0x0

Parameters

  • dimensions: Number of columns, rows

  • planeDefs: desired mask planes

Mask(lsst::geom::Extent2I const &dimensions, MaskPixelT initialValue, MaskPlaneDict const &planeDefs = MaskPlaneDict())

Construct a Mask initialized to a specified value

Parameters

  • dimensions: Number of columns, rows

  • initialValue: Initial value

  • planeDefs: desired mask planes

Mask(lsst::geom::Box2I const &bbox, MaskPlaneDict const &planeDefs = MaskPlaneDict())

Construct a Mask initialized to 0x0

Parameters

  • bbox: Desired number of columns/rows and origin

  • planeDefs: desired mask planes

Mask(lsst::geom::Box2I const &bbox, MaskPixelT initialValue, MaskPlaneDict const &planeDefs = MaskPlaneDict())

Construct a Mask initialized to a specified value

Parameters

  • bbox: Desired number of columns/rows and origin

  • initialValue: Initial value

  • planeDefs: desired mask planes

Mask(std::string const &fileName, int hdu = fits::DEFAULT_HDU, std::shared_ptr<lsst::daf::base::PropertySet> metadata = std::shared_ptr<lsst::daf::base::PropertySet>(), lsst::geom::Box2I const &bbox = lsst::geom::Box2I(), ImageOrigin origin = PARENT, bool conformMasks = false, bool allowUnsafe = false)

Construct a Mask by reading a regular FITS file.

The meaning of the bitplanes is given in the header. If conformMasks is false (default), the bitvalues will be changed to match those in

Mask’s plane dictionary. If it’s true, the bitvalues will be left alone, but Mask’s dictionary will be modified to match the on-disk version.
Parameters

  • [in] fileName: File to read.

  • [in] hdu: HDU to read, 0-indexed (i.e. 0=Primary HDU). The special value of afw::fits::DEFAULT_HDU reads the Primary HDU unless it is empty, in which case it reads the first extension HDU.

  • [inout] metadata: Metadata read from the header (may be null).

  • [in] bbox: If non-empty, read only the pixels within the bounding box.

  • [in] origin: Coordinate system of the bounding box; if PARENT, the bounding box should take into account the xy0 saved with the image.

  • [in] conformMasks: If true, make Mask conform to the mask layout in the file.

  • [in] allowUnsafe: Permit reading into the requested pixel type even when on-disk values may overflow or truncate.

Mask(fits::MemFileManager &manager, int hdu = fits::DEFAULT_HDU, std::shared_ptr<lsst::daf::base::PropertySet> metadata = std::shared_ptr<lsst::daf::base::PropertySet>(), lsst::geom::Box2I const &bbox = lsst::geom::Box2I(), ImageOrigin origin = PARENT, bool conformMasks = false, bool allowUnsafe = false)

Construct a Mask by reading a FITS image in memory.

The meaning of the bitplanes is given in the header. If conformMasks is false (default), the bitvalues will be changed to match those in

Mask’s plane dictionary. If it’s true, the bitvalues will be left alone, but Mask’s dictionary will be modified to match the on-disk version.
Parameters

  • [in] manager: An object that manages the memory buffer to read.

  • [in] hdu: HDU to read, 0-indexed (i.e. 0=Primary HDU). The special value of afw::fits::DEFAULT_HDU reads the Primary HDU unless it is empty, in which case it reads the first extension HDU.

  • [inout] metadata: Metadata read from the header (may be null).

  • [in] bbox: If non-empty, read only the pixels within the bounding box.

  • [in] origin: Coordinate system of the bounding box; if PARENT, the bounding box should take into account the xy0 saved with the image.

  • [in] conformMasks: If true, make Mask conform to the mask layout in the file.

  • [in] allowUnsafe: Permit reading into the requested pixel type even when on-disk values may overflow or truncate.

Mask(fits::Fits &fitsfile, std::shared_ptr<lsst::daf::base::PropertySet> metadata = std::shared_ptr<lsst::daf::base::PropertySet>(), lsst::geom::Box2I const &bbox = lsst::geom::Box2I(), ImageOrigin origin = PARENT, bool conformMasks = false, bool allowUnsafe = false)

Construct a Mask from an already-open FITS object.

The meaning of the bitplanes is given in the header. If conformMasks is false (default), the bitvalues will be changed to match those in

Mask’s plane dictionary. If it’s true, the bitvalues will be left alone, but Mask’s dictionary will be modified to match the on-disk version.
Parameters

  • [in] fitsfile: A FITS object to read from, already at the desired HDU.

  • [inout] metadata: Metadata read from the header (may be null).

  • [in] bbox: If non-empty, read only the pixels within the bounding box.

  • [in] origin: Coordinate system of the bounding box; if PARENT, the bounding box should take into account the xy0 saved with the image.

  • [in] conformMasks: If true, make Mask conform to the mask layout in the file.

  • [in] allowUnsafe: Permit reading into the requested pixel type even when on-disk values may overflow or truncate.

template<typename OtherPixelT>
Mask(Mask<OtherPixelT> const &rhs, const bool deep)
Mask(const Mask &src, const bool deep = false)

Construct a Mask from another Mask

Parameters

  • src: mask to copy

  • deep: deep copy? (construct a view with shared pixels if false)

Mask(Mask &&src)
~Mask()
Mask(const Mask &src, const lsst::geom::Box2I &bbox, ImageOrigin const origin = PARENT, const bool deep = false)

Construct a Mask from a subregion of another Mask

Parameters

  • src: mask to copy

  • bbox: subregion to copy

  • origin: coordinate system of the bbox

  • deep: deep copy? (construct a view with shared pixels if false)

Mask(ndarray::Array<MaskPixelT, 2, 1> const &array, bool deep = false, lsst::geom::Point2I const &xy0 = lsst::geom::Point2I())
void swap(Mask &rhs)
Mask &operator=(MaskPixelT const rhs)
Mask &operator=(const Mask &rhs)
Mask &operator=(Mask &&rhs)
Mask &operator|=(Mask const &rhs)

OR a Mask into a Mask.

Mask &operator|=(MaskPixelT const rhs)

OR a bitmask into a Mask.

template<>
Mask &operator&=(Mask const &rhs)

AND a Mask into a Mask.

template<>
Mask &operator&=(MaskPixelT const rhs)

AND a bitmask into a Mask.

Mask subset(lsst::geom::Box2I const &bbox, ImageOrigin origin = PARENT) const

Return a subimage corresponding to the given box.

This method is wrapped as

getitem in Python.
Return

A subimage view into this.

Parameters

  • bbox: Bounding box of the subimage returned.

  • origin: Origin bbox is rleative to; PARENT accounts for xy0, LOCAL does not.

Note

This method permits mutable views to be obtained from const references to images (just as the copy constructor does). This is an intrinsic flaw in Image’s design.

Mask operator[](lsst::geom::Box2I const &bbox) const

Return a subimage corresponding to the given box (interpreted as PARENT coordinates).

Mask &operator^=(Mask const &rhs)

XOR a Mask into a Mask.

Mask &operator^=(MaskPixelT const rhs)

XOR a bitmask into a Mask.

ImageBase<MaskPixelT>::PixelReference operator()(int x, int y)

get a reference to the specified pixel

Parameters

  • x: x index

  • y: y index

ImageBase<MaskPixelT>::PixelConstReference operator()(int x, int y) const

get the specified pixel (const version)

Parameters

  • x: x index

  • y: y index

bool operator()(int x, int y, int plane) const

is the specified mask plane set in the specified pixel?

Parameters

  • x: x index

  • y: y index

  • plane: plane ID

ImageBase<MaskPixelT>::PixelReference operator()(int x, int y, CheckIndices const &check)

get a reference to the specified pixel checking array bounds

Parameters

  • x: x index

  • y: y index

  • check: Check array bounds?

ImageBase<MaskPixelT>::PixelConstReference operator()(int x, int y, CheckIndices const &check) const

get the specified pixel with array checking (const version)

Parameters

  • x: x index

  • y: y index

  • check: Check array bounds?

bool operator()(int x, int y, int plane, CheckIndices const &check) const

is the specified mask plane set in the specified pixel, checking array bounds?

Parameters

  • x: x index

  • y: y index

  • plane: plane ID

  • check: Check array bounds?

void writeFits(std::string const &fileName, std::shared_ptr<lsst::daf::base::PropertySet const> metadata = std::shared_ptr<lsst::daf::base::PropertySet>(), std::string const &mode = "w") const

Write a mask to a regular FITS file.

Parameters

  • [in] fileName: Name of the file to write.

  • [in] metadata: Additional values to write to the header (may be null).

  • [in] mode: “w”=Create a new file; “a”=Append a new HDU.

void writeFits(fits::MemFileManager &manager, std::shared_ptr<lsst::daf::base::PropertySet const> metadata = std::shared_ptr<lsst::daf::base::PropertySet>(), std::string const &mode = "w") const

Write a mask to a FITS RAM file.

Parameters

  • [in] manager: Manager object for the memory block to write to.

  • [in] metadata: Additional values to write to the header (may be null).

  • [in] mode: “w”=Create a new file; “a”=Append a new HDU.

void writeFits(fits::Fits &fitsfile, std::shared_ptr<lsst::daf::base::PropertySet const> metadata = std::shared_ptr<lsst::daf::base::PropertySet const>()) const

Write a mask to an open FITS file object.

Parameters

  • [in] fitsfile: A FITS file already open to the desired HDU.

  • [in] metadata: Additional values to write to the header (may be null).

void writeFits(std::string const &filename, fits::ImageWriteOptions const &options, std::string const &mode = "w", std::shared_ptr<daf::base::PropertySet const> header = nullptr) const

Write a mask to a regular FITS file.

Parameters

  • [in] filename: Name of the file to write.

  • [in] options: Options controlling writing of FITS image.

  • [in] mode: “w”=Create a new file; “a”=Append a new HDU.

  • [in] header: Additional values to write to the header (may be null).

void writeFits(fits::MemFileManager &manager, fits::ImageWriteOptions const &options, std::string const &mode = "w", std::shared_ptr<daf::base::PropertySet const> header = nullptr) const

Write a mask to a FITS RAM file.

Parameters

  • [in] manager: Manager object for the memory block to write to.

  • [in] options: Options controlling writing of FITS image.

  • [in] mode: “w”=Create a new file; “a”=Append a new HDU.

  • [in] header: Additional values to write to the header (may be null).

void writeFits(fits::Fits &fitsfile, fits::ImageWriteOptions const &options, std::shared_ptr<daf::base::PropertySet const> header = nullptr) const

Write a mask to an open FITS file object.

Parameters

  • [in] fitsfile: A FITS file already open to the desired HDU.

  • [in] options: Options controlling writing of FITS image.

  • [in] header: Additional values to write to the header (may be null).

std::string getAsString(int x, int y)
void clearAllMaskPlanes()

Clear all the pixels.

void clearMaskPlane(int plane)

Clear the specified bit in all pixels.

void setMaskPlaneValues(const int plane, const int x0, const int x1, const int y)

Set the bit specified by “planeId” for pixels (x0, y) … (x1, y)

void removeAndClearMaskPlane(const std::string &name, bool const removeFromDefault = false)

Clear all pixels of the specified mask and remove the plane from the mask plane dictionary; optionally remove the plane from the default dictionary too.

Parameters

  • name: of maskplane

  • removeFromDefault: remove from default mask plane dictionary too

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if plane is invalid

MaskPlaneDict const &getMaskPlaneDict() const

Return the Mask’s maskPlaneDict

void printMaskPlanes() const

print the mask plane dictionary to std::cout

void conformMaskPlanes(const MaskPlaneDict &masterPlaneDict)

Adjust this mask to conform to the standard Mask class’s mask plane dictionary, adding any new mask planes to the standard.

Ensures that this mask (presumably from some external source) has the same plane assignments as the Mask class. If a change in plane assignments is needed, the bits within each pixel are permuted as required. The provided masterPlaneDict describes the true state of the bits in this Mask’s pixels and overrides its current MaskDict

Any new mask planes found in this mask are added to unused slots in the Mask class’s mask plane dictionary.

Parameters

  • masterPlaneDict: mask plane dictionary currently in use for this mask

Public Static Functions

static MaskPixelT getPlaneBitMask(const std::vector<std::string> &names)

Return the bitmask corresponding to a vector of plane names OR’d together

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if plane is invalid

static Mask readFits(std::string const &filename, int hdu = fits::DEFAULT_HDU)

Read a Mask from a regular FITS file.

Parameters

  • [in] filename: Name of the file to read.

  • [in] hdu: Number of the “header-data unit” to read (where 0 is the Primary HDU). The default value of afw::fits::DEFAULT_HDU is interpreted as “the first HDU with NAXIS != 0”.

static Mask readFits(fits::MemFileManager &manager, int hdu = fits::DEFAULT_HDU)

Read a Mask from a FITS RAM file.

Parameters

  • [in] manager: Object that manages the memory to be read.

  • [in] hdu: Number of the “header-data unit” to read (where 0 is the Primary HDU). The default value of afw::fits::DEFAULT_HDU is interpreted as “the first HDU with NAXIS != 0”.

static std::string interpret(MaskPixelT value)

Interpret a mask value as a comma-separated list of mask plane names.

static MaskPlaneDict parseMaskPlaneMetadata(std::shared_ptr<lsst::daf::base::PropertySet const> metadata)

Given a PropertySet that contains the MaskPlane assignments, setup the MaskPlanes.

Return

a dictionary of mask plane name: plane ID

Parameters

  • metadata: metadata from a Mask

static void clearMaskPlaneDict()

Reset the maskPlane dictionary.

static int addMaskPlane(const std::string &name)
static void removeMaskPlane(const std::string &name)
static int getMaskPlane(const std::string &name)

Return the mask plane number corresponding to a plane name

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if plane is invalid

static MaskPixelT getPlaneBitMask(const std::string &name)

Return the bitmask corresponding to a plane name

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if plane is invalid

static int getNumPlanesMax()
static int getNumPlanesUsed()
static void addMaskPlanesToMetadata(std::shared_ptr<lsst::daf::base::PropertySet>)

Given a PropertySet, replace any existing MaskPlane assignments with the current ones.

template<typename MaskPT = MaskPixelT>
struct ImageTypeFactory

A templated class to return this classes’ type (present in Image/Mask/MaskedImage)

Public Types

template<>
typedef Mask<MaskPT> type

Return the desired type.