artist.core.regularizers

Classes

`Regularizer`	Initialize the base regularizer.
`TotalVariationRegularizer`	Initialize the total variation regularizer.
`IdealSurfaceRegularizer`	Initialize the ideal surface regularizer.

Module Contents

class artist.core.regularizers.Regularizer(weight: float, reduction_dimensions: tuple[int, Ellipsis])

Initialize the base regularizer.

Parameters

weightfloat: The weight of the regularization term.
reduction_dimensionstuple[int, …]: The dimensions along which to reduce the regularization term.

weight

reduction_dimensions

abstractmethod __call__(original_surface_points: torch.Tensor, surface_points: torch.Tensor, surface_normals: torch.Tensor, device: torch.device | None = None, **kwargs: Any) → torch.Tensor

Compute the regularization.

Parameters

original_surface_pointstorch.Tensor: The original surface points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].
surface_pointstorch.Tensor: The surface points of the predicted surface. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].
surface_normalstorch.Tensor: The surface normals of the predicted surface. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_normals, 4].
devicetorch.device | None: The device on which to perform computations or load tensors and models (default is None). If None, ARTIST will automatically select the most appropriate device (CUDA or CPU) based on availability and OS.
**kwargsAny: Keyword arguments.

Raises

NotImplementedError: This abstract method must be overridden.

class artist.core.regularizers.TotalVariationRegularizer(weight: float, reduction_dimensions: tuple[int, Ellipsis], surface: str, number_of_neighbors: int = 20, sigma: float | None = None, batch_size: int = 512, epsilon: float = 1e-08)

Bases: Regularizer

Initialize the total variation regularizer.

Parameters

weightfloat: The weight of the regularization term.
reduction_dimensionstuple[int, …]: The dimensions along which to reduce the regularization term.
surfacestr: Specifies which part of a surface is regularized (either the surface points or the surface normals).
number_of_neighborsint: The number of nearest neighbors to consider (default is 20).
sigmafloat | None: Determines how quickly the weight falls off as the distance increases (default is None).
batch_sizeint: Used to process smaller batches of points instead of creating full distance matrices for all points (default is 512).
epsilonfloat: A small value used to prevent divisions by zero (default is 1e-8).

weight

reduction_dimensions

surface

number_of_neighbors = 20

sigma = None

batch_size = 512

epsilon = 1e-08

__call__(original_surface_points: torch.Tensor, surface_points: torch.Tensor, surface_normals: torch.Tensor, device: torch.device | None = None, **kwargs: Any) → torch.Tensor

Compute the regularization.

This regularization suppresses the noise in the surface. It measures the noise in the surface by taking absolute differences in the z-values of the provided points. This loss implementation focuses on local smoothness by applying a Gaussian distance weight and thereby letting closer points contribute more.

Parameters

original_surface_pointstorch.Tensor: The original surface points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].
surface_pointstorch.Tensor: The surface points of the predicted surface. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].
surface_normalstorch.Tensor: The surface normals of the predicted surface. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_normals, 4].
devicetorch.device | None: The device on which to perform computations or load tensors and models (default is None). If None, ARTIST will automatically select the most appropriate device (CUDA or CPU) based on availability and OS.
**kwargsAny: Keyword arguments.

Returns

torch.Tensor: The total variation loss for all provided surfaces. Tensor of shape [number_of_surfaces].

class artist.core.regularizers.IdealSurfaceRegularizer(weight: float, reduction_dimensions: tuple[int, Ellipsis])

Bases: Regularizer

Initialize the ideal surface regularizer.

Parameters

weightfloat: The weight of the regularization term.
reduction_dimensionstuple[int, …]: The dimensions along which to reduce the regularization term.

weight

reduction_dimensions

__call__(original_surface_points: torch.Tensor, surface_points: torch.Tensor, surface_normals: torch.Tensor, device: torch.device | None = None, **kwargs: Any) → torch.Tensor

Compute the regularization.

This regularization suppresses large changes in the control points positions. The real surface is expected to be close to the ideal surface, therefore large changes are penalized.

Parameters

original_surface_pointstorch.Tensor: The original surface points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].
surface_pointstorch.Tensor: The surface points of the predicted surface. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].
surface_normalstorch.Tensor: The surface normals of the predicted surface. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_normals, 4].
devicetorch.device | None: The device on which to perform computations or load tensors and models (default is None). If None, ARTIST will automatically select the most appropriate device (CUDA or CPU) based on availability and OS.
**kwargsAny: Keyword arguments.

Returns

torch.Tensor: The differences from the predicted surfaces to the ideal surfaces. Tensor of shape [number_of_surfaces].