# AlignmentAffine¶

class menpo.transform.AlignmentAffine(source, target)[source]

Bases: HomogFamilyAlignment, Affine

Constructs an Affine by finding the optimal affine transform to align source to target.

Parameters: source (PointCloud) – The source pointcloud instance used in the alignment target (PointCloud) – The target pointcloud instance used in the alignment

Notes

We want to find the optimal transform M which satisfies $$M a = b$$ where $$a$$ and $$b$$ are the source and target homogeneous vectors respectively.

(M a)' = b'
a' M' = b'
a a' M' = a b'


a a’ is of shape (n_dim + 1, n_dim + 1) and so can be inverted to solve for M.

This approach is the analytical linear least squares solution to the problem at hand. It will have a solution as long as (a a’) is non-singular, which generally means at least 2 corresponding points are required.

aligned_source()

The result of applying self to source

Type: PointCloud
alignment_error()

The Frobenius Norm of the difference between the target and the aligned source.

Type: float
apply(x, batch_size=None, **kwargs)

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters: x (Transformable or (n_points, n_dims) ndarray) – The array or object to be transformed. batch_size (int, optional) – If not None, this determines how many items from the numpy array will be passed through the transform at a time. This is useful for operations that require large intermediate matrices to be computed. kwargs (dict) – Passed through to _apply(). transformed (type(x)) – The transformed object or array
apply_inplace(*args, **kwargs)

Deprecated as public supported API, use the non-mutating apply() instead.

For internal performance-specific uses, see _apply_inplace().

as_non_alignment()[source]

Returns a copy of this Affine without its alignment nature.

Returns: transform (Affine) – A version of this affine with the same transform behavior but without the alignment logic.
as_vector(**kwargs)

Returns a flattened representation of the object as a single vector.

Returns: vector ((N,) ndarray) – The core representation of the object, flattened into a single vector. Note that this is always a view back on to the original object, but is not writable.
compose_after(transform)

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))


a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters: transform (Transform) – Transform to be applied before self transform (Transform or TransformChain) – If the composition was native, a single new Transform will be returned. If not, a TransformChain is returned instead.
compose_after_inplace(transform)

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))


a is permanently altered to be the result of the composition. b is left unchanged.

Parameters: transform (composes_inplace_with) – Transform to be applied before self ValueError – If transform isn’t an instance of composes_inplace_with
compose_before(transform)

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))


a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters: transform (Transform) – Transform to be applied after self transform (Transform or TransformChain) – If the composition was native, a single new Transform will be returned. If not, a TransformChain is returned instead.
compose_before_inplace(transform)

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))


a is permanently altered to be the result of the composition. b is left unchanged.

Parameters: transform (composes_inplace_with) – Transform to be applied after self ValueError – If transform isn’t an instance of composes_inplace_with
copy()

Generate an efficient copy of this HomogFamilyAlignment.

Returns: new_transform (type(self)) – A copy of this object
decompose()

Decompose this transform into discrete Affine Transforms.

Useful for understanding the effect of a complex composite transform.

Returns: transforms (list of DiscreteAffine) – Equivalent to this affine transform, such that:reduce(lambda x,y: x.chain(y), self.decompose()) == self 
from_vector(vector)

Build a new instance of the object from its vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters: vector ((n_parameters,) ndarray) – Flattened representation of the object. transform (Homogeneous) – An new instance of this class.
from_vector_inplace(vector)

Deprecated. Use the non-mutating API, from_vector.

For internal usage in performance-sensitive spots, see _from_vector_inplace()

Parameters: vector ((n_parameters,) ndarray) – Flattened representation of this object
has_nan_values()

Tests if the vectorized form of the object contains nan values or not. This is particularly useful for objects with unknown values that have been mapped to nan values.

Returns: has_nan_values (bool) – If the vectorized object contains nan values.
init_identity(n_dims)

Creates an identity matrix Affine transform.

Parameters: n_dims (int) – The number of dimensions. identity (Affine) – The identity matrix transform.
pseudoinverse()

The pseudoinverse of the transform - that is, the transform that results from swapping source and target, or more formally, negating the transforms parameters. If the transform has a true inverse this is returned instead.

Returns: transform (type(self)) – The inverse of this transform.
pseudoinverse_vector(vector)

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()


Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters: vector ((n_parameters,) ndarray) – A vectorized version of self pseudoinverse_vector ((n_parameters,) ndarray) – The pseudoinverse of the vector provided
set_h_matrix(value, copy=True, skip_checks=False)[source]

Updates h_matrix, optionally performing sanity checks.

Note

Updating the h_matrix on an AlignmentAffine triggers a sync of the target.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters: value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If True skip checking. Useful for performance. NotImplementedError – If h_matrix_is_mutable returns False.
set_target(new_target)

Update this object so that it attempts to recreate the new_target.

Parameters: new_target (PointCloud) – The new target that this object should try and regenerate.
composes_inplace_with

Affine can swallow composition with any other Affine.

composes_with

Any Homogeneous can compose with any other Homogeneous.

h_matrix

The homogeneous matrix defining this transform.

Type: (n_dims + 1, n_dims + 1) ndarray
h_matrix_is_mutable

True iff set_h_matrix() is permitted on this type of transform.

If this returns False calls to set_h_matrix() will raise a NotImplementedError.

Type: bool
has_true_inverse

The pseudoinverse is an exact inverse.

Type: True
linear_component

The linear component of this affine transform.

Type: (n_dims, n_dims) ndarray
n_dims

The number of dimensions of the target.

Type: int
n_dims_output

The output of the data from the transform.

Type: int
n_parameters

n_dims * (n_dims + 1) parameters - every element of the matrix but the homogeneous part.

Type: int

Examples

2D Affine: 6 parameters:

[p1, p3, p5]
[p2, p4, p6]


3D Affine: 12 parameters:

[p1, p4, p7, p10]
[p2, p5, p8, p11]
[p3, p6, p9, p12]

n_points

The number of points on the target.

Type: int
source

The source PointCloud that is used in the alignment.

The source is not mutable.

Type: PointCloud
target

The current PointCloud that this object produces.

To change the target, use set_target().

Type: PointCloud
translation_component

The translation component of this affine transform.

Type: (n_dims,) ndarray