Mask#

class lsst.images.Mask(array_or_fill=0, /, *, schema, bbox=None, yx0=None, shape=None, sky_projection=None, metadata=None)#

Bases: GeneralizedImage

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

Parameters:

array_or_fill (ndarray | int, default: 0) – Array or fill value for the mask. If a fill value, bbox or shape must be provided.
schema (MaskSchema) – Schema that defines the planes and their bit assignments.
bbox (Box | None, default: None) – Bounding box for the mask. This sets the shape of the first two dimensions of the array.
yx0 (Sequence[int] | None, default: None) – 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 (Sequence[int] | None, default: None) – 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.
sky_projection (SkyProjection | None, default: None) – Projection that maps the pixel grid to the sky.
metadata (dict[str, TypeAliasType] | None, default: None) – Arbitrary flexible metadata to associate with the mask.

Notes

Indexing the array attribute of a Mask does not take into account its yx0 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`	Flexible metadata associated with the image (`MetadataView`).
`schema`	Schema that defines the planes and their bit assignments (`MaskSchema`).
`sky_projection`	The projection that maps this mask's pixel grid to the sky (`SkyProjection` \| `None`).
`yx0`	The coordinates of the first pixel in the array (`YX` [`int`]).

Methods Summary

`add_plane`(name, description)	Return a new mask with one additional mask plane.
`add_planes`(planes, *[, drop])	Return a new mask with planes added and/or dropped.
`bbox_from_sky_circle`(center, radius[, clip])	Calculate the bounding box on this image corresponding to a circular region on the sky.
`clear`([plane, boolean_mask])	Clear one or more mask planes.
`compare`(other)	Return a plane-by-plane comparison with another mask.
`copy`()	Deep-copy the mask and metadata.
`describe`(*[, brief, detail, exclude])	Return a `Report` describing this object.
`from_legacy`(legacy[, plane_map, sky_projection])	Convert from an `lsst.afw.image.Mask` instance.
`get`(plane)	Return a 2-d boolean array for the given mask plane.
`read`(path, **kwargs)	Read an instance of this class from a 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, sky_projection, yx0])	Make a view of the mask, with optional updates.
`write`(path, **kwargs)	Write this object to a 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, SkyProjection, 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.

metadata#

Flexible metadata associated with the image (MetadataView).

Notes

The view combines two sources:

metadata.native: metadata that is part of the image’s data model and is saved with it. Keys are case-sensitive.
metadata.external: read-only metadata carried in from the file the image was read from, such as the primary FITS header. Keys are case-insensitive, and COMMENT and HISTORY cards are not included.

Lookups check native metadata first, matching case exactly, and then external metadata. Writes go to native metadata; adding a new key that case-insensitively matches an external key raises KeyError. When an external key is repeated, which of its values is returned is unspecified; use get_all to obtain every value.

Native metadata is shared with subimages and other views. Assigning a mapping replaces the native metadata with a shallow copy of it (of just its native metadata, for a MetadataView), disconnecting this image from any others it was shared with while leaving external metadata readable. To disconnect while keeping the current contents, or to start empty:

image.metadata = image.metadata
image.metadata = {}

Assignment does not check for keys that shadow external metadata.

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

sky_projection#

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

Notes

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

yx0#: The coordinates of the first pixel in the array (YX [int]).

Methods Documentation

add_plane(name, description)#

Return a new mask with one additional mask plane.

This is a convenience wrapper around add_planes for the common case of adding a single plane.

Parameters:

name (str) – Unique name for the new mask plane.
description (str) – Human-readable documentation for the new mask plane.

Returns:

A new mask whose schema includes the new plane; see add_planes for the reallocation and view semantics.

Return type:

Mask

Raises:

ValueError – Raised if a plane named name already exists.

add_planes(planes, *, drop=())#

Return a new mask with planes added and/or dropped.

Parameters:

planes (Iterable[MaskPlane | None]) – New mask planes to append, in order, after the planes retained from this mask. None entries reserve unused bits (placeholders), exactly as in MaskSchema.
drop (Iterable[str], default: ()) – Names of existing planes to remove from the schema.

Returns:

A new mask with the updated schema. Retained planes keep their pixel values (copied by name); newly added planes start cleared.

Return type:

Mask

Raises:

ValueError – Raised if a name in drop is not an existing plane, or if a plane in planes collides with a retained plane name.

Notes

Adding or dropping planes always reallocates the backing array and returns a new Mask; this mask is left unchanged and any views or subimages of it continue to refer to the original array with the original schema. This is deliberate: there is no way to update the schema of an existing view, and a stale view must never set bits that its now-outdated schema regards as unused. Dropping a plane compacts the schema, so planes after it are reassigned to lower bits and the pixel values are repacked by plane name to match.

bbox_from_sky_circle(center, radius, clip=False)#

Calculate the bounding box on this image corresponding to a circular region on the sky.

Parameters:

center (SkyCoord) – The center of the circle, as a scalar astropy.coordinates.SkyCoord in any frame.
radius (Angle) – Radius of the circle, as a scalar astropy.coordinates.Angle.
clip (bool, default: False) – If True (False is default), clip pixel bounds when the circle extends outside the image. If False an exception is raised if any part of the circle is off the image.

Returns:

Bounding box enclosing the circle in this image’s pixel coordinates.

Return type:

Box

Raises:

NotContainedError – Raised if the requested region is entirely off the image or if any part of the region is off the image and clipping is False.
ValueError – Raised if center or radius is not scalar, or if this image has no sky projection.

clear(plane=None, boolean_mask=Ellipsis)#

Clear one or more mask planes.

Parameters:

plane (str | None, default: None) – Name of the mask plane to set. If None all mask planes are cleared.
boolean_mask (ndarray | EllipsisType, default: Ellipsis) – 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.

Return type:

None

compare(other)#

Return a plane-by-plane comparison with another mask.

Parameters:

other (Mask) – The mask to compare against.

Returns:

Dictionary mask planes as keys, where the values are:

the number of pixels with that plane set in self but not other;
the number of pixels with that plane set in other but not self.

Mask planes where the images have the same pixels set are not included, so the result is empty for identical masks. Mask planes present in only one operand are treated as though they were unset for all pixels in the other operand.

Return type:

dict [str, tuple [int, int]]

Notes

Two masks with different schemas can have an empty compare result while still not satisfying an equality check, as long as the planes they have in common have the same pixels set and any planes present in only one operand have no pixels set.

copy()#

Deep-copy the mask and metadata.

Return type:: Mask

describe(*, brief=False, detail=False, exclude=())#

Return a Report describing this object.

Parameters:

brief (bool, optional) – Whether to build only what repr and str read.
detail (bool, optional) – Whether to include extras that are too expensive for a default report, such as per-plane set-pixel counts.
exclude (Collection [str], optional) – Names of report elements to omit.

Returns:

report – Report describing this object.

Return type:

Report

static from_legacy(legacy, plane_map=None, *, sky_projection=None)#

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

Parameters:

legacy (Any) – An lsst.afw.image.Mask instance. This will not share pixel data with the new object.
plane_map (Mapping[str, MaskPlane] | None, default: None) – A mapping from legacy mask plane name to the new plane name and description. If not provided, the right legacy mask plane will be guessed, but this can depend on which mask planes the legacy mask actually has set. Planes from get_legacy_optional_mask_planes are added when the legacy mask defines them and has pixels set in them.
sky_projection (Optional[SkyProjection[Any]], default: None) – Projection from pixels to sky.

Returns:

Converted mask.

Return type:

Mask

get(plane)#

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

Parameters:: plane (str) – Name of the mask plane.
Returns:: A 2-d boolean array with the same shape as bbox that is True where the bit for plane is set and False elsewhere.
Return type:: numpy.ndarray

classmethod read(path, **kwargs)#

Read an instance of this class from a file.

A thin convenience wrapper around lsst.images.serialization.read_archive that fixes the expected in-memory type to this class. The container format is inferred from path’s extension.

Parameters:

path (str | ParseResult | ResourcePath | Path) – File to read; convertible to lsst.resources.ResourcePath.
**kwargs (Any) – Forwarded to read_archive (e.g. bbox to read a subimage).

Return type:

Self

static read_legacy(uri, *, plane_map=None, ext=1, fits_wcs_frame=None)#

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

Parameters:

uri (str | ParseResult | ResourcePath | Path) – URI or file name.
plane_map (Mapping[str, MaskPlane] | None, default: None) – A mapping from legacy mask plane name to the new plane name and description. If not provided, the right legacy mask plane will be guessed, but this can depend on which mask planes the legacy mask actually has set. Planes from get_legacy_optional_mask_planes are added when the legacy mask defines them and has pixels set in them.
ext (str | int, default: 1) – Name or index of the FITS HDU to read.
fits_wcs_frame (Frame | None, default: None) – If not None and the HDU containing the mask has a FITS WCS, attach a SkyProjection to the returned mask by converting that WCS.

Returns:

Mask read from the file.

Return type:

Mask

serialize(archive, *, update_header=<function no_header_updates>, save_projection=True, add_offset_wcs='A', tile_shape=None, options_name=None)#

Serialize the mask to an output archive.

Parameters:

archive (OutputArchive[TypeVar(P, bound= BaseModel)]) – Archive to write to.
update_header (Callable[[Header], None], default: <function no_header_updates at 0x7fe9f6f95620>) – 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 (bool, default: True) – If True, save the SkyProjection 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 " ").
add_offset_wcs (str | None, default: 'A') – 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 / yx0. Set to None to not write this WCS. If this is set to " ", it will prevent the SkyProjection from being saved as a FITS WCS.
tile_shape (tuple[int, ...] | None, default: None) – The recommended shape of each tile, if the archive will save the array in distinct tiles for faster subarray retrieval. This is a hint; archives are not required to use this value.
options_name (str | None, default: None) – Use this name to look up archive options.

Return type:

MaskSerializationModel[TypeVar]

set(plane, boolean_mask=Ellipsis)#

Set a mask plane.

Parameters:

plane (str) – Name of the mask plane to set.
boolean_mask (ndarray | EllipsisType, default: Ellipsis) – 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.

Return type:

None

to_legacy(plane_map=None)#

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

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

Parameters:: plane_map (Mapping[str, MaskPlane] | None, default: None) – A mapping from legacy mask plane name to the new plane name and description. Schema planes the map does not name are written under their own names. If not provided, every schema plane is written under its own name.
Returns:: Converted mask.
Return type:: lsst.afw.image.Mask

update(other)#

Update self to include all common mask values set in other.

Parameters:: other (Mask) – Mask whose set bits are merged into self.
Return type:: None

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=Ellipsis, sky_projection=Ellipsis, yx0=Ellipsis)#

Make a view of the mask, with optional updates.

Parameters:

schema (MaskSchema | EllipsisType, default: Ellipsis) – Replacement schema; defaults to the current schema.
sky_projection (SkyProjection | None | EllipsisType, default: Ellipsis) – Replacement sky projection; defaults to the current one.
yx0 (Sequence[int] | EllipsisType, default: Ellipsis) – Replacement origin of the mask; defaults to the current origin.

Return type:

Mask

Notes

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

write(path, **kwargs)#

Write this object to a file.

A thin convenience wrapper around lsst.images.serialization.write_archive. The container format is chosen from path’s extension.

Parameters:

path (str) – Destination file path. Must not already exist.
**kwargs (Any) – Forwarded to write_archive (e.g. compression_options and compression_seed for FITS).

Return type:

None