artist.core.regularizers ======================== .. py:module:: artist.core.regularizers Classes ------- .. autoapisummary:: artist.core.regularizers.Regularizer artist.core.regularizers.TotalVariationRegularizer artist.core.regularizers.IdealSurfaceRegularizer Module Contents --------------- .. py:class:: Regularizer(weight: float, reduction_dimensions: tuple[int, Ellipsis]) Initialize the base regularizer. Parameters ---------- weight : float The weight of the regularization term. reduction_dimensions : tuple[int, ...] The dimensions along which to reduce the regularization term. .. py:attribute:: weight .. py:attribute:: reduction_dimensions .. py:method:: __call__(original_surface_points: torch.Tensor, surface_points: torch.Tensor, surface_normals: torch.Tensor, device: torch.device | None = None, **kwargs: Any) -> torch.Tensor :abstractmethod: Compute the regularization. Parameters ---------- original_surface_points : torch.Tensor The original surface points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4]. surface_points : torch.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_normals : torch.Tensor The surface normals of the predicted surface. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_normals, 4]. device : torch.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. \*\*kwargs : Any Keyword arguments. Raises ------ NotImplementedError This abstract method must be overridden. .. py:class:: 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: :py:obj:`Regularizer` Initialize the total variation regularizer. Parameters ---------- weight : float The weight of the regularization term. reduction_dimensions : tuple[int, ...] The dimensions along which to reduce the regularization term. surface : str Specifies which part of a surface is regularized (either the surface points or the surface normals). number_of_neighbors : int The number of nearest neighbors to consider (default is 20). sigma : float | None Determines how quickly the weight falls off as the distance increases (default is None). batch_size : int Used to process smaller batches of points instead of creating full distance matrices for all points (default is 512). epsilon : float A small value used to prevent divisions by zero (default is 1e-8). .. py:attribute:: weight .. py:attribute:: reduction_dimensions .. py:attribute:: surface .. py:attribute:: number_of_neighbors :value: 20 .. py:attribute:: sigma :value: None .. py:attribute:: batch_size :value: 512 .. py:attribute:: epsilon :value: 1e-08 .. py:method:: __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_points : torch.Tensor The original surface points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4]. surface_points : torch.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_normals : torch.Tensor The surface normals of the predicted surface. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_normals, 4]. device : torch.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. \*\*kwargs : Any Keyword arguments. Returns ------- torch.Tensor The total variation loss for all provided surfaces. Tensor of shape [number_of_surfaces]. .. py:class:: IdealSurfaceRegularizer(weight: float, reduction_dimensions: tuple[int, Ellipsis]) Bases: :py:obj:`Regularizer` Initialize the ideal surface regularizer. Parameters ---------- weight : float The weight of the regularization term. reduction_dimensions : tuple[int, ...] The dimensions along which to reduce the regularization term. .. py:attribute:: weight .. py:attribute:: reduction_dimensions .. py:method:: __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_points : torch.Tensor The original surface points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4]. surface_points : torch.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_normals : torch.Tensor The surface normals of the predicted surface. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_normals, 4]. device : torch.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. \*\*kwargs : Any Keyword arguments. Returns ------- torch.Tensor The differences from the predicted surfaces to the ideal surfaces. Tensor of shape [number_of_surfaces].