skshapes.multiscaling.multiscale.Multiscale

class skshapes.multiscaling.multiscale.Multiscale(shape, ratios=None, n_points=None, scales=None, decimation_module=None)

Bases: object

Multiscale representation of a shape.

This class represents a shape using multiple levels of details, from coarse to fine scales. This is useful to speed-up computations such as multigrid simulations or level-of-detail rendering. This class takes as input a high-resolution shape and accepts three types of parameters to define the coarser representations in the hierarchy:

The number of points n_points of each coarser scale.
The typical scale or distance between two neighboring samples at each coarser scale.
The ratio of the number of points between the origin scale and each coarser scale. A ratio of 1.0 corresponds to the original high-resolution shape, whereas a ratio of 0.2 corresponds to a coarse representation that only uses 20% of the original point count.

Most of the methods of this class can be called with one of the n_points, scale or ratio parameters.

We can retrieve existing coarse models at different scales using the at method and add models at new sampling resolutions using the append method.

Signals (point_data) defined at one scale can be propagated to the other scales using the propagate() method. This is illustrated in this tutorial.

Likewise, if landmarks are defined on the original shape, they are propagated to the coarser scales as illustrated in this tutorial.

Parameters:

shape (polydata_type | image_type) – The shape at the original, finest scale.
ratios (Float[Tensor, '_'] | Float[ndarray, '_'] | list[float] | list[int | float] | Int[Tensor, '_'] | Int[ndarray, '_'] | list[int] | None) – The sampling ratios that describe the coarser scales.
n_points (Int[Tensor, '_'] | Int[ndarray, '_'] | list[int] | None) – The target numbers of points for each coarser scale.
scales (Float[Tensor, '_'] | Float[ndarray, '_'] | list[float] | list[int | float] | Int[Tensor, '_'] | Int[ndarray, '_'] | list[int] | None) – The sampling scales that describe the coarser scales.
decimation_module – The decimation module that should be used to compute the coarser representations of the shape. If not provided, it is defined automatically.

Raises:

NotImplementedError – If the shape is not a triangle mesh.
ValueError – If none of the ratios, n_points or scales parameters are provided or if more than one of these parameters are provided.

Examples

import skshapes as sks

shape = sks.Sphere()
multiscale = sks.Multiscale(shape=shape, ratios=[0.5, 0.25])
# Note that the original shape is always included in the multiscale representation
# for a sampling ratio = 1.0
for ratio in multiscale.ratios:
    print(f"at ratio={ratio}, {multiscale.at(ratio=ratio).n_points} points")

at ratio=1.0, 842 points
at ratio=0.5, 421 points
at ratio=0.25, 210 points

See the gallery for more examples.

__init__(shape, ratios=None, n_points=None, scales=None, decimation_module=None)

Methods

`__init__`(shape[, ratios, n_points, scales, ...])
`append`(*[, ratio, n_points, scale])	Appends a new shape to the list of sub-sampled representations of the base shape.
`at`(*[, ratio, n_points, scale])	Returns the shape at a given ratio, number of points or scale.
`best_key`(*, ratio)	Return the best key in the shapes dictionary for a given, arbitrary ratio.
`index_mapping`(fine_ratio, coarse_ratio)	Returns the index mapping from a fine to a coarse resolution.
`propagate`(signal_name[, from_scale, ...])	Propagate a signal to the other scales.

Attributes

ratios

Return the available ratios of the shapes in the multiscale representation.

append(*, ratio=None, n_points=None, scale=None)

Appends a new shape to the list of sub-sampled representations of the base shape.

This function can be called with one of the ratio, n_points or scale parameters.

Parameters:

ratio (int | float | None) – The target ratio from the initial number of points.
n_points (int | None) – The target number of points.
scale (int | float | None) – The target scale.

Return type:

None

Examples

import skshapes as sks

shape = sks.Sphere()
multiscale = sks.Multiscale(shape=shape, ratios=[0.5])
multiscale.append(n_points=100)
# N.B.: the original shape is always included in the multiscale representation
#       for a sampling ratio = 1.0
for ratio in multiscale.ratios:
    print(f"at ratio={ratio:.3f}, {multiscale.at(ratio=ratio).n_points} points")

at ratio=1.000, 842 points
at ratio=0.500, 421 points
at ratio=0.119, 100 points

at(*, ratio=None, n_points=None, scale=None)

Returns the shape at a given ratio, number of points or scale.

If the shape at the given ratio, number of points or scale does not exist, returns most compact (= coarsest) shape that is at least as precise.

Return type:: polydata_type | image_type

Examples

import skshapes as sks

shape = sks.Sphere()  # The sphere has 842 points
multiscale = sks.Multiscale(shape=shape, n_points=[300, 100])
print(multiscale.at(n_points=200).n_points)

best_key(*, ratio)

Return the best key in the shapes dictionary for a given, arbitrary ratio.

This returns the smallest ratio (= most compact shape) which is still larger (= at least as precise) as the required sampling ratio.

Return type:: int | float

Examples

import skshapes as sks

shape = sks.Sphere()
multiscale = sks.Multiscale(shape=shape, ratios=[0.5, 0.25])
print(multiscale.best_key(ratio=0.6))
print(multiscale.best_key(ratio=0.3))

1.0
0.5

index_mapping(fine_ratio, coarse_ratio)

Returns the index mapping from a fine to a coarse resolution.

The index mapping is a 1d tensor of integers whose length is equal to the number of points at the fine resolution ratio. Each element of the tensor is the index of the corresponding point at the coarse resolution ratio. This method is used internally to propagate signals from one scale to another.

Parameters:

fine_ratio (int | float) – The ratio of the high resolution shape.
coarse_ratio (int | float) – The ratio of the low resolution shape.

Returns:

The index mapping from a fine to a coarse resolution.

Return type:

Int1dTensor

Examples

import skshapes as sks

shape = sks.Sphere()
multiscale = sks.Multiscale(shape=shape, ratios=[0.5, 0.25])
im = multiscale.index_mapping(fine_ratio=0.5, coarse_ratio=0.25)

print(f"{multiscale.at(ratio=0.5).n_points} = {im.shape},", im.dtype)

421 = torch.Size([421]), torch.int64

print(f"{multiscale.at(ratio=0.25).n_points} = {im.max()} + 1")

210 = 209 + 1

print(im[:10])

tensor([53,  0,  0,  7,  1,  2,  2,  3,  4,  4])

propagate(signal_name, from_scale=None, from_ratio=None, from_n_points=None, fine_to_coarse_policy=None, coarse_to_fine_policy=None)

Propagate a signal to the other scales.

The signal must be defined at the origin scale. The propagation is performed in both directions from the origin to the coarser scales and from the origin to the finer scales.

The propagation is parametrized by two policies: one for the fine to coarse propagation and one for the coarse to fine propagation. These policies are defined by the fine_to_coarse_policy and coarse_to_fine_policy parameters. If not provided, default policies are used. See the documentation of the [FineToCoarsePolicy][skshapes.types.FineToCoarsePolicy] and [CoarseToFinePolicy][skshapes.types.CoarseToFinePolicy] classes for more details.

Parameters:

signal_name (str) – The name of the signal to propagate.
from_scale (int | float | None) – The scale of the origin shape.
from_ratio (int | float | None) – The ratio of the origin shape.
from_n_points (int | None) – The number of points of the origin shape.
fine_to_coarse_policy (FineToCoarsePolicy | None) – The policy for the fine to coarse propagation.
coarse_to_fine_policy (CoarseToFinePolicy | None) – The policy for the coarse to fine propagation.

Return type:

None

Examples

See the Multiscaling and signal propagation tutorial for an example.

Return the available ratios of the shapes in the multiscale representation.

The ratios are sorted in decreasing order.

Examples

import skshapes as sks

shape = sks.Sphere()  # The sphere has 842 points
multiscale = sks.Multiscale(shape=shape, n_points=[400, 100])
# N.B.: the original shape is always included in the multiscale representation
#       for a sampling ratio = 1.0
print(multiscale.ratios)

[1.0, 0.4750593824228028, 0.1187648456057007]