GeneralizedImage

class lsst.images.GeneralizedImage(metadata: dict[str, MetadataValue] | None = None)

Bases: ABC

A base class for types that represent one or more 2-d image-like arrays with the same pixel grid and sky projection.

Parameters

metadata

Arbitrary flexible metadata to associate with the image.

Attributes Summary

absolute	A proxy object for slicing a generalized image using absolute pixel coordinates.
astropy_wcs	An Astropy WCS for this image's pixel array.
bbox	Bounding box for the image (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).
sky_projection	The projection that maps this image's 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 and metadata.
read(path, **kwargs)	Read an instance of this class from a file.
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

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

Bounding box for the image (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.

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.

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

sky_projection

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

Notes

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

yx0

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

Methods Documentation

bbox_from_sky_circle(center: SkyCoord, radius: Angle, clip: bool = False) → Box

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

Parameters

center

The center of the circle, as a scalar astropy.coordinates.SkyCoord in any frame.

radius

Radius of the circle, as a scalar astropy.coordinates.Angle.

clip

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

Box

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

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.

abstract copy() → Self

Deep-copy the image and metadata.

Attached immutable objects (like SkyProjection instances) are not copied.

classmethod read(path: str | ParseResult | ResourcePath | Path, **kwargs: Any) → Self

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

File to read; convertible to lsst.resources.ResourcePath.

**kwargs

Forwarded to read_archive (e.g. bbox to read a subimage).

write(path: str, **kwargs: Any) → None

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

Destination file path. Must not already exist.

**kwargs

Forwarded to write_archive (e.g. compression_options and compression_seed for FITS).