VisitImage#

class lsst.images.VisitImage(image: Image, *, mask: Mask | None = None, variance: Image | None = None, mask_schema: MaskSchema | None = None, sky_projection: SkyProjection[DetectorFrame] | None = None, bounds: Bounds | None = None, obs_info: ObservationInfo | None = None, summary_stats: ObservationSummaryStats | None = None, photometric_scaling: Field | None = None, psf: PointSpreadFunction | ArchiveReadError, detector: Detector, aperture_corrections: ApertureCorrectionMap | None = None, backgrounds: BackgroundMap | None = None, band: str, metadata: dict[str, MetadataValue] | None = None)#

Bases: MaskedImage

A calibrated single-visit image.

Parameters#

image: The main image plane. If this has a SkyProjection, it will be used for all planes unless a sky_projection is passed separately.
mask: A bitmask image that annotates the main image plane. Must have the same bounding box as image if provided. Any attached sky_projection is replaced (possibly by None).
variance: The per-pixel uncertainty of the main image as an image of variance values. Must have the same bounding box as image if provided, and its units must be the square of image.unit or None. Values default to 1.0. Any attached sky_projection is replaced (possibly by None).
mask_schema: Schema for the mask plane. Must be provided if and only if mask is not provided.
sky_projection: Projection that maps the pixel grid to the sky. Can only be None if a sky_projection is already attached to image.
bounds: The region where this image’s pixels and other properties are valid. If not provided, the bounding box of the image is used. Other components (psf, sky_projection, aperture_corrections, etc.) are assumed to have their own bounds which may or may not be the same as the image bounds. If bounds extends beyond the image bounding box, the intersection between bounds and the image bounding box is used instead.
obs_info: General information about this visit in standardized form.
summary_stats: Summary statistics associated with this visit. Initialized to default values if not provided.
photometric_scaling: Field that can be used to multiply a post-ISR image units to yield calibrated image units. This may be a scaling that was already applied (so dividing by it will recover the post-ISR units) or a scaling that has not been applied, depending on image.unit.
psf: Point-spread function model for this image, or an exception explaining why it could not be read (to be raised if the PSF is requested later).
detector: Geometry and electronic information for the detector attached to this image.
aperture_correctionsdict [str, BaseField]: Mapping from photometry algorithm name to the aperture correction for that algorithm.
backgrounds: Background models associated with this image.
band: Name of the passband the image was observed with (this is a shorter, less specific version of obs_info.physical_filter).
metadata: Arbitrary flexible metadata to associate with the image.

Attributes Summary

`absolute`	A proxy object for slicing a generalized image using absolute pixel coordinates.
`aperture_corrections`	A mapping from photometry algorithm name to the aperture correction field for that algorithm (`dict` [`str`, `BaseField`]).
`astropy_wcs`	An Astropy WCS for the pixel arrays (`SkyProjectionAstropyView`).
`backgrounds`	A mapping of backgrounds associated with this image (`BackgroundMap`).
`band`	Short name of the bandpass filter (`str`).
`bbox`	The bounding box shared by all three image planes (`Box`).
`bounds`	The region where pixels are valid (`Bounds`).
`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`)
`detector`	Geometry and electronic information about the detector (`cameras.Detector`).
`fits_wcs`	An Astropy FITS WCS for this image's pixel array.
`image`	The main image plane (`Image`).
`local`	A proxy object for slicing a generalized image using "local" or "array" pixel coordinates.
`mask`	The mask plane (`Mask`).
`metadata`	Arbitrary flexible metadata associated with the image (`dict`).
`obs_info`	General information about this observation in standard form.
`photometric_scaling`	Field that multiplies a post-ISR image to yield the calibrated image (~`fields.BaseField`).
`physical_filter`	Full name of the physical bandpass filter (`str`).
`psf`	The point-spread function model for this image (`psfs.PointSpreadFunction`).
`sky_projection`	The projection that maps the pixel grid to the sky (`SkyProjection` [`DetectorFrame`]).
`summary_stats`	Optional summary statistics for this observation (`ObservationSummaryStats`).
`unit`	The units of the image plane (`astropy.units.Unit`).
`variance`	The variance plane (`Image`).
`yx0`	The coordinates of the first pixel in the array (`YX` [`int`]).

Methods Summary

`convert_unit`([unit, copy, copy_detector])	Return an equivalent image with different pixel units.
`copy`(*[, copy_detector])	Deep-copy the visit image.
`from_hdu_list`(hdu_list, *[, fits_wcs_frame])	Reconstruct a `MaskedImage` from a cut-down `lsst.images` FITS HDU list.
`from_legacy`(legacy, *[, unit, plane_map, ...])	Convert from an `lsst.afw.image.Exposure` instance.
`read`(path, **kwargs)	Read an instance of this class from a file.
`read_legacy`(filename, *[, ...])	Read a FITS file written by `lsst.afw.image.Exposure.writeFits`.
`serialize`(archive)	Serialize the masked image to an output archive.
`to_legacy`(*[, copy, plane_map])	Convert to an `lsst.afw.image.Exposure` instance.
`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

aperture_corrections#: A mapping from photometry algorithm name to the aperture correction field for that algorithm (dict [str, BaseField]).

astropy_wcs#: An Astropy WCS for the pixel arrays (SkyProjectionAstropyView).

Notes#

As expected for Astropy WCS objects, this defines pixel coordinates such that the first row and column in the 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).

backgrounds#: A mapping of backgrounds associated with this image (BackgroundMap).

band#: Short name of the bandpass filter (str).

bbox#: The bounding box shared by all three image planes (Box).

bounds#: The region where pixels are valid (Bounds).

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)

detector#: Geometry and electronic information about the detector (cameras.Detector).

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.

image#: The main image plane (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

mask#

The mask plane (Mask).

Assigning a new Mask (for example one returned by add_planes) replaces the mask plane. The new mask must share this image’s bounding box; its sky projection is replaced with the image’s.

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

obs_info#: General information about this observation in standard form. (ObservationInfo).

photometric_scaling#: Field that multiplies a post-ISR image to yield the calibrated image (~`fields.BaseField`).

physical_filter#: Full name of the physical bandpass filter (str).

psf#: The point-spread function model for this image (psfs.PointSpreadFunction).

sky_projection#: The projection that maps the pixel grid to the sky (SkyProjection [DetectorFrame]).

summary_stats#: Optional summary statistics for this observation (ObservationSummaryStats).

unit#: The units of the image plane (astropy.units.Unit).

variance#: The variance plane (Image).

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

Methods Documentation

convert_unit(unit: UnitBase = Unit('nJy'), copy: Literal['as-needed'] | bool = True, copy_detector: bool = False) → VisitImage#

Return an equivalent image with different pixel units.

Parameters#

unit

The unit to transform to. This may be any of the following:

any unit directly relatable to the current units via Astropy;
any unit relatable to the product of the current units with the photometric_scaling (i.e. if the current image is in instrumental units but we know how to calibrate them)
any unit relatable to the quotient of the current units with the photometric_scaling (i.e. if the current image is in calibrated units and we want to revert back to instrumental units).

copy

Whether to copy the images and other components. If True, all components that aren’t controlled by some other argument will always be deep-copied. If False, the operation will fail if the image is not already in the right units. If as-needed, only the image and variance will be copied, and only if they are not already in the right units.

copy_detector

Whether to deep-copy the detector attribute.

Returns#

VisitImage: An image with the given units.

copy(*, copy_detector: bool = False) → VisitImage#

Deep-copy the visit image.

Parameters#

copy_detector: Whether to deep-copy the detector attribute.

classmethod from_hdu_list(hdu_list: HDUList, *, fits_wcs_frame: Frame | None = GeneralFrame(unit=Unit('pix'), frame_type='GENERAL')) → MaskedImage#

Reconstruct a MaskedImage from a cut-down lsst.images FITS HDU list.

This assumes the PRIMARY, IMAGE, MASK, and VARIANCE HDUs written for the masked-image cut-outs produced by dax_images_cutout: a real lsst.images file with its JSON-tree, index, and any nested-archive HDUs dropped. The reconstructed object can be re-serialized as a normal lsst.images file (with schema and index) so it can be read with the full lsst.images infrastructure.

Parameters#

hdu_list: HDU list with IMAGE, MASK, and VARIANCE extensions and a primary HDU.
fits_wcs_frame: Pixel-grid Frame for the SkyProjection reconstructed from the FITS WCS. Defaults to a plain pixel frame; pass None to skip attaching a projection.

Returns#

MaskedImage: The reconstructed masked image.

Raises#

ValueError: Raised if the MASK HDU has neither MSKN nor MP_ mask- plane cards, since the mask schema cannot then be reconstructed, or if hdu_list contains more than one MASK HDU (multiple MASK extensions, distinguished by EXTVER, are not handled here and would otherwise be silently dropped).

Notes#

Both mask-plane conventions are supported: the self-describing MSKN/MSKM/MSKD cards written by lsst.images, and the legacy lsst.afw.image MP_* cards (as produced by dax_images_cutout from afw-written images). Legacy masks are mapped to a new schema with the same plane-guessing used by read_legacy.

Unlike read_legacy, the legacy MP_* mask-plane cards are kept (not stripped) for backwards compatibility, since this path reconstructs a file that may still be read by legacy tooling. They are re-indexed to the reshuffled schema so each MP_ bit matches the plane’s position in the written MSKN layout.

The headers of the HDUs in hdu_list are modified in place: the WCS and mask-schema cards interpreted here are stripped from the caller’s headers.

static from_legacy(legacy: LegacyExposure, *, unit: astropy.units.UnitBase | None = None, plane_map: Mapping[str, MaskPlane] | None = None, instrument: str | None = None, visit: int | None = None) → VisitImage#

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

Parameters#

legacy: An lsst.afw.image.Exposure instance that will share image and variance (but not mask) pixel data with the returned object.
unit: Units of the image. If not provided, the BUNIT metadata key will be used, if available.
plane_map: A mapping from legacy mask plane name to the new plane name and description. If None (default) get_legacy_visit_image_mask_planes is used.
instrument: Name of the instrument. Extracted from the metadata if not provided.
visit: ID of the visit. Extracted from the metadata if not provided.

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 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 (e.g. bbox to read a subimage).

static read_legacy(filename: str, *, preserve_quantization: bool = False, plane_map: Mapping[str, MaskPlane] | None = None, instrument: str | None = None, visit: int | None = None, component: Literal['bbox', 'image', 'mask', 'variance', 'sky_projection', 'psf', 'detector', 'photometric_scaling', 'obs_info', 'summary_stats', 'aperture_corrections'] | None = None) → Any#

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

Parameters#

filename: Full name of the file.
preserve_quantization: If True, ensure that writing the masked image back out again will exactly preserve quantization-compressed pixel values. This causes the image and variance plane arrays to be marked as read-only and stores the original binary table data for those planes in memory. If the MaskedImage is copied, the precompressed pixel values are not transferred to the copy.
plane_map: A mapping from legacy mask plane name to the new plane name and description. If None (default) get_legacy_visit_image_mask_planes is used.
instrument: Name of the instrument. Read from the primary header if not provided.
visit: ID of the visit. Read from the primary header if not provided.
component: A component to read instead of the full image.

serialize(archive: OutputArchive[Any]) → VisitImageSerializationModel#

Serialize the masked image to an output archive.

Parameters#

archive: Archive to write to.

to_legacy(*, copy: bool | None = None, plane_map: Mapping[str, MaskPlane] | None = None) → LegacyExposure#

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

Parameters#

copy: If True, always copy the image and variance 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. Mask pixel data is always copied.
plane_map: A mapping from legacy mask plane name to the new plane name and description. If None (default), get_legacy_visit_image_mask_planes is used.

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

Write this object to a file.

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

Parameters#

path: Destination file path. Must not already exist.
**kwargs: Forwarded to write (e.g. compression_options and compression_seed for FITS).

VisitImage#

Parameters#

Notes#

See Also#

Notes#

Notes#

Notes#

See Also#

Notes#

Parameters#

Returns#

Parameters#

Parameters#

Returns#

Raises#

Notes#

Parameters#

Parameters#

Parameters#

Parameters#

Parameters#

Parameters#