nurbspy.jax.nurbs_surface module

Differentiable tensor-product NURBS surfaces with the NumPy surface API.

class nurbspy.jax.nurbs_surface.NurbsSurface(control_points=None, weights=None, u_degree=None, v_degree=None, u_knots=None, v_knots=None)

Bases: Module

A differentiable surface with paired parameters and NumPy-compatible shapes.

control_points has shape (ndim, Nu, Nv), and weights has shape (Nu, Nv). Omitting degrees makes a Bezier patch; omitted knots are open uniform. Values and derivatives have shape (ndim, N), including (ndim, 1) for scalar parameters. To evaluate a grid, flatten an ij meshgrid.

Degrees and control-net dimensions are static. Points, weights and knots remain differentiable array leaves. Normals and curvature require a regular three-dimensional patch; they are undefined at singular points. Pass changing parameters as arrays to reuse compiled evaluations; Python scalar arguments are static under eqx.filter_jit, as in JAX curves.

Attributes:

U_mults

Multiplicities of distinct u knots for host-side CAD export.

U_values

Distinct u knots for host-side CAD export; unavailable inside JIT.

V_mults

Multiplicities of distinct v knots for host-side CAD export.

V_values

Distinct v knots for host-side CAD export; unavailable inside JIT.

Methods

PointToSurfaceProjectionProblem(S, dS, P)	Compatibility wrapper for the NumPy distance-objective helper.
attach_nurbs_udir(new_nurbs)	Attach a patch along u, mapping the originals to [0,.5] and [.5,1].
attach_nurbs_vdir(new_nurbs)	Attach a patch along v, mapping the originals to [0,.5] and [.5,1].
compute_bspline_coordinates(P, p, q, U, V, u, v)	Evaluate a polynomial patch at paired parameters, returning (ndim, N).
compute_bspline_derivatives(P, p, q, U, V, ...)	Return partials with shape (ku+1, kv+1, ndim, N), zero above each degree.
compute_nurbs_coordinates(P, W, p, q, U, V, u, v)	Evaluate a rational patch with control points (ndim, Nu, Nv) and weights (Nu, Nv).
compute_nurbs_derivatives(P, W, p, q, U, V, ...)	Return rational mixed partials through the requested orders.
get_curvature(u, v)	Return signed mean and Gaussian curvature, each with shape (N,).
get_derivative(u, v, order_u, order_v)	Evaluate the requested mixed partial; derivative orders are static.
get_isocurve_u(u0)	Return the rational curve S(u0,v), differentiable in scalar u0.
get_isocurve_v(v0)	Return the rational curve S(u,v0), differentiable in scalar v0.
get_normals(u, v)	Return oriented unit normals S_u cross S_v, with shape (3, N).
get_value(u, v)	Evaluate paired parameters as an array of shape (ndim, N).
plot([fig, ax, surface, surface_color, ...])	Plot on the host with the NumPy API; plotting is outside JIT and autodiff.
plot_boundary(fig, ax[, color, linewidth, ...])	Draw the four boundary curves on host axes.
plot_control_points(fig, ax[, color, ...])	Draw the control net on host axes.
plot_curvature([fig, ax, curvature_type])	Plot mean or Gaussian curvature over parameter space on the host.
plot_isocurve_u(fig, ax, u_values[, color, ...])	Draw sections with fixed u on host axes.
plot_isocurve_v(fig, ax, v_values[, color, ...])	Draw sections with fixed v on host axes.
plot_normals(fig, ax[, number_u, number_v, ...])	Draw sampled unit normals on host axes.
plot_surface(fig, ax[, color, alpha, ...])	Draw sampled surface values or curvature colors on host axes.
project_point_to_surface(P[, maxiter, ftol, ...])	Return a sampled single-start projection on the actual knot domain.
project_points(points[, maxiter, ftol, ...])	Project (ndim,N) queries; sample geometry once, return (2,N).
rescale_plot(fig, ax)	Set equal three-dimensional plot scales on the host.

P: Array

class PointToSurfaceProjectionProblem(S, dS, P)

Bases: object

Compatibility wrapper for the NumPy distance-objective helper.

Methods

fitness(x)	Return Euclidean distance in a length-one array.
get_bounds()	Return the normalized parameter bounds of the projection problem.
gradient(x)	Return the distance gradient, using zero at an exact intersection.

fitness(x)

Return Euclidean distance in a length-one array.

static get_bounds()

Return the normalized parameter bounds of the projection problem.

gradient(x)

Return the distance gradient, using zero at an exact intersection.

U: Array

property U_mults

Multiplicities of distinct u knots for host-side CAD export.

property U_values

Distinct u knots for host-side CAD export; unavailable inside JIT.

V: Array

property V_mults

Multiplicities of distinct v knots for host-side CAD export.

property V_values

Distinct v knots for host-side CAD export; unavailable inside JIT.

W: Array

attach_nurbs_udir(new_nurbs)

Attach a patch along u, mapping the originals to [0,.5] and [.5,1].

attach_nurbs_vdir(new_nurbs)

Attach a patch along v, mapping the originals to [0,.5] and [.5,1].

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

Evaluate a polynomial patch at paired parameters, returning (ndim, N).

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

Return partials with shape (ku+1, kv+1, ndim, N), zero above each degree.

Degrees and requested orders are nonnegative Python integers, fixed while tracing. Parameter derivatives at knots follow the basis span convention.

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

Evaluate a rational patch with control points (ndim, Nu, Nv) and weights (Nu, Nv).

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

Return rational mixed partials through the requested orders.

The output has shape (ku+1, kv+1, ndim, N). Unlike polynomial partials, rational partials may be nonzero above either degree. Differentiating the identity w*S=A gives the two-dimensional quotient-rule recurrence.

get_curvature(u, v)

Return signed mean and Gaussian curvature, each with shape (N,).

get_derivative(u, v, order_u, order_v)

Evaluate the requested mixed partial; derivative orders are static.

get_isocurve_u(u0)

Return the rational curve S(u0,v), differentiable in scalar u0.

get_isocurve_v(v0)

Return the rational curve S(u,v0), differentiable in scalar v0.

get_normals(u, v)

Return oriented unit normals S_u cross S_v, with shape (3, N).

get_value(u, v)

Evaluate paired parameters as an array of shape (ndim, N).

ndim: int

p: int

plot(fig=None, ax=None, surface=True, surface_color='blue', colorbar=False, boundary=True, control_points=False, normals=False, axis_off=False, ticks_off=False, Nu=50, Nv=50, isocurves_u=None, isocurves_v=None)

Plot on the host with the NumPy API; plotting is outside JIT and autodiff.

plot_boundary(fig, ax, color='black', linewidth=1.0, linestyle='-', south=True, north=True, east=True, west=True)

Draw the four boundary curves on host axes.

plot_control_points(fig, ax, color='red', linewidth=1.0, linestyle='-', markersize=5, markerstyle='o')

Draw the control net on host axes.

plot_curvature(fig=None, ax=None, curvature_type='mean')

Plot mean or Gaussian curvature over parameter space on the host.

plot_isocurve_u(fig, ax, u_values, color='black', linewidth=1.0, linestyle='-')

Draw sections with fixed u on host axes.

plot_isocurve_v(fig, ax, v_values, color='black', linewidth=1.0, linestyle='-')

Draw sections with fixed v on host axes.

plot_normals(fig, ax, number_u=10, number_v=10, scale=0.075)

Draw sampled unit normals on host axes.

plot_surface(fig, ax, color='blue', alpha=0.3, colorbar=False, Nu=50, Nv=50)

Draw sampled surface values or curvature colors on host axes.

project_point_to_surface(P, maxiter=200, ftol=1e-06, gtol=1e-06, *, samples_per_span=8, xtol=1e-12)

Return a sampled single-start projection on the actual knot domain.

The closest sampled surface point starts one bounded local Newton solve. There is no multistart mode or hidden restart. gtol bounds tangent-scaled spatial stationarity relative to 1 + distance; ftol/xtol detect stagnation, never convergence on their own. A failed solve raises an error. Sampling cannot certify global optimality.

Exact implicit derivatives support query and geometry sensitivities at a locally unique regular minimum with stable active bounds. Weak-bound transitions, nonsmooth knots and singular reduced Hessians yield NaN sensitivities. The existing positional arguments remain supported.

project_points(points, maxiter=200, ftol=1e-06, gtol=1e-06, *, samples_per_span=8, xtol=1e-12)

Project (ndim,N) queries; sample geometry once, return (2,N).

Requires finite geometry, positive weights and continuous knot vectors. samples_per_span is an interior budget for each knot span/axis. See project_point_to_surface for convergence and AD assumptions.

q: int

rescale_plot(fig, ax)

Set equal three-dimensional plot scales on the host.

surface_type: str

nurbspy.jax.nurbs_surface.make_offset_surface(surface, offset)

Approximate S-offset*N with a sampled polynomial control net.

Match the NumPy algorithm: use ten times as many control points in each direction, retain the degrees, and use uniform clamped knots. This is exact for planes but is not an exact general NURBS offset construction.