geometries.nurbs

This package contains the mathematical basis for NURBS, adapted for the Optiland backend.

class NurbsGeometry(coordinate_system, radius=inf, conic=0.0, nurbs_norm_x=None, nurbs_norm_y=None, x_center=0.0, y_center=0.0, control_points=None, weights=None, u_degree=None, v_degree=None, u_knots=None, v_knots=None, n_points_u=4, n_points_v=4, tol=1e-10, max_iter=100)

Creates a NURBS (Non-Uniform Rational Basis Spline) geometry.

This class can be used to represent polynomial and rational Bézier, B-Spline, and NURBS surfaces. The type of surface depends on the initialization arguments.

Parameters:

• coordinate_system – The coordinate system of the geometry.

• radius – The radius of curvature of the base conic. (ignored if control points are passed)

• conic – The conic constant of the base conic. (ignored if control points are passed)

• nurbs_norm_x – Defines, along with nurbs_norm_y, x_center, and y_center, the rectangular area for the fit of the surface with the NURBS. If None, scales automatically during paraxial updates. Defaults to None.

• nurbs_norm_y – Defines, along with nurbs_norm_x, x_center, and y_center, the rectangular area for the fit of the surface with the NURBS. If None, scales automatically during paraxial updates. Defaults to None.

• x_center – Defines, along with nurbs_norm_x, nurbs_norm_y, and y_center, the rectangular area for the fit of the surface with the NURBS.

• y_center – Defines, along with nurbs_norm_x, nurbs_norm_y, and x_center, the rectangular area for the fit of the surface with the NURBS.

• control_points – An array with shape (ndim, n+1, m+1) containing the coordinates of the control points. The first dimension of ´P´ spans the coordinates of the control points (any number of dimensions), the second dimension of ´P´ spans the u-direction control points (0, 1, …, n), and the third dimension of ´P´ spans the v-direction control points (0, 1, …, m).

• weights – An array with shape (n+1, m+1) containing the weight of the control points. The first dimension of ´W´ spans the u-direction control points weights (0, 1, …, n), and the second dimension of ´W´ spans the v-direction control points weights (0, 1, …, m).

• u_degree – The degree of the u-basis polynomials.

• v_degree – The degree of the v-basis polynomials.

• u_knots – A knot vector in the u-direction with shape (r+1=n+p+2,). Set the multiplicity of the first and last entries equal to ´p+1´ to obtain a clamped spline.

• v_knots – A knot vector in the v-direction with shape (s+1=m+q+2,). Set the multiplicity of the first and last entries equal to ´q+1´ to obtain a clamped spline.

• n_points_u – Defines the grid size of control points (n_points_u x n_points_v). The default value is updated in case control points are passed.

• n_points_v – Defines the grid size of control points (n_points_u x n_points_v). The default value is updated in case control points are passed.

• tol – The tolerance for Newton-Raphson iteration.

• max_iter – The maximum number of iterations for Newton-Raphson.

References

• The NURBS Book. See references to equations and algorithms throughout the code. L. Piegl and W. Tiller. Springer, second edition.

• Curves and Surfaces for CADGD. See references to equations in the source code. G. Farin. Morgan Kaufmann Publishers, fifth edition.

• All references correspond to The NURBS book unless it is explicitly stated that they come from Farin’s book.

static compute_bspline_coordinates(P, p, q, U, V, u, v)

Evaluates the coordinates of the B-Spline surface.

This function computes the coordinates of a B-Spline surface as given by equation 3.11. See algorithm A3.5 in The NURBS Book.

Parameters:

• P – An array containing the coordinates of the control points.

• p – The degree of the u-basis polynomials.

• q – The degree of the v-basis polynomials.

• U – The knot vector in the u-direction.

• V – The knot vector in the v-direction.

• u – The u-parameter used to evaluate the surface.

• v – The v-parameter used to evaluate the surface.

Returns:

An array containing the B-Spline surface coordinates.

static compute_bspline_derivatives(P, p, q, U, V, u, v, up_to_order_u, up_to_order_v)

Computes the derivatives of a B-Spline surface.

This function computes the analytic derivatives of a B-Spline surface using equation 3.17. See algorithm A3.6 in The NURBS Book.

Parameters:

• P – An array containing the coordinates of the control points.

• p – The degree of the u-basis polynomials.

• q – The degree of the v-basis polynomials.

• U – The knot vector in the u-direction.

• V – The knot vector in the v-direction.

• u – The u-parameter used to evaluate the surface.

• v – The v-parameter used to evaluate the surface.

• up_to_order_u – The order of the highest derivative in the u-direction.

• up_to_order_v – The order of the highest derivative in the v-direction.

Returns:

An array containing the B-Spline surface derivatives.

static compute_nurbs_coordinates(P, W, p, q, U, V, u, v)

Evaluates the coordinates of the NURBS surface.

This function computes the coordinates of the NURBS surface in homogeneous space using equation 4.15 and then maps the coordinates to ordinary space using the perspective map given by equation 1.16. See algorithm A4.3 in The NURBS Book.

Parameters:

• P – An array containing the coordinates of the control points.

• W – An array containing the weight of the control points.

• p – The degree of the u-basis polynomials.

• q – The degree of the v-basis polynomials.

• U – The knot vector in the u-direction.

• V – The knot vector in the v-direction.

• u – The u-parameter used to evaluate the surface.

• v – The v-parameter used to evaluate the surface.

Returns:

An array containing the NURBS surface coordinates.

compute_nurbs_derivatives(P, W, p, q, U, V, u, v, up_to_order_u, up_to_order_v)

Computes the derivatives of a NURBS surface.

This function computes the analytic derivatives of the NURBS surface in ordinary space using equation 4.20 and the derivatives of the NURBS surface in homogeneous space obtained from compute_bspline_derivatives().

The derivatives are computed recursively in a fashion similar to algorithm A4.4 in The NURBS Book.

Parameters:

• P – An array containing the coordinates of the control points.

• W – An array containing the weight of the control points.

• p – The degree of the u-basis polynomials.

• q – The degree of the v-basis polynomials.

• U – The knot vector in the u-direction.

• V – The knot vector in the v-direction.

• u – The u-parameter used to evaluate the surface.

• v – The v-parameter used to evaluate the surface.

• up_to_order_u – The order of the highest derivative in the u-direction.

• up_to_order_v – The order of the highest derivative in the v-direction.

Returns:

An array containing the NURBS surface derivatives.

distance(rays)

Finds the propagation distance to the geometry for the given rays.

The approach is described in the paper “Practical ray tracing of trimmed NURBS surfaces” from William Martin etc.

Parameters:

rays – The rays for which to calculate the distance.

Returns:

An array of distances from each ray’s current position to its intersection point with the geometry.

fit_surface()

Handles the NURBS surface approximation.

This function calls specific functions depending on the nature of the surface that we want to fit. For the time being, standard surface and plane surface are implemented.

flip()

Flip the geometry.

This method changes the sign of the radius and the z-coordinate of the control points.

classmethod from_dict(data)

Create a geometry from a dictionary.

Parameters:

data (dict) – A dictionary containing the geometry data, including its ‘type’ and coordinate system ‘cs’.

Returns:

An instance of a specific geometry subclass created from the dictionary data.

Return type:

BaseGeometry

get_derivative(u, v, order_u, order_v)

Evaluates the derivative of the surface.

Parameters:

• u – The u-parameter used to evaluate the surface.

• v – The v-parameter used to evaluate the surface.

• order_u – The order of the partial derivative in the u-direction.

• order_v – The order of the partial derivative in the v-direction.

Returns:

An array containing the derivative of the desired order.

get_normals(u, v)

Evaluates the unitary vectors normal to the surface.

The definition of the unitary normal vector is given in section 19.2 of Farin’s textbook.

Parameters:

• u – The u-parameter used to evaluate the normals.

• v – The v-parameter used to evaluate the normals.

Returns:

An array containing the unitary vectors normal to the surface.

get_value(u, v)

Evaluates the coordinates of the surface.

Parameters:

• u – The u-parameter used to evaluate the surface.

• v – The v-parameter used to evaluate the surface.

Returns:

An array containing the coordinates of the surface.

globalize(rays)

Convert rays from the local coordinate system to the global coordinate system.

Parameters:

rays (RealRays) – The rays to convert.

localize(rays)

Convert rays from the global coordinate system to the local coordinate system.

Parameters:

rays (RealRays) – The rays to convert.

sag(x=0, y=0)

Computes the surface sag.

The sag is computed for a specific x,y from the z-coordinate of the intersection point between the ray with direction (0,0,1) and passing from (x,y,0) and the NURBS surface.

Parameters:

• x – The x-coordinate.

• y – The y-coordinate.

Returns:

The surface sag.

scale(scale_factor: float)

Scale the geometry parameters.

Parameters:

scale_factor (float) – The factor by which to scale the geometry.

set_radius(value: float) → None

Set the radius of curvature.

Parameters:

value (float) – The new radius of curvature.

surface_normal(rays)

Computes the surface normal.

Parameters:

rays – The rays for which to calculate the surface normal.

Returns:

A tuple containing the x, y, and z components of the surface normal.

to_dict()

Convert the geometry to a dictionary.

Returns:

The dictionary representation of the geometry.

Return type:

dict

update_normalization(semi_aperture: float) → None

Update the normalization attributes of the geometry based on its defined normalization_mode (‘auto’ or ‘manual’). Base geometry generally does not maintain a normalization radius.

Parameters:

semi_aperture (float) – The current semi-aperture of the surface.

approximate_surface(points, size_u, size_v, degree_u, degree_v, **kwargs)

Approximates a surface using a least-squares method.

This algorithm interpolates the corner control points and approximates the remaining control points. Please refer to Algorithm A9.7 of The NURBS Book (2nd Edition), pp.422-423 for details.

Parameters:

• points – The data points.

• size_u – The number of data points on the u-direction, \(r\).

• size_v – The number of data points on the v-direction, \(s\).

• degree_u – The degree of the output surface for the u-direction.

• degree_v – The degree of the output surface for the v-direction.

• **kwargs – Keyword arguments.

Returns:

The approximated B-Spline surface.