skshapes.data package¶

Data classes: PolyData, Images.

skshapes.data.Circle(n_points=20)¶

Return a circle.

Parameters: n_points (int, optional): Number of points. Defaults to 20.

Returns:: the circle
Return type:: polydata_type

skshapes.data.Sphere()¶

Return a sphere.

Return type:: polydata_type

Submodules¶

skshapes.data.image module¶

Image shape class.

class skshapes.data.image.Image¶

Bases: image_type

Image shape class.

skshapes.data.polydata module¶

PolyData class.

class skshapes.data.polydata.PolyData(points, *, edges=None, triangles=None, device=None, landmarks=None, control_points=None, stiff_edges=None, point_data=None, edge_data=None, triangle_data=None, cache_size=None)¶

Bases: polydata_type

A polygonal data object. It is composed of points, edges and triangles.

Three types of objects can be provided to initialize a PolyData object:

a vedo mesh
a pyvista mesh
a path to a mesh
points, edges and triangles as torch tensors

PolyData object has support for data attributes: point_data, edge_data and triangle_data. These are dictionaries of torch tensors that can be used to store any kind of data associated with the points, edges or triangles of the shape.

Landmarks can be defined on the shape. The easiest way to define landmarks is to provide a list of indices.

Landmarks can also be defined as a sparse tensor of shape (n_landmarks, n_points) where each line is a landmark in barycentric coordinates. It allows to define landmarks in a continuous space (on a triangle or an edge) and not only on the vertices of the shape.

Control Points can be defined on the shape. Control Points is another PolyData that is used to control the deformation of the shape. It is used in the context of the [ExtrinsicDeformation](../../morphing/extrinsic_deformation) model.

For visualization, PolyData can be converted into a pyvista PolyData or a vedo Mesh with the to_pyvista and to_vedo methods.

Also, PolyData can be saved to a file with the save method. The format accepted by PyVista are supported (.ply, .stl, .vtk).

Parameters:

points (Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3'] | Mesh | PolyData | Path | str) – The points of the shape. Could also be a vedo mesh, a pyvista mesh or a path to a file. If it is a mesh or a path, the edges and triangles are inferred from it.
edges (Int64[Tensor, '_ 2'] | None) – The edges of the shape.
triangles (Int64[Tensor, '_ 3'] | None) – The triangles of the shape.
device (str | device | None) – The device on which the shape is stored. If None it is inferred from the points.
landmarks (Union[Tensor, Int[Tensor, '_'], Int[ndarray, '_'], list[int], None]) – The landmarks of the shape.
control_points (polydata_type | None) – The control points of the shape.
stiff_edges (Int64[Tensor, '_ 2'] | None) – The stiff edges structure of the shape, useful for as_isometric_as_possible
point_data (DataAttributes | None) – The point data of the shape.
edge_data (DataAttributes | None) – The edge data of the shape.
triangle_data (DataAttributes | None) – The triangle data of the shape.
cache_size (int | None) – Size of the cache for memoized properties. Defaults to None (= no cache limit). Use a smaller value if you intend to e.g. compute point curvatures at many different scales.

Examples

See the corresponding [examples](../../../generated/gallery/#data)

add_landmarks(indices)¶

Add vertices landmarks to the shape.

Parameters:: indices (Int[Tensor, '_'] | Int[ndarray, '_'] | list[int] | int) – The indices of the vertices to add to the landmarks.
Return type:: None

bounding_grid(N=10, offset=0.05)¶

Bounding grid of the shape.

Compute a bounding grid of the shape. The grid is a PolyData with points and edges representing a regular grid enclosing the shape.

Parameters:

N (int) – The number of points on each axis of the grid.
offset (float | int) – The offset of the grid with respect to the shape. If offset=0, the grid is exactly the bounding box of the shape. If offset=1, the grid is the bounding box of the shape dilated by a factor 2.

Returns:

The bounding grid of the shape.

Return type:

PolyData

cache_clear()¶: Reload all cached properties.

property control_points: polydata_type | None¶: Control points of the shape.

copy()¶

Copy the shape.

Returns:: The copy of the shape.
Return type:: PolyData

decimate(*, target_reduction=None, n_points=None, ratio=None)¶

Decimation of the shape.

Parameters:

target_reduction (int | float | None) – The target reduction ratio.
n_points (int | None) – The number of points to keep.

Raises:

InputStructureError – If both target_reduction and n_points are provided. If none of target_reduction and n_points are provided.

Returns:

The decimated shape.

Return type:

PolyData

property device: device¶: Device getter.

property dim: int¶: Dimension of the shape getter.

property edge_centers: Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3']¶: Center of each edge.

property edge_data: DataAttributes¶: Edge data getter.

property edge_lengths: Float32[Tensor, '_']¶: Length of each edge.

property edges: Int64[Tensor, '_ 2'] | None¶

Edges getter.

Returns:: The edges of the shape. If the shape is a triangle mesh, the edges are computed from the triangles. If the shape is not a triangle mesh, the edges are directly returned.
Return type:: Optional[Edges]

is_triangle_mesh()¶

Check if the shape is triangular.

Return type:: bool

k_ring_graph(k=2, verbose=False)¶

Compute the k-ring graph of the shape.

The k-ring graph is the graph where each vertex is connected to its k-neighbors, where the neighborhoods are defined by the edges.

Parameters:

k (int) – the size of the neighborhood, by default 2
optional – the size of the neighborhood, by default 2
verbose (bool) – whether or not display information about the remaining number of steps
optional – whether or not display information about the remaining number of steps

Return type:

Int64[Tensor, '_ 2']

Returns:

The k-ring neighbors edges.

knn_graph(k=2, include_edges=False)¶

Return the k-nearest neighbors edges of a shape.

Parameters:

shape – The shape to process.
k (int) – The number of neighbors.
include_edges (bool) – If True, the edges of the shape are concatenated with the k-nearest neighbors edges.

Returns:

The k-nearest neighbors edges.

Return type:

Edges

property landmark_indices: Int64[Tensor, '...'] | None¶

Indices of the landmarks.

Raises:: ValueError – If the landmarks are not indices (there are defined in barycentric coordinates).
Returns:: The indices of the landmarks. None if no landmarks are defined.
Return type:: Optional[IntTensor]

property landmark_points: Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3'] | None¶: Landmarks in spatial coordinates.

property landmark_points_3D: Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3'] | None¶

Landmarks in 3D coordinates.

If self.dim == 3, it is equivalent to landmark_points. Otherwise, if self.dim == 2, it returns the landmarks with a third coordinate set to 0.

Returns:: The landmarks in 3D coordinates.
Return type:: Points

property landmarks: Tensor | None¶

Get the landmarks of the shape.

The format is a sparse tensor of shape (n_landmarks, n_points), each line is a landmark in barycentric coordinates. If you want to get the landmarks in 3D coordinates, use the landmark_points property. If you want to get the landmarks as a list of indices, use the landmark_indices property.

If no landmarks are defined, returns None.

property mean_point: Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3']¶

Mean point of the shape.

Return the mean point as a (N_batch, 3) tensor.

property n_edges: int¶: Number of edges getter.

property n_landmarks: int¶: Return the number of landmarks.

property n_points: int¶: Number of points getter.

property n_triangles: int¶: Number of triangles getter.

plot(backend='pyvista', **kwargs)¶

Plot the shape.

Available backends are “pyvista” and “vedo”. See the documentation of the corresponding plot method for the available arguments:

Parameters:: backend (Literal['pyvista', 'vedo']) – Which backend to use for plotting.
Return type:: None

property point_data: DataAttributes¶: Point data getter.

property point_weights: Float32[Tensor, '_']¶: Point weights.

property points: Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3']¶: Points getter.

save(filename)¶

Save the shape to a file.

Format accepted by PyVista are supported (.ply, .stl, .vtk) see: https://github.com/pyvista/pyvista/blob/release/0.40/pyvista/core/pointset.py#L439-L1283 # noqa: E501

Parameters:: filename (Path | str) – The path where to save the shape.
Return type:: None

property standard_deviation: Float32[Tensor, '_']¶

Standard deviation of the shape.

Returns the standard deviation (radius) of the shape as a (N_batch,) tensor.

property stiff_edges: Int64[Tensor, '_ 2'] | None¶: Stiff edges getter

to(device)¶

Copy the shape on a given device.

Return type:: PolyData

to_pyvista()¶

Pyvista PolyData converter.

Return type:: PolyData

to_vedo()¶

Vedo Mesh converter.

Return type:: Mesh

to_weighted_points()¶

Convert the shape to a weighted point cloud.

Return type:

tuple[Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3'], Float32[Tensor, '_']]

Returns:

points – The points of the weighted point cloud.
weights – The weights of the weighted point cloud.

property triangle_areas: Float32[Tensor, '_']¶: Area of each triangle.

property triangle_centers: Float32[Tensor, '_ 2'] | Float32[Tensor, '_ 3']¶: Center of the triangles.

property triangle_data: DataAttributes¶: Triangle data getter.

property triangle_normals: Float32[Tensor, '_ _']¶: Normal of each triangle.

property triangles: Int64[Tensor, '_ 3'] | None¶: Triangles getter.

skshapes.data.utils module¶

Utility functions and classes for the data module.

class skshapes.data.utils.DataAttributes(*, n=None, device=None)¶

Bases: dict

DataAttributes class.

This class is a dictionary aimed to store attributes associated to a data structure (e.g. a set of points, a set of triangles, etc.) When a new attribute is added to the dictionary, it is checked that its size is compatible with the size of the data structure.

The DataAttributes structure ensures that all the attributes are torch.Tensor and on the same device, doing the necessary conversions if needed.

There are two ways to add an attribute to the dictionary:

With an explicit name, using the __setitem__ method (e.g.
A[“attribute”] = attribute)
Without an explicit name, using the append method (e.g.
A.append(attribute)) which will automatically set “attribute_{i}” where i is the minimum integer such that “attribute_{i}” is not already in the dictionary

Parameters:

n (int | None) – The number of elements of the set. If None, it will be determined by the first attribute added to the DataAttributes object.
device (str | device | None) – The device on which the attributes should be stored. If None, it will be determined by the first attribute added to the

append(value)¶

Append an attribute to the DataAttributes object.

The key of the attribute will be “attribute_{i}” where i is the minimum integer such that “attribute_{i}” is not already in the dictionary.

Parameters:: value ('] | ']) – The value of the attribute to append.
Return type:: None

clone()¶

Clone the DataAttributes object.

Returns:: The cloned DataAttributes object.
Return type:: DataAttributes

property device: str | device¶: Device getter.

classmethod from_dict(cls, attributes, device=None)¶

From dictionary constructor.

Parameters:

attributes (dict[Any, '] | '] | '] | ']]) – The dictionary of attributes to initialize the DataAttributes object.
device (str | device | None) – The device on which the attributes should be stored. If None, it will be determined from attributes.

Return type:

DataAttributes

classmethod from_pyvista_datasetattributes(attributes, device=None)¶

From pyvista.DataSetAttributes constructor.

Return type:: DataAttributes

property n: int¶: Number of elements of the set getter.

to(device)¶

Move the DataAttributes object on a given device.

Parameters:: device (str | device) – The device on which the object should be made.
Returns:: The copy of the DataAttributes object on the new device.
Return type:: DataAttributes

to_numpy_dict()¶

Cast as dictionary of numpy arrays.

Return type:: dict[Any, '] | ']]

skshapes.data.utils.cache_clear(self)¶: Reload all cached properties.

skshapes.data.utils.cached_method(*lru_args, **lru_kwargs)¶: Least-recently-used cache decorator for instance methods.

skshapes.data.utils.instance_lru_cache(method=None, *, maxsize=128, typed=False)¶

Least-recently-used cache decorator for instance methods.

The cache follows the lifetime of an object (it is stored on the object, not on the class) and can be used on unhashable objects. Wrapper around functools.lru_cache.

If maxsize is set to None, the LRU features are disabled and the cache can grow without bound.

If typed is True, arguments of different types will be cached separately. For example, f(3.0) and f(3) will be treated as distinct calls with distinct results.

Arguments to the cached method (other than ‘self’) must be hashable.

View the cache statistics named tuple (hits, misses, maxsize, currsize) with f.cache_info(). Clear the cache and statistics with f.cache_clear(). Access the underlying function with f.__wrapped__.

Return type:: Callable[..., TypeVar(T)] | Callable[[Callable[..., TypeVar(T)]], Callable[..., TypeVar(T)]]