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 alignmenttarget (
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.
-
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
isTransformable
,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
andb
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. Seecomposes_with
for a description of how the mode of composition is decided.- Parameters
transform (
Transform
) – Transform to be applied beforeself
- Returns
transform (
Transform
orTransformChain
) – If the composition was native, a single newTransform
will be returned. If not, aTransformChain
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 beforeself
- Raises
ValueError – If
transform
isn’t an instance ofcomposes_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
andb
are left unchanged.An attempt is made to perform native composition, but will fall back to a
TransformChain
as a last resort. Seecomposes_with
for a description of how the mode of composition is decided.- Parameters
transform (
Transform
) – Transform to be applied afterself
- Returns
transform (
Transform
orTransformChain
) – If the composition was native, a single newTransform
will be returned. If not, aTransformChain
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 afterself
- Raises
ValueError – If
transform
isn’t an instance ofcomposes_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 thatreduce(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 adeepcopy
of the object followed by a call tofrom_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 tonan
values.- Returns
has_nan_values (bool) – If the vectorized object contains
nan
values.
-
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. IfFalse
, phi and psi are interpreted as radians.
- Returns
shear_transform (
Affine
) – A 2D shear transform.
-
classmethod
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 ofself
- 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 theh_matrix
could change the nature of the transform. Seeh_matrix_is_mutable
for how you can discover if theh_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
returnsFalse
.
-
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_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
iffset_h_matrix()
is permitted on this type of transform.If this returns
False
calls toset_h_matrix()
will raise aNotImplementedError
.- 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_output
¶ The output of the data from the transform.
- Type
int
-
property
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]
-
property
source
¶ The source
PointCloud
that is used in the alignment.The source is not mutable.
- Type
-
property
target
¶ The current
PointCloud
that this object produces.To change the target, use
set_target()
.- Type
-
property
translation_component
¶ The translation component of this affine transform.
- Type
(n_dims,)
ndarray