GeneralizedImage

class lsst.images.GeneralizedImage(metadata=None)

Bases: DescribableMixin, 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 (Mapping[str, TypeAliasType] | MetadataView | None, default: None) – Arbitrary flexible metadata to associate with the image. A dict, or the native metadata of a MetadataView, is shared by reference rather than copied, unlike assignment to metadata; any other mapping is copied.

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	Flexible metadata associated with the image (MetadataView).
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.
describe(*[, brief, detail, exclude])	Return a Report describing this object.
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

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.

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

abstract copy()

Deep-copy the image and metadata.

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

Return type:

Self

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

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

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