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().
Returns:

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
Returns: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
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) – Transform to be applied after self
Returns: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
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 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.
Returns: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_from_2d_shear(phi, psi, degrees=True)

Convenience constructor for 2D shear transformations about the origin.

Parameters:
  • phi (float) – The angle of shearing in the X direction.
  • psi (float) – The angle of shearing in the Y direction.
  • degrees (bool, optional) – If True phi and psi are interpreted as degrees. If False, phi and psi are interpreted as radians.
Returns:

shear_transform (Affine) – A 2D shear transform.

init_identity(n_dims)

Creates an identity matrix Affine transform.

Parameters:n_dims (int) – The number of dimensions.
Returns: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
Returns:pseudoinverse_vector ((n_parameters,) ndarray) – The pseudoinverse of the vector provided
set_h_matrix(value, copy=True, skip_checks=False)

Deprecated Deprecated - do not use this method - you are better off just creating a new transform!

Updates h_matrix, optionally performing sanity checks.

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_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

Deprecated 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