Transformation

The Transformation component provides the abstraction to handle coordinate transforms between conjugate planes, assuming Gaussian optics (i.e. diffractive effects are ignored and must be modeled separately). Under this approximation, transforms are just \(\mathbb R^2\to\mathbb R^2\) functions between coordinates.

Something as simple as a telescope with a given focal length can be modeled as a coordinate transform that multiplies the input coordinates by the inverse of the focal length. The following clases belong to the Transformation component:

class Transform

This is the abstract class from which all other coordinate transforms are derived. If instatiated directly, it represents the identity transform. Transforms accept tuples of the form \((x, y)\) or \(N\times2\) FloatArray arrays representing sets of \(N\) coordinates.

_forward(xy)

Protected method that computes the forward transform over the ARRAY_TYPE tuple xy and returns a \(1\times2\) FloatArray containing the transformed coordinates. Non-trivial derivations of Transform must override at least _forward and _backward.

_backward(xy)

Protected method that computes the backward transform over the ARRAY_TYPE tuple xy and returns a \(1\times2\) FloatArray containing the transformed coordinates. Non-trivial derivations of Transform must override at least _forward and _backward.

_forward_matrix(matrix)

Protected method that performs \(N\) forward coordinate transforms all at once over the coordinate list matrix in the form of a \(N\times2\) FloatArray and returns the transformed coordinate list as another \(N\times2\) FloatArray. If not overriden by the subclass, this method simply applies _forward along the \(N\) rows of matrix.

_backward_matrix(matrix)

Protected method that performs \(N\) backward coordinate transforms all at once over the coordinate list matrix in the form of a \(N\times2\) FloatArray and returns the transformed coordinate list as another \(N\times2\) FloatArray. If not overriden by the subclass, this method simply applies _backward along the \(N\) rows of matrix.

forward(xy=None, x=None, y=None)

Public method that performs a forward transform, accepting either two scalar coordinates x and y or a tuple / FloarArray of coordinates in xy. The method automatically determines whether to use _forward of _forward_matrix according to the arguments passed to it.

backward(xy=None, x=None, y=None)

Public method that performs a forward transform, accepting either two scalar coordinates x and y or a tuple / FloarArray of coordinates in xy. The method automatically determines whether to use _backward of _backward_matrix according to the arguments passed to it.

generate()

In case the transform is derived from a set of parameters with uncertainties (e.g. mechanical tolerances, misalignments, precission limits in measurements), this method is called during Monte Carlo testing to initialize the specific transform parameters by drawing a sample from each parameter distribution.

reset()

In case the transform holds a state (e.g. energy consumed during operation, time variation of the parameter distributions, etc), this method sets any internal state variables to their initial values.

class CompositeTransform

The CompositeTransform represents a chain of transforms \(T_{1},T_{2}, ... ,T_{n}\) that are applied sequentially according to the transform direction. If \(T_1\) represents the coordinate transform between the object plane and the rest of the chain and \(T_n\) the transform between the rest of the chain and the object plane, the forward composite transform is simply \(T_{cf}=T_{nf}\circ \dots \circ T_{2f}\circ T_{1f}\). The backward transform will be \(T_{cb}=T_{cf}^{-1}=(T_{nf}\circ \dots \circ T_{2f}\circ T_{1f})^{-1}=T_{1f}^{-1}\circ T_{2f}^{-1}\circ \dots \circ T_{nf}^{-1}=T_{1b}\circ T_{2b}\circ \dots \circ T_{nb}\).

push_front(T)

Puts the transform T in the frontmost position of the transform chain, becoming the first transform to be computed in the forward direction.

push_front(T)

Puts the transform T in the backmost position of the transform chain, becoming the first transform to be computed in the backward direction.

class TransformTester(T)

As new transforms are expected to be implemented in the future, a tester class TransformTester with transform debugging functions is provided. TransformTester is instantiated from a given transform \(T\) and can generate a set of coordinates (the so-called departure coordinates), either from a regular grid or from a set of stars in the sky up to certain visual magnitude. Then, a copy of these coordinates (the current coordinates) can be transformed multiple times in both directions by applying \(T\) by means of the tester API. Finally, the tester API also allows the user to measure how much the current coordinates deviate from the departure coordinates and produce image files representing these deviations.

Images produced by TransformTester using a regular grid of points (left) and stars in the sky (right).

generate_stars(ra, dec, ra_width, dec_width, maglimit)

Initializes the departure coordinates from a set of stars in the sky enclosed in a rectangle centered in right ascension ra and declination dec, and dimensions ra_width x dec_width (both of them in degrees) up to magnitude maglimit. Right ascension is encoded in the \(x\) coordinate and declination in the \(y\) coordinate.

generate_points(width, height, delta_x, delta_y)

Initializes the departure coordinates from a set of equally spaced points, assuming a rectangle of size width x height with a delta_x separation in the horizontal dimension and delta_y separation in the vertical dimension.

forward()

Applies the transform T to the current coordinates in the forward direction and replaces them by the result of the transform

backward()

Applies the transform T to the current coordinates in the forward direction and replaces them by the result of the transform.

backfeed()

Replaces the departure coordinates by the current coordinates, effectively behaving as if the tester departure points were generated from the current state.

sample()

Call T.generate() in order to sample the parameter distribution of the transform.

distortion_rms()

Returns the root-mean-square value of the difference between the current coordinates and the departure coordinates. This value is computed as:

\[E = \left[\frac{1}{N}\sum_{i=1}^N (x_i-\tilde{x}_i)^2+(y_i-\tilde{y}_i)^2\right]^{1/2}\]

With \((x_i, y_i)\) the departure coordinates and \((\tilde{x}_i,\tilde{y}_i)\) the current (potentially transformed) coordinates.

save_to_image(path)

Produce an image describing the result of the transformation with respect to the departure points, along with technical information like the exact sequence of applied transformations and the transform RMS.