Mask#

Bases: GeneralizedImage

A 2-d bitmask image backed by a 3-d byte array.

Parameters#

array_or_fill: Array or fill value for the mask. If a fill value, bbox or shape must be provided.
schema: Schema that defines the planes and their bit assignments.
bbox: Bounding box for the mask. This sets the shape of the first two dimensions of the array.
start: Logical coordinates of the first pixel in the array, ordered y, x (unless an XY instance is passed). Ignored if bbox is provided. Defaults to zeros.
shape: Leading dimensions of the array, ordered y, x (unless an XY instance is passed). Only needed if array_or_fill is not an array and bbox is not provided. Like the bbox, this does not include the last dimension of the array.
projection: Projection that maps the pixel grid to the sky.
obs_info: General information about the associated observation in standardized form.
metadata: Arbitrary flexible metadata to associate with the mask.

Notes#

Indexing the array attribute of a Mask does not take into account its start offset, but accessing a subimage mask by indexing a Mask with a Box does, and the bbox of the subimage is set to match its location within the original mask.

A mask’s bbox corresponds to the leading dimensions of its backing numpy.ndarray, while the last dimension’s size is always equal to the mask_size of its schema, since a schema can in general require multiple array elements to represent all of its planes.

Attributes Summary

`absolute`	A proxy object for slicing a generalized image using absolute pixel coordinates.
`array`	The low-level array (`numpy.ndarray`).
`astropy_wcs`	An Astropy WCS for this image's pixel array.
`bbox`	2-d bounding box of the mask (`Box`).
`butler_dataset`	The butler dataset reference for this image (`lsst.daf.butler.SerializedDatasetRef` \| `None`).
`butler_provenance`	The butler inputs and ID of the task quantum that produced this dataset (`lsst.daf.butler.DatasetProvenance` \| `None`)
`fits_wcs`	An Astropy FITS WCS for this image's pixel array.
`local`	A proxy object for slicing a generalized image using "local" or "array" pixel coordinates.
`metadata`	Arbitrary flexible metadata associated with the image (`dict`).
`obs_info`	General information about the associated observation in standard form.
`projection`	The projection that maps this mask's pixel grid to the sky (`Projection` \| `None`).
`schema`	Schema that defines the planes and their bit assignments (`MaskSchema`).

Methods Summary

`clear`([plane, boolean_mask])	Clear one or more mask planes.
`copy`()	Deep-copy the mask and metadata.
`deserialize`(model, archive, *[, bbox, ...])	Deserialize a mask from an input archive.
`from_legacy`(legacy[, plane_map])	Convert from an `lsst.afw.image.Mask` instance.
`get`(plane)	Return a 2-d boolean array for the given mask plane.
`read_fits`(url, *[, bbox])	Read an image from a FITS file.
`read_legacy`(uri, *[, plane_map, ext, ...])	Read a FITS file written by `lsst.afw.image.Mask.writeFits`.
`serialize`(archive, *[, update_header, ...])	Serialize the mask to an output archive.
`set`(plane[, boolean_mask])	Set a mask plane.
`to_legacy`([plane_map])	Convert to an `lsst.afw.image.Mask` instance.
`update`(other)	Update `self` to include all common mask values set in `other`.
`view`(*[, schema, projection, start, obs_info])	Make a view of the mask, with optional updates.
`write_fits`(filename, *[, compression])	Write the mask to a FITS file.

Attributes Documentation

absolute#: A proxy object for slicing a generalized image using absolute pixel coordinates.

Notes#

In this convention, the first row and column of the pixel grid is bbox.start. A subimage and its parent image share the same absolute pixel coordinate system, and most lsst.images types (e.g. Box, Projection, PointSpreadFunction) operate exclusively in this system.

Note that astropy.wcs and numpy.ndarray are not aware of the bbox.start offset that defines tihs coordinates system; use local slicing for indices obtained from those.

See Also#

lsst.images.BoxSliceFactory lsst.images.IntervalSliceFactory

array#

The low-level array (numpy.ndarray).

Assigning to this attribute modifies the existing array in place; the bounding box and underlying data pointer are never changed.

astropy_wcs#: An Astropy WCS for this image’s pixel array.

Notes#

As expected for Astropy WCS objects, this defines pixel coordinates such that the first row and column in any associated arrays are (0, 0), not bbox.start, as is the case for projection.

This object satisfies the astropy.wcs.wcsapi.BaseHighLevelWCS and astropy.wcs.wcsapi.BaseLowLevelWCS interfaces, but it is not an astropy.wcs.WCS (use fits_wcs for that).

bbox#

2-d bounding box of the mask (Box).

This sets the shape of the first two dimensions of the array.

butler_dataset#: The butler dataset reference for this image (lsst.daf.butler.SerializedDatasetRef | None).

butler_provenance#: The butler inputs and ID of the task quantum that produced this dataset (lsst.daf.butler.DatasetProvenance | None)

fits_wcs#: An Astropy FITS WCS for this image’s pixel array.

Notes#

As expected for Astropy WCS objects, this defines pixel coordinates such that the first row and column in any associated arrays are (0, 0), not bbox.start, as is the case for projection.

This may be an approximation or absent if projection is not naturally representable as a FITS WCS.

local#: A proxy object for slicing a generalized image using “local” or “array” pixel coordinates.

Notes#

In this convention, the first row and column of the pixel grid is always at (0, 0). This is also the convention used by astropy.wcs objects. When a subimage is created from a parent image, its “local” coordinate system is offset from the coordinate systems of the parent image.

Note that most lsst.images types (e.g. Box, Projection, PointSpreadFunction) operate instead in “absolute” coordinates, which is shared by subimage and their parents.

See Also#

lsst.images.BoxSliceFactory lsst.images.IntervalSliceFactory

metadata#: Arbitrary flexible metadata associated with the image (dict).

Notes#

Metadata is shared with subimages and other views. It can be disconnected by reassigning to a copy explicitly:

image.metadata = image.metadata.copy()

obs_info#: General information about the associated observation in standard form. (ObservationInfo | None).

projection#: The projection that maps this mask’s pixel grid to the sky (Projection | None).

Notes#

The pixel coordinates used by this projection account for the bounding box start; they are not just array indices.

schema#: Schema that defines the planes and their bit assignments (MaskSchema).

Methods Documentation

clear(plane: str | None = None, boolean_mask: ndarray | ellipsis = Ellipsis) → None#

Clear one or more mask planes.

Parameters#

plane: Name of the mask plane to set. If None all mask planes are cleared.
boolean_mask: A 2-d boolean array with the same shape as bbox that is True where the bit for plane should be cleared and False where it should be left unchanged. May be ... to clear the bit everywhere.

copy() → Mask#: Deep-copy the mask and metadata.

classmethod deserialize(model: ~lsst.images._mask.MaskSerializationModel[Any], archive: ~lsst.images.serialization._input_archive.InputArchive[~typing.Any], *, bbox: ~lsst.images._geom.Box | None = None, strip_header: ~collections.abc.Callable[[~astropy.io.fits.header.Header], None] = <function no_header_updates>) → Mask#

Deserialize a mask from an input archive.

Parameters#

model: A Pydantic model representation of the mask, holding references to data stored in the archive.
archive: Archive to read from.
bbox: Bounding box of a subimage to read instead.
strip_header: A callable that strips out any FITS header cards added by the update_header argument in the corresponding call to serialize.

static from_legacy(legacy: Any, plane_map: Mapping[str, MaskPlane] | None = None) → Mask#

Convert from an lsst.afw.image.Mask instance.

Parameters#

legacy: An lsst.afw.image.Mask instance. This will not share pixel data with the new object.
plane_map: A mapping from legacy mask plane name to the new plane name and description.

get(plane: str) → ndarray#

Return a 2-d boolean array for the given mask plane.

Parameters#

plane: Name of the mask plane.

Returns#

numpy.ndarray: A 2-d boolean array with the same shape as bbox that is True where the bit for plane is set and False elsewhere.

static read_fits(url: str | ParseResult | ResourcePath | Path, *, bbox: Box | None = None) → Mask#

Read an image from a FITS file.

Parameters#

url: URL of the file to read; may be any type supported by lsst.resources.ResourcePath.
bbox: Bounding box of a subimage to read instead.

Read a FITS file written by lsst.afw.image.Mask.writeFits.

Parameters#

uri: URI or file name.
plane_map: A mapping from legacy mask plane name to the new plane name and description.
ext: Name or index of the FITS HDU to read.
fits_wcs_frame: If not None and the HDU containing the mask has a FITS WCS, attach a Projection to the returned mask by converting that WCS.

serialize(archive: ~lsst.images.serialization._output_archive.OutputArchive, *, update_header: ~collections.abc.Callable[[~astropy.io.fits.header.Header], None] = <function no_header_updates>, save_projection: bool = True, save_obs_info: bool = True, add_offset_wcs: str | None = 'A') → MaskSerializationModel[TypeVar]#

Serialize the mask to an output archive.

Parameters#

archive: Archive to write to.
update_header: A callback that will be given the FITS header for the HDU containing this mask in order to add keys to it. This callback may be provided but will not be called if the output format is not FITS. As multiple HDUs may be added, this function may be called multiple times.
save_projection: If True, save the Projection attached to the image, if there is one. This does not affect whether a FITS WCS corresponding to the projection is written (it always is, if available, and if add_offset_wcs is not " ").
save_obs_info: If True, save the ObservationInfo attached to the image, if there is one.
add_offset_wcs: A FITS WCS single-character suffix to use when adding a linear WCS that maps the FITS array to the logical pixel coordinates defined by bbox.start. Set to None to not write this WCS. If this is set to " ", it will prevent the Projection from being saved as a FITS WCS.

set(plane: str, boolean_mask: ndarray | ellipsis = Ellipsis) → None#

Set a mask plane.

Parameters#

plane: Name of the mask plane to set
boolean_mask: A 2-d boolean array with the same shape as bbox that is True where the bit for plane should be set and False where it should be left unchanged (not set to zero). May be ... to set the bit everywhere.

to_legacy(plane_map: Mapping[str, MaskPlane] | None = None) → Any#

Convert to an lsst.afw.image.Mask instance.

The pixel data will not be shared between the two objects.

Parameters#

plane_map: A mapping from legacy mask plane name to the new plane name and description.

update(other: Mask) → None#: Update self to include all common mask values set in other.

Notes#

This only operates on the intersection of the two mask bounding boxes and the mask planes that are present in both. Mask bits are only set, not cleared (i.e. this uses |= updates, not = assignments).

view(*, schema: MaskSchema | ellipsis = Ellipsis, projection: Projection | None | ellipsis = Ellipsis, start: Sequence[int] | ellipsis = Ellipsis, obs_info: ObservationInfo | None | ellipsis = Ellipsis) → Mask#: Make a view of the mask, with optional updates.

Notes#

This can only be used to make changes to schema descriptions; plane names must remain the same (in the same order).

write_fits(filename: str, *, compression: ~lsst.images.fits._common.FitsCompressionOptions | None = FitsCompressionOptions(algorithm=<FitsCompressionAlgorithm.GZIP_2: 'GZIP_2'>, tile_shape=None, quantization=None)) → None#

Write the mask to a FITS file.

Parameters#

filename: Name of the file to write to. Must be a local file.
compression: Compression options.

Mask#

Parameters#

Notes#

Notes#

See Also#

Notes#

Notes#

Notes#

See Also#

Notes#

Notes#

Parameters#

Parameters#

Parameters#

Parameters#

Returns#

Parameters#

Parameters#

Parameters#

Parameters#

Parameters#

Notes#

Notes#

Parameters#