AlignmentSimilarity

class menpo.transform.AlignmentSimilarity(source, target, rotation=True, allow_mirror=False)[source]

Bases: HomogFamilyAlignment, Similarity

Infers the similarity transform relating two vectors with the same dimensionality. This is simply the procrustes alignment of the source to the target.

Parameters:
  • source (PointCloud) – The source pointcloud instance used in the alignment
  • target (PointCloud) – The target pointcloud instance used in the alignment
  • rotation (bool, optional) – If False, the rotation component of the similarity transform is not inferred.
  • allow_mirror (bool, optional) – If True, the Kabsch algorithm check is not performed, and mirroring of the Rotation matrix is permitted.
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 similarity without it’s alignment nature.

Returns:transform (Similarity) – A version of this similarity 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_identity(n_dims)

Creates an identity transform.

Parameters:n_dims (int) – The number of dimensions.
Returns:identity (Similarity) – 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)

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

h_matrix is not mutable.

Type:False
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

2D Similarity: 4 parameters:

[(1 + a), -b,      tx]
[b,       (1 + a), ty]

3D Similarity: Currently not supported

Returns:n_parameters (int) – The transform parameters
Raises:DimensionalityError, NotImplementedError – Only 2D transforms are supported.
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