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.

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, **kwargs)

Bases: BaseModel

Vector field deformation model.

Parameters:

  • n_steps (int) – Number of integration steps.

  • metric (Literal['as_isometric_as_possible', 'shell_energy']) – 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.

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

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