artist.util.nurbs

Classes

NURBSSurfaces

Initialize NURBS surfaces.

Module Contents

class artist.util.nurbs.NURBSSurfaces(degrees: torch.Tensor, control_points: torch.Tensor, uniform: bool = True, device: torch.device | None = None)

Bases: torch.nn.Module

Initialize NURBS surfaces.

NURBS stands for Non-Uniform Rational B-Spline. NURBS allow for an efficient and precise reconstruction of the imperfect heliostat surfaces in the digital twin. This implementation of the NURBS is differentiable. The NURBS surfaces require a degree in two directions and control points. These parameters are used to create the NURBS surface. For more details, see the NURBS tutorial.

Parameters

degreestorch.Tensor: The spline degrees in u and then in v direction. Tensor of shape [2].
control_pointstorch.Tensor: The control points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_control_points_u_direction, number_of_control_points_v_direction, 3].
uniformbool: Indicates wether the NURBS are uniform or not (default is True (uniform)).
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.

degrees

control_points

uniform = True

number_of_surfaces

number_of_facets_per_surface

knot_vectors_u

knot_vectors_v

calculate_uniform_knot_vectors(direction: int, device: torch.device | None = None) → torch.Tensor | None

Calculate the knot vectors for all surfaces in one direction.

For our application, only uniform knot vectors are required. The knots range from zero to one and are distributed uniformly. The first knot (0) and the last knot (1) have full multiplicity, i.e., they are repeated as often as specified by the degree. This means the NURBS start and end in a control point.

Parameters

directionint: The NURBS surface direction u or v.
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.

Returns

torch.Tensor: The knot vectors.

find_spans(direction: int, evaluation_points: torch.Tensor, knot_vectors: torch.Tensor, device: torch.device | None = None) → torch.Tensor

Determine the knot spans in one direction.

To generate NURBS, the basis functions must be evaluated. However, some basis functions may be zero. To improve computational efficiency, basis functions that are zero are not computed. Therefore, the knot spans in which the evaluation point lies is first computed using this function. See The NURBS Book p. 68 for reference. If the knot vector is uniform, the spans can be computed more efficiently.

Parameters

directionint: The NURBS surface direction u or v.
evaluation_pointstorch.Tensor: The evaluation points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 2].
knot_vectorstorch.Tensor: The knot vector for the NURBS surfaces in a single direction. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_control_points_one_direction + degree_one_direction + 1].
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.

Returns

torch.Tensor: The knot spans. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points].

basis_functions_and_derivatives(direction: int, evaluation_points: torch.Tensor, knot_vectors: torch.Tensor, spans: torch.Tensor, nth_derivative: int = 1, device: torch.device | None = None) → list[list[torch.Tensor]]

Compute the nonzero derivatives of the basis functions up to the nth-derivative.

See The NURBS Book p. 72 for reference.

Parameters

directionint: The NURBS surface direction u or v.
evaluation_pointstorch.Tensor: The evaluation points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 2].
knot_vectorstorch.Tensor: Contains all the knots of the NURBS surfaces. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_control_points_one_direction + degree_one_direction + 1].
spanstorch.Tensor: The knot spans. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points].
nth_derivativeint: Specifies how many derivatives are calculated (default is 1).
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.

Returns

list[list[torch.Tensor]]: The derivatives of the basis functions.

_batched_gather_control_points(control_points: torch.Tensor, index_u: torch.Tensor, index_v: torch.Tensor, device: torch.device | None = None) → torch.Tensor

Gathers control points using batched 2D indices.

Parameters

control_pointstorch.Tensor: The control points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_control_points_u_direction, number_of_control_points_v_direction, 4].
index_utorch.Tensor: The indices in u direction. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points].
index_vtorch.Tensor: The indices in v direction. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points].
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.

Returns

torch.Tensor: The gathered control points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].

calculate_surface_points_and_normals(evaluation_points: torch.Tensor, device: torch.device | None = None) → tuple[torch.Tensor, torch.Tensor]

Calculate the surface points and normals of the NURBS surfaces.

Parameters

evaluation_pointstorch.Tensor: The evaluation points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 2].
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.

Returns

torch.Tensor: The surface points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].
torch.Tensor: The surface normals. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].

forward(evaluation_points: torch.Tensor, device: torch.device | None = None) → tuple[torch.Tensor, torch.Tensor]

Specify the forward operation of the NURBS, i.e., calculate the surface points and normals.

Parameters

evaluation_pointstorch.Tensor: The evaluation points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 2].
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.

Returns

torch.Tensor: The surface points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].
torch.Tensor: The surface normals. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].