artist.nurbs.surfaces ===================== .. py:module:: artist.nurbs.surfaces Classes ------- .. autoapisummary:: artist.nurbs.surfaces.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. Shape is ``[2]``. control_points : torch.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]``. uniform : bool Indicates whether 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. Shape is ``[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. Shape is ``[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. Shape is ``[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. Shape is ``[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. Shape is ``[number_of_surfaces, number_of_facets_per_surface, number_of_control_points_one_direction + degree_one_direction + 1]``. spans : torch.Tensor The knot spans. Shape is ``[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 Gather control points using batched 2D indices. Parameters ---------- control_points : torch.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_u : torch.Tensor The indices in u direction. Shape is ``[number_of_surfaces, number_of_facets_per_surface, number_of_surface_points]``. index_v : torch.Tensor The indices in v direction. Shape is ``[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. Shape is ``[number_of_surfaces, number_of_facets_per_surface, number_of_surface_points, 4]``. .. py:method:: 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_points : torch.Tensor The evaluation points. Shape is ``[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. 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]``. .. py:method:: 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_points : torch.Tensor The evaluation points. Shape is ``[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. 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]``.