skshapes.morphing package¶

Deformation models.

Submodules¶

skshapes.morphing.basemodel module¶

Base class for all deformation models.

class skshapes.morphing.basemodel.BaseModel¶

Bases: object

Base class for all deformation models.

copy()¶

Return a copy of the model.

Returns:: a copy of the model
Return type:: BaseModel

inital_parameter(shape)¶

Return the initial parameters of the model.

Parameters:: shape (polydata_type | image_type) – the shape to morph
Returns:: the initial parameters of the model
Return type:: FloatTensor

skshapes.morphing.extrinsic_deformation module¶

Kernel deformation morphing algorithm.

This algorithm describes the morphing as a deformation of the ambiant space. The parameter is a vector field, which is referred to as the momentum. This momentum is smoothed by a kernel, and the morphed shape is obtained by integrating the momentum. The regularization is given by <p, K_q p> where p is the momentum, q is the initial position of the shape and K_q is the kernel at q.

class skshapes.morphing.extrinsic_deformation.ExtrinsicDeformation(n_steps=1, kernel='gaussian', scale=0.1, normalization=None, control_points=False, solver='euler')¶

Bases: BaseModel

Kernel deformation morphing algorithm.

Parameters:

n_steps (int) – Number of integration steps.
kernel (Literal['gaussian', 'uniform']) – Type of kernel.
scale (int | float) – Scale of the kernel.
normalization (Optional[Literal['rows', 'columns', 'both']]) – Normalization of the kernel matrix.
control_points (bool) – If True, the control points are the control points of the shape (accessible with shape.control_points). If False, the control points are the points of the shape. If shape.control_points is None, the control points are the points of the shape.
solver (Literal['euler', 'midpoint', 'rk4']) – The solver to use for the integration. Can be “euler”, “midpoint” or “rk4”.

H(p, q)¶

Hamiltonian function.

Return type:: Float32[Tensor, '']

K(q0, q1=None, weights0=None, weights1=None)¶

Return type:: LinearOperator

morph(shape, parameter, return_path=False, return_regularization=False, final_time=1.0)¶

Morph a shape using the kernel deformation algorithm.

Parameters:

shape (polydata_type) – The shape to morph.
parameter (Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3']) – The momentum.
return_path (bool) – True if you want to have access to the sequence of polydatas.
return_regularization (bool) – True to have access to the regularization.
final_time (float) – The final time of the integration. Default is 1.0, it can be set to a different value for extrapolation.

Returns:

A named tuple containing the morphed shape, the regularization and the path if needed.

Return type:

MorphingOutput

ode_func(t, y)¶

ODE function.

Return type:: tuple[Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3'], Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3']] | tuple[Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3'], Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3'], Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3']]

parameter_shape(shape)¶

Return the shape of the parameter.

Parameters:: shape (polydata_type) – The shape to morph.
Returns:: The shape of the parameter.
Return type:: tuple[int, int]

class skshapes.morphing.extrinsic_deformation.ODEModule(func)¶

Bases: Module

Define the ODE function as a module for torchdiffeq.

Wrap the ODE function in a torch.nn.Module module to be used with torchdiffeq.

Parameters:: func (callable) – The function that defines the ODE, see th documentation of [torchdiffeq](https://github.com/rtqichen/torchdiffeq).

skshapes.morphing.intrinsic_deformation module¶

Vector field deformation model.

This module contains the implementation of the vector field deformation model. This model is described by a sequence of speed vectors, which are summed to obtain the sequence of points of the morphed shape. The morphing is regularized by a Riemannian metric on the shape space.

class skshapes.morphing.intrinsic_deformation.IntrinsicDeformation(n_steps=1, metric='as_isometric_as_possible', endpoints=None, use_stiff_edges=True, **kwargs)¶

Bases: BaseModel

Vector field deformation model.

Parameters:

n_steps (int) – Number of integration steps.
metric (Union[Literal['as_isometric_as_possible', 'shell_energy'], Callable]) – Riemannian metric used to regularize the morphing.
endpoints (None | Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3']) – The endpoints of the morphing. If None, the endpoints are not fixed and the morphed shape is free to move. If not None, the morphed shape is constrained to be at the endpoints and the only free steps are the intermediate steps. Providing endpoints is useful to minimize the energy of the morphing while keeping the endpoints fixed.
use_stiff_edges (bool) – If the source PolyData has a stiff_edges property and this argument is True, the stiff_edges are passed to the metric. If the source PolyData has no stiff_edges, edges are passed by default.
**kwargs – Additional keyword arguments.

morph(shape, parameter, return_path=False, return_regularization=False)¶

Morph a shape.

Parameters:

shape (polydata_type) – The shape to morph.
parameter (Float32[Tensor, '_ _ _']) – Sequence of velocity vectors.
return_path (bool) – True if you want to have access to the morphing’s sequence of polydatas.
return_regularization (bool) – True to have access to the regularization.

Returns:

A named tuple containing the morphed shape, the regularization and the path if requested.

Return type:

MorphingOutput

property n_free_steps: int¶

Number of integration steps.

If the endpoints are fixed, the number of free steps is n_steps - 1 as the last step is fixed by the endpoints. Otherwise, the number of free steps is n_steps.

parameter_shape(shape)¶

Return the shape of the parameter.

Parameters:: shape (polydata_type) – The shape to morph.
Return type:: tuple[int, int, int]
Returns:: The shape of the parameter.

skshapes.morphing.intrinsic_deformation.as_isometric_as_possible(points_sequence, velocities_sequence, edges=None, triangles=None)¶

As isometric as possible metric.

This metric penalizes the non-isometricity of the mesh.

Compute the mean velocities’ metric along the sequence of points.

Parameters:

points_sequence (Float32[Tensor, '_ _ _']) – Sequence of points
velocities_sequence (Float32[Tensor, '_ _ _']) – Sequence of velocities.
edges (Int64[Tensor, '_ 2'] | None) – Edges.
triangles (Int64[Tensor, '_ 3'] | None) – Triangles.

Raises:

AttributeError – This metric requires edges to be defined:

Return type:

Float32[Tensor, '']

Returns:

FloatScalar: the mean velocities metric

References

[KILIAN, Martin, MITRA, Niloy J., et POTTMANN, Helmut. Geometric modeling in shape space. In : ACM SIGGRAPH 2007 papers. 2007. p. 64-es.](https://dmg.tuwien.ac.at/geom/ig/publications/oldpub/2007/kilian-2007-gmss/paper_docs/shape_space_sig_07.pdf)

skshapes.morphing.intrinsic_deformation.metric_validation(metric)¶

Test the validity of a callable metric.

Parameters:: metric (Callable) – The metric to test.
Raises:: ValueError – If the metric has one of the following issues: - The metric does not have the expected arguments (points_sequence, velocities_sequence, edges, triangles). - The metric does not return a torch.Tensor. - The metric does not return a scalar. - The metric is not differentiable wrt the velocities.
Return type:: None

skshapes.morphing.intrinsic_deformation.shell_energy_metric(points_sequence, velocities_sequence, edges=None, triangles=None, bending_weight=0.001)¶

Shell energy metric.

This metric is the sum of a membrane contribution, measuring the local stretching and a bending contribution, measuring the change in curvature. The parameter weight controls the importance of the bending energy.

Parameters:

points_sequence (Float32[Tensor, '_ _ _']) – Sequence of points
velocities_sequence (Float32[Tensor, '_ _ _']) – Sequence of velocities.
edges (Int64[Tensor, '_ 2'] | None) – Edges.
triangles (Int64[Tensor, '_ 3'] | None) – Triangles.
bending_weight (int | float) – The weight of the bending energy.

Raises:

AttributeError – This metric requires triangles to be defined:

Return type:

Float32[Tensor, '']

Returns:

FloatScalar: the mean velocities metric

References

[HEEREN, Behrend, RUMPF, Martin, SCHRÖDER, Peter, et al. Exploring the geometry of the space of shells. In : Computer Graphics Forum. 2014. p. 247-256.](https://ddg.math.uni-goettingen.de/pub/HeRuSc14.pdf)

skshapes.morphing.rigid_motion module¶

Rigid motion model.

This module contains the implementation of the rigid motion model. This model is described by a translation and a rotation. The morphing is not regularized.

class skshapes.morphing.rigid_motion.RigidMotion(n_steps=1)¶

Bases: BaseModel

Rigid motion morphing.

Parameters:: n_steps (int) – Number of steps.

create_path(*, shape, small_rotation_matrix, small_translation)¶

Create the path from the rotation matrix and the translation.

Parameters:

shape (polydata_type) – The initial shape.
small_rotation_matrix (Float32[Tensor, '_ _']) – The rotation matrix that will be applied at each step.
translation – The translation vector that will be applied at each step.

Returns:

The path. Its length is n_steps + 1.

Return type:

list[polydata_type]

morph(shape, parameter, return_path=False, return_regularization=False)¶

Morph a shape using the rigid motion model.

If the data is 3D The parameter must be a (2, 3) tensor, where the first row is the axis-angle rotations and the second row is the translation vector.

If the data is 2D, the parameter must be a (3,) tensor, where the first element is the rotation angle and the two last elements are the translation vector.

Parameters:

shape (polydata_type) – The shape to morph.
parameter (Float32[Tensor, '_ _'] | Float32[Tensor, '_']) – The rigid motion parameter.
return_path (bool) – True if you want to have access to the sequence of polydatas.
return_regularization (bool) – True to have access to the regularization.

Returns:

A named tuple containing the morphed shape, the regularization and the path if needed.

Return type:

MorphingOutput

parameter_shape(shape)¶

Return the shape of the parameter.

Parameters:: shape (polydata_type | image_type) – The shape to morph.
Returns:: The shape of the parameter.
Return type:: Union[tuple[int, int]

skshapes.morphing.rigid_motion.axis_angle_to_matrix(axis_angle)¶

Convert rotations given as axis/angle to rotation matrices.

Parameters:: axis_angle (Tensor) – Rotations given as a vector in axis angle form, as a tensor of shape (…, 3), where the magnitude is the angle turned anticlockwise in radians around the vector’s direction.
Returns:: Rotation matrices as tensor of shape (…, 3, 3).
Return type:: torch.Tensor

skshapes.morphing.rigid_motion.axis_angle_to_quaternion(axis_angle)¶

Convert rotations given as axis/angle to quaternions.

Parameters:: axis_angle (Tensor) – Rotations given as a vector in axis angle form, as a tensor of shape (…, 3), where the magnitude is the angle turned anticlockwise in radians around the vector’s direction.
Returns:: Quaternions with real part first, as tensor of shape (…, 4).
Return type:: torch.Tensor

skshapes.morphing.rigid_motion.quaternion_to_matrix(quaternions)¶

Convert rotations given as quaternions to rotation matrices.

Parameters:: quaternions (Tensor) – Quaternions with real part first, as tensor of shape (…, 4).
Return type:: Tensor
Returns:: Rotation matrices as tensor of shape (…, 3, 3).

skshapes.morphing.validation module¶

Validation utilities for morphing module.

skshapes.morphing.validation.validate_polydata_morphing_model(model, shape)¶

Test a model with a PolyData shape.

This function does basic tests on a model with a PolyData shape. In order to be used in a task such as Registration, the model must fulfill some requirements.

It checks that the parameter tensor can be initialized automatically from the model and that the morph induces a transformation that is differentiable with respect to the parameter.

Parameters:

model (Any) – The model to test.
shape (polydata_type | image_type) – The shape on which to test the model.

Return type:

None

Examples

import skshapes as sks shape_3d = sks.Sphere() shape_2d = sks.Circle() model = sks.RigidMotion() sks.validate_model_polydata(model, shape_3d) sks.validate_model_polydata(model, shape_2d)