Transform#

final class lsst.images.Transform(in_frame: I, out_frame: O, ast_mapping: Mapping, in_bounds: Bounds | None = None, out_bounds: Bounds | None = None, components: Iterable[Transform[Any, Any]] = ())#

Bases: Generic

A transform that maps two coordinate frames.

Notes#

The Transform class constructor is considered a private implementation detail. Instead of using this, various factory methods are available:

from_fits_wcs constructs a transform from a FITS WCS, as represented astropy.wcs.WCS;
then composes two transforms;
identity constructs a trivial transform that does nothing;
inverted returns the inverse of a transform;
from_legacy converts an lsst.afw.geom.Transform instance.

When applied to celestial coordinate systems, x=ra and y=dec. Projection provides a more natural interface for pixel-to-sky transforms.

Transform is conceptually immutable (the internal AST Mapping should never be modified in-place after construction), and hence does not need to be copied when any object that holds it is copied.

Attributes Summary

`in_bounds`	The region that bounds valid input points (`Bounds` \| `None`).
`in_frame`	Coordinate frame for input points.
`out_bounds`	The region that bounds valid output points (`Bounds` \| `None`).
`out_frame`	Coordinate frame for output points.

Methods Summary

`apply_forward`(*, x, y)	Apply the forward transform to one or more points.
`apply_forward_q`(*, x, y)	Apply the forward transform to one or more unit-aware points.
`apply_inverse`(*, x, y)	Apply the inverse transform to one or more points.
`apply_inverse_q`(*, x, y)	Apply the inverse transform to one or more unit-aware points.
`as_fits_wcs`(bbox)	Return a FITS WCS representation of this transform, if possible.
`as_projection`()	Return a `Projection` view of this transform.
`decompose`()	Deconstruct a composed transform into its constituent parts.
`deserialize`(model, archive)	Deserialize a transform from an archive.
`from_fits_wcs`(fits_wcs, in_frame, out_frame)	Construct a transform from a FITS WCS.
`from_legacy`(legacy, in_frame, out_frame[, ...])	Construct a transform from a legacy `lsst.afw.geom.Transform`.
`identity`(frame)	Construct a trivial transform that maps a frame to itelf.
`inverted`()	Return the inverse of this transform.
`serialize`(archive, *[, use_frame_sets])	Serialize a transform to an archive.
`show`([simplified, comments])	Return the AST native representation of the transform.
`then`(next[, remember_components])	Compose two transforms into another.
`to_legacy`()	Convert to a legacy `lsst.afw.geom.TransformPoint2ToPoint2` instance.

Attributes Documentation

in_bounds#: The region that bounds valid input points (Bounds | None).

in_frame#: Coordinate frame for input points.

out_bounds#: The region that bounds valid output points (Bounds | None).

out_frame#: Coordinate frame for output points.

Methods Documentation

apply_forward(*, x: T, y: T) → XY#

Apply the forward transform to one or more points.

Parameters#

xnumpy.ndarray | float: x values of the points to transform.
ynumpy.ndarray | float: y values of the points to transform.

Returns#

XY [numpy.ndarray | float]: The transformed point or points.

apply_forward_q(*, x: Quantity, y: Quantity) → XY[Quantity]#

Apply the forward transform to one or more unit-aware points.

Parameters#

x: x values of the points to transform.
y: y values of the points to transform.

Returns#

XY [astropy.units.Quantity]: The transformed point or points.

apply_inverse(*, x: T, y: T) → XY#

Apply the inverse transform to one or more points.

Parameters#

xnumpy.ndarray | float: x values of the points to transform.
ynumpy.ndarray | float: y values of the points to transform.

Returns#

XY [numpy.ndarray | float]: The transformed point or points.

apply_inverse_q(*, x: Quantity, y: Quantity) → XY[Quantity]#

Apply the inverse transform to one or more unit-aware points.

Parameters#

x: x values of the points to transform.
y: y values of the points to transform.

Returns#

XY [astropy.units.Quantity]: The transformed point or points.

as_fits_wcs(bbox: Box) → WCS | None#

Return a FITS WCS representation of this transform, if possible.

Parameters#

bbox: Bounding box of the array the FITS WCS will describe. This transform object is assumed to work on the same coordinate system in which bbox is defined, while the FITS WCS will consider the first row and column in that box to be (0, 0) (in Astropy interfaces) or (1, 1) (in the FITS representation itself).

Notes#

This method assumes the transform maps pixel coordinates to world coordinates.

Not all transforms can be represented exactly; when a FITS represention is not possible, None is returned. When the returned WCS is not None, it will have the same functional form, but it may not evaluate identically due to small implementation differences in the order of floating-point operations.

as_projection() → Projection[I]#

Return a Projection view of this transform.

This is only valid when out_frame is ICRS.

decompose() → list[Transform[Any, Any]]#: Deconstruct a composed transform into its constituent parts.

Notes#

Most transforms will just return a single-element list holding self. Identity transform will return an empty list, and transforms composed with then will return the original transforms. Transforms constructed by FrameSet may or may not be decomposable.

static deserialize(model: TransformSerializationModel[TypeVar], archive: InputArchive) → Transform[Any, Any]#

Deserialize a transform from an archive.

Parameters#

model: Seralized form of the transform.
archive: Archive to read from.

static from_fits_wcs(fits_wcs: WCS, in_frame: I, out_frame: O, in_bounds: Bounds | None = None, out_bounds: Bounds | None = None, x0: int = 0, y0: int = 0) → Transform[I, O]#

Construct a transform from a FITS WCS.

Parameters#

fits_wcs: FITS WCS to convert.
in_frame: Coordinate frame for input points to the forward transform.
out_frame: Coordinate frame for output points from the forward transform.
in_bounds: The region that bounds valid input points.
out_bounds: The region that bounds valid output points.
x0: Logical coordinate of the first column in the array this WCS relates to world coordinates.
y0: Logical coordinate of the first column in the array this WCS relates to world coordinates.

Notes#

The x0 and y0 parameters reflect the fact that for FITS, the first row and column are always labeled (1, 1), while in Astropy and most other Python libraries, they are (0, 0). The types in this package (e.g. Image, Mask) allow them to be any pair of integers.

Parameters#

legacylsst.afw.geom.Transform: Legacy transform object.
in_frame: Coordinate frame for input points to the forward transform.
out_frame: Coordinate frame for output points from the forward transform.
in_bounds: The region that bounds valid input points.
out_bounds: The region that bounds valid output points.

static identity(frame: I) → Transform[I, I]#

Construct a trivial transform that maps a frame to itelf.

Parameters#

frame: Frame used for both input and output points.

inverted() → Transform[O, I]#: Return the inverse of this transform.

serialize(archive: OutputArchive, *, use_frame_sets: bool = False) → TransformSerializationModel[TypeVar]#

Serialize a transform to an archive.

Parameters#

archive: Archive to serialize to.
use_frame_sets: If True, decompose the transform and try to reference component mappings that were already serialized into a FrameSet in the archive. Note that if multiple transforms exist between a pair of frames (e.g. a Projection and its FITS approximation), this may cause the wrong one to be saved. When this option is used, the frame set must be saved before the transform, and it must be deserialized before the transform as well.

Returns#

TransformSerializationModel: Serialized form of the transform.

show(simplified: bool = False, comments: bool = False) → str#

Return the AST native representation of the transform.

Parameters#

simplified: Whether to ask AST to simplify the mapping before showing it. This will make it much more likely that two equivalent transforms have the same show result. If the internal mapping is actually a frame set (as needed to round-trip legacy lsst.afw.geom.SkyWcs objects), this will also just show the mapping with no frame set information.
comments: Whether to include descriptive comments.

then(next: Transform[O, F], remember_components: bool = True) → Transform[I, F]#

Compose two transforms into another.

Parameters#

next: Another transform to apply after self.
remember_components: If True, the returned composed transform will remember self and other so they can be returned by decompose.

to_legacy() → LegacyTransform#: Convert to a legacy lsst.afw.geom.TransformPoint2ToPoint2 instance.

Transform#

Notes#

Parameters#

Returns#

Parameters#

Returns#

Parameters#

Returns#

Parameters#

Returns#

Parameters#

Notes#

Notes#

Parameters#

Parameters#

Notes#

See Also#

Parameters#

Parameters#

Parameters#

Returns#

Parameters#

Parameters#