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, **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. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

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

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

as_non_alignment()[source]¶

Returns a copy of this affine without it’s 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` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – 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`
Raises:	`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` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – 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`
Raises:	`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 it’s 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 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.
Returns:	transform (`type(self)`) – An new instance of this class.

from_vector_inplace(p)¶: Updates this Affine in-place from the new parameters. See from_vector for details of the parameter format

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`
Returns:	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.
Raises:	`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_with¶: Any Homogeneous can compose with any other Homogeneous.

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

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_parameters¶

n_dims * (n_dims + 1) parameters - every element of the matrix bar 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