artist.nurbs.surfaces

Classes

NURBSSurfaces

Initialize NURBS surfaces.

Module Contents

class artist.nurbs.surfaces.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. Shape is [2].
control_pointstorch.Tensor: The control points. Shape is [number_of_surfaces, number_of_facets_per_surface, number_of_control_points_u_direction, number_of_control_points_v_direction, 3].
uniformbool: Indicates whether 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. Shape is [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. Shape is [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. Shape is [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. Shape is [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 2].
knot_vectorstorch.Tensor: Contains all the knots of the NURBS surfaces. Shape is [number_of_surfaces, number_of_facets_per_surface, number_of_control_points_one_direction + degree_one_direction + 1].
spanstorch.Tensor: The knot spans. Shape is [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

Gather control points using batched 2D indices.

Parameters

control_pointstorch.Tensor: The control points. Shape is [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. Shape is [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points].
index_vtorch.Tensor: The indices in v direction. Shape is [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. Shape is [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].

calculate_surface_points_and_normals(evaluation_points: torch.Tensor, canting: torch.Tensor, facet_translations: 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. Shape is [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. Shape is [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].
torch.Tensor: The surface normals. Shape is [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].

forward(evaluation_points: torch.Tensor, canting: torch.Tensor, facet_translations: 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. Shape is [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. Shape is [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].
torch.Tensor: The surface normals. Shape is [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4].