DifferentiableAlignmentSimilarity¶

class
menpofit.transform.
DifferentiableAlignmentSimilarity
(source, target, rotation=True, allow_mirror=False)[source]¶ Bases:
AlignmentSimilarity
,DP
,DX
Base class that constructs a similarity transformation that is the optimal transform to align the source to the target. It can compute its own derivative with respect to spatial changes, as well as its parametrisation.

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 nondestructively (a transformed copy of the object will be returned).If not,
x
is assumed to be an ndarray. The transformation will be nondestructive, 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 nonmutating apply() instead.
For internal performancespecific uses, see _apply_inplace().

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

d_dp
(points)[source]¶ The derivative with respect to the parametrisation changes evaluated at points.
 Parameters
points (
(n_points, n_dims)
ndarray) – The spatial points at which the derivative should be evaluated. Returns
d_dp (
(n_points, n_parameters, n_dims)
ndarray) – The Jacobian with respect to the parametrisation.d_dp[i, j, k]
is the scalar differential change that thek
’th dimension of thei
’th point experiences due to a first order change in thej
’th scalar in the parametrisation vector.

d_dx
(points)[source]¶ The first order derivative with respect to spatial changes evaluated at points.
 Parameters
points (
(n_points, n_dims)
ndarray) – The spatial points at which the derivative should be evaluated. Returns
d_dx (
(n_points, n_dims, n_dims)
ndarray) – The Jacobian wrt spatial changes.d_dx[i, j, k]
is the scalar differential change that thej
’th dimension of thei
’th point experiences due to a first order change in thek
’th dimension.It may be the case that the Jacobian is constant across space  in this case axis zero may have length
1
to allow for broadcasting.

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 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 nonmutating API, from_vector.
For internal usage in performancesensitive 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 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 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_inplace_with
¶ Affine
can swallow composition with any otherAffine
.

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
¶ Number of parameters of Similarity
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.

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
