Template Class Transform

Inheritance Relationships

Base Types

Class Documentation

template<class FromEndpoint, class ToEndpoint>
class Transform : public lsst::afw::table::io::PersistableFacade<Transform<FromEndpoint, ToEndpoint>>, public lsst::afw::table::io::Persistable

Transform LSST spatial data, such as lsst::geom::Point2D and lsst::geom::SpherePoint, using an AST mapping.

This class contains two Endpoints, to specify the “from” and “to” LSST data type, and an ast::Mapping to specify the transformation.

Depending on the ast::FrameSet or ast::Mapping used to define it, a Transform may provide either a forward transform, an inverse transform, or both. In particular, the inverse of a forward-only transform is an inverse-only transform. The hasForward and hasInverse methods can be used to check which transforms are available.

Unless otherwise stated, all constructors and methods may throw std::runtime_error to indicate internal errors within AST.

Transforms are always immutable.

Note

You gain some safety by constructing a Transform from an ast::FrameSet, since the base and current frames in the FrameSet can be checked against by the appropriate endpoint.

Note

”In place” versions of applyForward and applyInverse are not available because data must be copied when converting from LSST data types to the type used by astshim, so it didn’t seem worth the bother.

Public Types

template<>
using FromArray = typename FromEndpoint::Array
template<>
using FromPoint = typename FromEndpoint::Point
template<>
using ToArray = typename ToEndpoint::Array
template<>
using ToPoint = typename ToEndpoint::Point

Public Functions

Transform(Transform const&)
Transform(Transform&&)
Transform &operator=(Transform const&)
Transform &operator=(Transform&&)
~Transform()
Transform(ast::Mapping const &mapping, bool simplify = true)

Construct a Transform from a deep copy of an ast::Mapping

Parameters

  • [in] mapping: ast::Mapping describing the desired transformation

  • [in] simplify: Simplify the mapping? This combines component mappings where it is possible to do so without affecting accuracy.

Transform(ast::FrameSet const &frameSet, bool simplify = true)

Construct a Transform from a deep copy of a ast::FrameSet

The result transforms from the “base” frame to the “current” frame of the provided FrameSet. The “from” endpoint is used to normalize the “base” frame and the “to” endpoint is used to normalize the “current” frame.

This is pickier than the constructor that takes an ast::Mapping in that:

  • SpherePointEndpoint must be associated with an ast::SkyFrame and the SkyFrame axes are transposed, if necessary, to give the standard order: longitude, latitude.

  • Point2Endpoint must be associated with an ast::Frame (not a subclass), because Frame is the only kind of Frame that is sure to be Cartesian.

Parameters

  • [in] frameSet: ast::FrameSet describing the desired transformation in the usual way: from “base” frame to “current” frame

  • [in] simplify: Simplify the mapping? This combines component mappings where it is possible to do so without affecting accuracy.

bool hasForward() const

Test if this method has a forward transform.

Provides basic exception safety.

bool hasInverse() const

Test if this method has an inverse transform.

Provides basic exception safety.

FromEndpoint getFromEndpoint() const

Get the “from” endpoint

std::shared_ptr<const ast::Mapping> getMapping() const

Get the contained mapping

ToEndpoint getToEndpoint() const

Get the “to” endpoint

ToPoint applyForward(FromPoint const &point) const

Transform one point in the forward direction (“from” to “to”)

ToArray applyForward(FromArray const &array) const

Transform an array of points in the forward direction (“from” to “to”)

The first dimension of the array must match the number of input axes, and the data order is values for the first axis, then values for the next axis, and so on, e.g. for 2 axes: x0, x1, x2, …, y0, y1, y2…

FromPoint applyInverse(ToPoint const &point) const

Transform one point in the inverse direction (“to” to “from”)

FromArray applyInverse(ToArray const &array) const

Transform an array of points in the inverse direction (“to” to “from”)

The first dimension of the array must match the number of output axes, and the data order is values for the first axis, then values for the next axis, and so on, e.g. for 2 axes: x0, x1, x2, …, y0, y1, y2…

std::shared_ptr<Transform<ToEndpoint, FromEndpoint>> inverted() const

The inverse of this Transform.

Provides basic exception safety.

Return

a Transform whose applyForward is equivalent to this Transform’s applyInverse, and vice versa.

Eigen::MatrixXd getJacobian(FromPoint const &x) const

The Jacobian matrix of this Transform.

Radians are used for each axis of an SpherePointEndpoint.

The matrix is defined only if this object has a forward transform.

Provides basic exception safety.

Return

a matrix J with getToEndpoint().getNAxes() rows and getFromEndpoint().getNAxes() columns. J(i,j) shall be the rate of change of the ith output coordinate with respect to the jth input coordinate, or NaN if the derivative cannot be calculated.

Parameters

  • x: the position at which the Jacobian shall be evaluated

Note

The derivatives may be estimated by sampling and interpolating this Transform in the neighborhood of x. If the implementation requires interpolation, computation of the Jacobian may require hundreds of evaluations of applyForward.

template<class NextToEndpoint>
std::shared_ptr<Transform<FromEndpoint, NextToEndpoint>> then(Transform<ToEndpoint, NextToEndpoint> const &next, bool simplify = true) const

Concatenate two Transforms.

More than two Transforms can be combined in series. For example: 

auto pixelsToSky = pixelsToFp.then(fpToField)->then(fieldToSky);
Return

a Transform that first applies this transform to its input, and then next to the result. Its inverse shall first apply the inverse of next, and then the inverse of this transform.

Template Parameters

  • NextToEndpoint: the “to” Endpoint of next

Parameters

  • next: the Transform to apply after this one

  • simplify: if true then produce a transform containing a single simplified mapping with no intermediate frames.

Exceptions

  • pex::exceptions::InvalidParameterError: Thrown if getToEndpoint() and next.getFromEndpoint() do not have the same number of axes. Provides basic exception safety.

void writeStream(std::ostream &os) const

Serialize this Transform to an output stream

Version 1 format is as follows:

  • The version number (an integer)

  • A space

  • The short class name, as obtained from getShortClassName

  • A space

  • The contained ast::FrameSet written using FrameSet.show(os, false)

Parameters

  • [out] os: outpu stream to which to serialize this Transform

std::string writeString() const

Serialize this Transform to a string, using the same format as writeStream.

bool isPersistable() const

Whether the Transform is persistable via afw::table::io (always true).

Public Static Functions

static std::string getShortClassName()

Return a short version of the class name with no punctuation

Used as the Python class name and for persistence as a string

Returns “Transform” + fromEndpoint.getClassPrefix() + “To” + toEndpoint.getClassPrefix(), for example “TransformPoint2ToSpherePoint” or “TransformPoint2ToGeneric”.

static std::shared_ptr<Transform<FromEndpoint, ToEndpoint>> readStream(std::istream &is)

Deserialize a Transform of this type from an input stream

Parameters

  • [in] is: input stream from which to deserialize this Transform

static std::shared_ptr<Transform<FromEndpoint, ToEndpoint>> readString(std::string &str)

Deserialize a Transform of this type from a string, using the same format as readStream.

Protected Functions

Transform(std::shared_ptr<ast::Mapping> mapping)

Construct a Transform from a shared pointer to an ast::Mapping

std::string getPersistenceName() const

Return the unique name used to persist this object and look up its factory.

Must be less than ArchiveIndexSchema::MAX_NAME_LENGTH characters.

std::string getPythonModule() const

Return the fully-qualified Python module that should be imported to guarantee that its factory is registered.

Must be less than ArchiveIndexSchema::MAX_MODULE_LENGTH characters.

Will be ignored if empty.

void write(OutputArchiveHandle &handle) const

Write the object to one or more catalogs.

The handle object passed to this function provides an interface for adding new catalogs and adding nested objects to the same archive (while checking for duplicates). See OutputArchiveHandle for more information.