Image#

final class lsst.images.Image(array_or_fill=0, /, *, bbox=None, yx0=None, shape=None, dtype=None, unit=None, sky_projection=None, metadata=None)#

Bases: GeneralizedImage

A 2-d array that may be augmented with units and a nonzero origin.

Parameters:

array_or_fill (ndarray | int | float, default: 0) – Array or fill value for the image. If a fill value, bbox or shape must be provided.
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.
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.
dtype (TypeAliasType | None, default: None) – Pixel data type override.
unit (UnitBase | None, default: None) – Units for the image’s pixel values.
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.

Notes

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

Indexed assignment to a subimage requires consistency between the coordinate systems and units of both operands, but it will automatically select a subimage of the right-hand side and convert compatible units when possible. In other words:

a[box] = b

is a shortcut for

a[box].quantity = b[box].quantity

An ellipsis (...) can be used instead of a Box to assign to the full image.

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`	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`).
`quantity`	The low-level array with units (`astropy.units.Quantity`).
`sky_projection`	The projection that maps this image's pixel grid to the sky (`SkyProjection` \| `None`).
`unit`	Units for the image's pixel values (`astropy.units.Unit` or `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.
`from_hdu_list`(hdu_list, *[, fits_wcs_frame])	Reconstruct an `Image` from a cut-down `lsst.images` HDU list.
`from_legacy`(legacy[, unit, sky_projection])	Convert from an `lsst.afw.image.Image` instance.
`read`(path, **kwargs)	Read an instance of this class from a file.
`read_legacy`(uri, *[, preserve_quantization, ...])	Read a FITS file written by `lsst.afw.image.Image.writeFits`.
`serialize`(archive, *[, update_header, ...])	Serialize the image to an output archive.
`to_legacy`(*[, copy])	Convert to an `lsst.afw.image.Image` instance.
`view`(*[, unit, sky_projection, yx0])	Make a view of the image, 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#

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

quantity#

The low-level array with units (astropy.units.Quantity).

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

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.

unit#: Units for the image’s pixel values (astropy.units.Unit or 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 and metadata.

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

Return type:: Image

classmethod from_hdu_list(hdu_list, *, fits_wcs_frame=GeneralFrame(unit=Unit('pix'), frame_type='GENERAL'))#

Reconstruct an Image from a cut-down lsst.images HDU list.

This reads only the first two HDUs (the primary HDU and the image HDU), as written for the image-only cut-outs produced by dax_images_cutout: a real lsst.images file with its JSON-tree, index, and any nested-archive HDUs dropped.

Parameters:

hdu_list (HDUList) – HDU list whose first HDU is the primary header and whose second HDU holds the image pixels.
fits_wcs_frame (Frame | None, default: GeneralFrame(unit=Unit("pix"), frame_type='GENERAL')) – Pixel-grid Frame for the SkyProjection reconstructed from the image HDU’s FITS WCS. Defaults to a plain pixel frame; pass None to skip attaching a projection.

Returns:

The reconstructed image, ready to be re-serialized as a normal lsst.images file.

Return type:

Image

Notes

The headers of the consumed HDUs are modified in place (WCS and other interpreted cards are stripped), as in read_legacy.

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

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

Parameters:

legacy (TypeAliasType) – An lsst.afw.image.Image instance that will share pixel data with the returned object.
unit (UnitBase | None, default: None) – Units of the image.
sky_projection (Optional[SkyProjection[Any]], default: None) – Projection from pixels to xky.

Return type:

Image

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, *, preserve_quantization=False, ext=1, fits_wcs_frame=None)#

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

Parameters:

uri (str | ParseResult | ResourcePath | Path) – URI or file name.
preserve_quantization (bool, default: False) – If True, ensure that writing the image back out again will exactly preserve quantization-compressed pixel values. This causes the arrays to be marked as read-only and stores the original binary table data for those planes in memory. If the Image is copied, the precompressed pixel values are not transferred to the copy.
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 image has a FITS WCS, attach a SkyProjection to the returned image by converting that WCS.

Return type:

Image

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

Serialize the image 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 0x7f27576196c0>) – A callback that will be given the FITS header for the HDU containing this image in order to add keys to it. This callback may be provided but will not be called if the output format is not FITS.
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. 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:

ImageSerializationModel[TypeVar]

to_legacy(*, copy=None)#

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

Parameters:: copy (bool | None, default: None) – If True, always copy the pixel data. If False, return a view, and raise TypeError if the pixel data is read-only (this is not supported by afw). If None, only copy if the pixel data is read-only.
Return type:: TypeAliasType

view(*, unit=Ellipsis, sky_projection=Ellipsis, yx0=Ellipsis)#

Make a view of the image, with optional updates.

Parameters:

unit (UnitBase | None | EllipsisType, default: Ellipsis) – Units for the view’s pixel values. Defaults to the units of this image.
sky_projection (SkyProjection | None | EllipsisType, default: Ellipsis) – Projection that maps the pixel grid to the sky. Defaults to the projection of this image.
yx0 (Sequence[int] | EllipsisType, default: Ellipsis) – Logical coordinates of the first pixel, ordered y, x. Defaults to the start of this image’s bounding box.

Return type:

Image

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