artist.util.nurbs ================= .. py:module:: artist.util.nurbs Classes ------- .. autoapisummary:: artist.util.nurbs.NURBSSurfaces Module Contents --------------- .. py:class:: NURBSSurfaces(degrees: torch.Tensor, control_points: torch.Tensor, uniform: bool = True, device: torch.device | None = None) Bases: :py:obj:`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 ---------- degrees : torch.Tensor The spline degrees in u and then in v direction. Tensor of shape [2]. control_points : torch.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]. uniform : bool Indicates wether the NURBS are uniform or not (default is True (uniform)). 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. .. py:attribute:: degrees .. py:attribute:: control_points .. py:attribute:: uniform :value: True .. py:attribute:: number_of_surfaces .. py:attribute:: number_of_facets_per_surface .. py:attribute:: knot_vectors_u .. py:attribute:: knot_vectors_v .. py:method:: 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 ---------- direction : int The NURBS surface direction u or v. 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. Returns ------- torch.Tensor The knot vectors. .. py:method:: 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 ---------- direction : int The NURBS surface direction u or v. evaluation_points : torch.Tensor The evaluation points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 2]. knot_vectors : torch.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]. 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. Returns ------- torch.Tensor The knot spans. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points]. .. py:method:: 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 ---------- direction : int The NURBS surface direction u or v. evaluation_points : torch.Tensor The evaluation points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 2]. knot_vectors : torch.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]. spans : torch.Tensor The knot spans. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points]. nth_derivative : int Specifies how many derivatives are calculated (default is 1). 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. Returns ------- list[list[torch.Tensor]] The derivatives of the basis functions. .. py:method:: _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_points : torch.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_u : torch.Tensor The indices in u direction. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points]. index_v : torch.Tensor The indices in v direction. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points]. 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. Returns ------- torch.Tensor The gathered control points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4]. .. py:method:: 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_points : torch.Tensor The evaluation points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 2]. 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. 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]. .. py:method:: 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_points : torch.Tensor The evaluation points. Tensor of shape [number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 2]. 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. 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].