AlignmentRotation

class menpo.transform.AlignmentRotation(source, target, allow_mirror=False)[source]

Bases: HomogFamilyAlignment, Rotation

Constructs an Rotation by finding the optimal rotation 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

  • 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 rotation without its alignment nature.

Returns

transform (Rotation) – A version of this rotation 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.

axis_and_angle_of_rotation()

Abstract method for computing the axis and angle of rotation.

Returns

  • axis ((n_dims,) ndarray) – The unit vector representing the axis of rotation

  • angle_of_rotation (float) – The angle in radians of the rotation about the axis. The angle is signed in a right handed sense.

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_from_vector_inplace(vector)

Specialised inplace composition with a vector. This should be overridden to provide specific cases of composition whereby the current state of the transform can be derived purely from the provided vector.

Parameters

vector ((n_parameters,) ndarray) – Vector to update the transform state with.

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()

A DiscreteAffine is already maximally decomposed - return a copy of self in a list.

Returns

transform (DiscreteAffine) – Deep copy of 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.

classmethod init_3d_from_quaternion(q)

Convenience constructor for 3D rotations based on quaternion parameters.

Parameters

q ((4,) ndarray) – The quaternion parameters.

Returns

rotation (Rotation) – A 3D rotation transform.

classmethod init_from_2d_ccw_angle(theta, degrees=True)

Convenience constructor for 2D CCW rotations about the origin.

Parameters
  • theta (float) – The angle of rotation about the origin

  • degrees (bool, optional) – If True theta is interpreted as a degree. If False, theta is interpreted as radians.

Returns

rotation (Rotation) – A 2D rotation transform.

classmethod 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.

classmethod init_from_3d_ccw_angle_around_x(theta, degrees=True)

Convenience constructor for 3D CCW rotations around the x axis

Parameters
  • theta (float) – The angle of rotation about the origin

  • degrees (bool, optional) – If True theta is interpreted as a degree. If False, theta is interpreted as radians.

Returns

rotation (Rotation) – A 3D rotation transform.

classmethod init_from_3d_ccw_angle_around_y(theta, degrees=True)

Convenience constructor for 3D CCW rotations around the y axis

Parameters
  • theta (float) – The angle of rotation about the origin

  • degrees (bool, optional) – If True theta is interpreted as a degree. If False, theta is interpreted as radians.

Returns

rotation (Rotation) – A 3D rotation transform.

classmethod init_from_3d_ccw_angle_around_z(theta, degrees=True)

Convenience constructor for 3D CCW rotations around the z axis

Parameters
  • theta (float) – The angle of rotation about the origin

  • degrees (bool, optional) – If True theta is interpreted as a degree. If False, theta is interpreted as radians.

Returns

rotation (Rotation) – A 3D rotation transform.

classmethod init_identity(n_dims)

Creates an identity transform.

Parameters

n_dims (int) – The number of dimensions.

Returns

identity (Rotation) – 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_rotation_matrix(value, skip_checks=False)[source]

Sets the rotation matrix.

Parameters
  • value ((n_dims, n_dims) ndarray) – The new rotation matrix.

  • skip_checks (bool, optional) – If True avoid sanity checks on value for performance.

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.

property composes_inplace_with

Rotation can swallow composition with any other Rotation.

property composes_with

Any Homogeneous can compose with any other Homogeneous.

property h_matrix

The homogeneous matrix defining this transform.

Type

(n_dims + 1, n_dims + 1) ndarray

property 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

property has_true_inverse

The pseudoinverse is an exact inverse.

Type

True

property linear_component

The linear component of this affine transform.

Type

(n_dims, n_dims) ndarray

property n_dims

The number of dimensions of the target.

Type

int

property n_dims_output

The output of the data from the transform.

Type

int

property n_parameters

Number of parameters of Rotation. Only 3D rotations are currently supported.

Returns

n_parameters (int) – The transform parameters. Only 3D rotations are currently supported which are parametrized with quaternions.

Raises

DimensionalityError, NotImplementedError – Non-3D Rotations are not yet vectorizable

property n_points

The number of points on the target.

Type

int

property rotation_matrix

The rotation matrix.

Type

(n_dims, n_dims) ndarray

property source

The source PointCloud that is used in the alignment.

The source is not mutable.

Type

PointCloud

property target

The current PointCloud that this object produces.

To change the target, use set_target().

Type

PointCloud

property translation_component

The translation component of this affine transform.

Type

(n_dims,) ndarray