ColorImage

class lsst.images.ColorImage(array, /, *, bbox=None, yx0=None, sky_projection=None, metadata=None)

Bases: GeneralizedImage

An RGB image with an optional SkyProjection.

Parameters:

• array (ndarray[tuple[int, int, Literal[3]], dtype[Any]]) – Array or fill value for the image. Must have three dimensions with the shape of the third dimension equal to three.

• bbox (Box | None, default: None) – Bounding box for the image.

• 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.

• sky_projection (Optional[SkyProjection[Any]], 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 image.

Attributes Summary

absolute	A proxy object for slicing a generalized image using absolute pixel coordinates.
array	The 3-d array (numpy.ndarray).
astropy_wcs	An Astropy WCS for this image's pixel array.
bbox	The 2-d bounding box of the image (Box).
blue	A 2-d view of the blue channel (Image).
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.
green	A 2-d view of the green channel (Image).
local	A proxy object for slicing a generalized image using "local" or "array" pixel coordinates.
metadata	Arbitrary flexible metadata associated with the image (dict).
red	A 2-d view of the red channel (Image).
sky_projection	The projection that maps the pixel grid to the sky (SkyProjection | None).
yx0	The coordinates of the first pixel in the array (YX [int]).

Methods Summary

bbox_from_sky_circle(center, radius[, clip])	Calculate the bounding box on this image corresponding to a circular region on the sky.
copy()	Deep-copy the image.
from_channels(r, g, b, *[, sky_projection, ...])	Construct from separate RGB images.
read(path, **kwargs)	Read an instance of this class from a file.
serialize(archive)	Serialize the masked image to an output archive.
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.

See also

lsst.images.BoxSliceFactory, lsst.images.IntervalSliceFactory

array

The 3-d array (numpy.ndarray).

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 sky_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

The 2-d bounding box of the image (Box).

blue

A 2-d view of the blue channel (Image).

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 sky_projection.

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

green

A 2-d view of the green channel (Image).

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, SkyProjection, 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()

red

A 2-d view of the red channel (Image).

sky_projection

The projection that maps the pixel grid to the sky (SkyProjection | None).

yx0

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

Methods Documentation

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.

copy()

Deep-copy the image.

Return type:

ColorImage

static from_channels(r, g, b, *, sky_projection=None, metadata=None)

Construct from separate RGB images.

All channels are assumed to have the same bounding box, sky_projection, and pixel type.

Parameters:

• r (Image) – Red channel image.

• g (Image) – Green channel image.

• b (Image) – Blue channel image.

• sky_projection (Optional[SkyProjection[Any]], default: None) – Sky projection for the image, defaulting to that of r.

• metadata (dict[str, TypeAliasType] | None, default: None) – Flexible metadata to associate with the image.

Return type:

ColorImage

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

serialize(archive)

Serialize the masked image to an output archive.

Parameters:

archive (OutputArchive[Any]) – Archive to write to.

Return type:

ColorImageSerializationModel

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