Transform#

final class lsst.images.Transform(in_frame, out_frame, ast_mapping, in_bounds=None, out_bounds=None, components=())#

Bases: Generic

A transform that maps two coordinate frames.

Parameters:

in_frame (TypeVar(I, bound= Frame)) – Input coordinate frame.
out_frame (TypeVar(O, bound= Frame)) – Output coordinate frame.
ast_mapping (Mapping) – AST mapping that implements the transform.
in_bounds (Bounds | None, default: None) – Bounds of the input frame, defaulting to the input frame’s bounding box.
out_bounds (Bounds | None, default: None) – Bounds of the output frame, defaulting to the output frame’s bounding box.
components (Iterable[Transform[Any, Any]], default: ()) – Component transforms that this transform was composed from.

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;
affine contructs an affine transform from a 2x2 or 3x3 matrix;
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. SkyProjection 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

`affine`(in_frame, out_frame, matrix)	Construct an affine transform from a matrix.
`apply_forward`([point, x, y])	Apply the forward transform to one or more points.
`apply_forward_q`([point, x, y])	Apply the forward transform to one or more unit-aware points.
`apply_inverse`([point, x, y])	Apply the inverse transform to one or more points.
`apply_inverse_q`([point, 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.
`decompose`()	Deconstruct a composed transform into its constituent parts.
`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

static affine(in_frame, out_frame, matrix)#

Construct an affine transform from a matrix.

Parameters:

in_frame (TypeVar(I, bound= Frame)) – Coordinate frame for input points to the forward transform.
out_frame (TypeVar(O, bound= Frame)) – Coordinate frame for output points from the forward transform.
matrix (ndarray) – Matrix of coefficients, either a 2x2 linear transform or a 3x3 augmented affine transform, with a shift embedded in the third column and [0, 0, 1] the third row.

Return type:

Transform[TypeVar(I, bound= Frame), TypeVar(O, bound= Frame)]

apply_forward(point=None, /, *, x=None, y=None)#

Apply the forward transform to one or more points.

Parameters:

point (Union[XY[Any], YX[Any], None], default: None) – An XY or YX coordinate pair to transform. Mutually exclusive with x and y.
x (float | array-like) – x values of the points to transform, as a scalar or any array-like. Results are broadcast against y. Mutually exclusive with point.
y (float | array-like) – y values of the points to transform, as a scalar or any array-like. Results are broadcast against x. Mutually exclusive with point.

Returns:

The transformed point or points. A scalar input pair returns XY of float; array-like inputs return XY of numpy.ndarray with the broadcast shape of x and y.

Return type:

XY [float | numpy.ndarray]

apply_forward_q(point=None, /, *, x=None, y=None)#

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

Parameters:

point (Union[XY[Quantity], YX[Quantity], None], default: None) – An XY or YX coordinate pair of Quantity to transform. Mutually exclusive with x and y.
x (Any, default: None) – x values of the points to transform. Mutually exclusive with point.
y (Any, default: None) – y values of the points to transform. Mutually exclusive with point.

Returns:

The transformed point or points.

Return type:

XY [astropy.units.Quantity]

apply_inverse(point=None, /, *, x=None, y=None)#

Apply the inverse transform to one or more points.

Parameters:

point (Union[XY[Any], YX[Any], None], default: None) – An XY or YX coordinate pair to transform. Mutually exclusive with x and y.
x (float | array-like) – x values of the points to transform, as a scalar or any array-like. Results are broadcast against y. Mutually exclusive with point.
y (float | array-like) – y values of the points to transform, as a scalar or any array-like. Results are broadcast against x. Mutually exclusive with point.

Returns:

The transformed point or points. A scalar input pair returns XY of float; array-like inputs return XY of numpy.ndarray with the broadcast shape of x and y.

Return type:

XY [float | numpy.ndarray]

apply_inverse_q(point=None, /, *, x=None, y=None)#

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

Parameters:

point (Union[XY[Quantity], YX[Quantity], None], default: None) – An XY or YX coordinate pair of Quantity to transform. Mutually exclusive with x and y.
x (Any, default: None) – x values of the points to transform. Mutually exclusive with point.
y (Any, default: None) – y values of the points to transform. Mutually exclusive with point.

Returns:

The transformed point or points.

Return type:

XY [astropy.units.Quantity]

as_fits_wcs(bbox)#

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

Parameters:: bbox (Box) – 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).
Return type:: WCS | None

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.

decompose()#

Deconstruct a composed transform into its constituent parts.

Return type:: list[Transform[Any, Any]]

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 from_fits_wcs(fits_wcs, in_frame, out_frame, in_bounds=None, out_bounds=None, x0=0, y0=0)#

Construct a transform from a FITS WCS.

Parameters:

fits_wcs (WCS) – FITS WCS to convert.
in_frame (TypeVar(I, bound= Frame)) – Coordinate frame for input points to the forward transform.
out_frame (TypeVar(O, bound= Frame)) – Coordinate frame for output points from the forward transform.
in_bounds (Bounds | None, default: None) – The region that bounds valid input points.
out_bounds (Bounds | None, default: None) – The region that bounds valid output points.
x0 (int, default: 0) – Logical coordinate of the first column in the array this WCS relates to world coordinates.
y0 (int, default: 0) – Logical coordinate of the first column in the array this WCS relates to world coordinates.

Return type:

Transform[TypeVar(I, bound= Frame), TypeVar(O, bound= Frame)]

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.