MaskSchema#

class lsst.images.MaskSchema(planes, dtype=<class 'numpy.uint8'>)#

Bases: object

A schema for a bit-packed mask array.

Parameters:

planes (Iterable[MaskPlane | None]) – Iterable of MaskPlane instances that define the schema. None values may be included to reserve bits for future use.
dtype (TypeAliasType, default: <class 'numpy.uint8'>) – The numpy data type of the mask arrays that use this schema.

Notes

A MaskSchema is a collection of mask planes, which each correspond to a single bit in a mask array. Mask schemas are immutable and associated with a particular array data type, allowing them to safely precompute the index and bitmask for each plane.

MaskSchema indexing is by integer (the overall index of a plane in the schema). The descriptions attribute may be indexed by plane name to get the description for that plane, and the bitmask method can be used to obtain an array that can be used to select one or more planes by name in a mask array that uses this schema.

If no mask planes are provided, a None placeholder is automatically added.

Attributes Summary

`descriptions`	A mapping from plane name to description.
`dtype`	The numpy data type of the mask arrays that use this schema.
`mask_size`	The number of elements in the last dimension of any mask array that uses this schema.
`names`	The names of the mask planes, in bit order.

Methods Summary

`bit`(plane)	Return the last array index and mask for the given mask plane.
`bitmask`(*planes)	Return a 1-d mask array that represents the union (i.e. bitwise OR) of the planes with the given names.
`bits_per_element`(dtype)	Return the number of mask bits per array element for the given data type.
`from_fits_header`(header[, dtype])	Reconstruct a schema from the `MSKN`/`MSKD` cards written by `update_header`.
`interpret`(value)	Return the names of the mask planes that are set in the given pixel value.
`split`(dtype)	Split the schema into an equivalent series of schemas that each have a `mask_size` of `1`, dropping all `None` placeholders.
`strip_header`(header)	Remove all header cards added by `update_header`.
`update_header`(header)	Add a description of this mask schema to a FITS header.

Attributes Documentation

descriptions#: A mapping from plane name to description.

dtype#: The numpy data type of the mask arrays that use this schema.

mask_size#: The number of elements in the last dimension of any mask array that uses this schema.

names#: The names of the mask planes, in bit order.

Methods Documentation

bit(plane)#

Return the last array index and mask for the given mask plane.

Parameters:: plane (str) – Name of the mask plane.
Return type:: MaskPlaneBit

bitmask(*planes)#

Return a 1-d mask array that represents the union (i.e. bitwise OR) of the planes with the given names.

Parameters:: *planes (str) – Mask plane names.
Returns:: A 1-d array with shape (mask_size,).
Return type:: numpy.ndarray

static bits_per_element(dtype)#

Return the number of mask bits per array element for the given data type.

Parameters:: dtype (TypeAliasType) – Data type of the mask array elements.
Return type:: int

classmethod from_fits_header(header, dtype=<class 'numpy.uint8'>)#

Reconstruct a schema from the MSKN/MSKD cards written by update_header.

Parameters:

header (Header) – FITS header containing MSKN{n:04d} plane-name cards and MSKD{n:04d} description cards.
dtype (TypeAliasType, default: <class 'numpy.uint8'>) – Data type of the mask arrays that will use this schema. The cards describe a mask_size==1 serialized form and do not record the in-memory dtype, so the caller must supply it; it defaults to the same uint8 used by the Mask constructor.

Returns:

Schema whose planes are ordered by their MSKN index, with None placeholders inserted for any gaps in that numbering.

Return type:

MaskSchema

Raises:

ValueError – Raised if the header contains no MSKN cards.

interpret(value)#

Return the names of the mask planes that are set in the given pixel value.

Parameters:: value (ndarray) – A 1-d array of length mask_size, representing a single pixel in a Mask.
Return type:: list[str]

split(dtype)#

Split the schema into an equivalent series of schemas that each have a mask_size of 1, dropping all None placeholders.

Parameters:: dtype (TypeAliasType) – Data type of the new mask pixels.
Returns:: A list of mask schemas that together include all planes in self and have mask_size equal to 1. If there are no mask planes (only None placeholders) in self, a single mask schema with a None placeholder is returned; otherwise None placeholders are returned.
Return type:: list [MaskSchema]

strip_header(header)#

Remove all header cards added by update_header.

Parameters:: header (Header) – FITS header to remove the mask schema cards from.
Return type:: None

update_header(header)#

Add a description of this mask schema to a FITS header.

Parameters:: header (Header) – FITS header to add the mask schema description to.
Return type:: None