Tensor product B-splines and NURBS

using TinyGismousing TinyGismo: knots, degree, basis, component, weights, weight

A tensor product basis is the outer product of one univariate basis per parametric direction. Each direction carries its own knot vector, so the degree, the number of elements and the refinement level can differ from direction to direction. Everything else — evaluation, refinement, degree elevation — behaves exactly as in the univariate case.

Building a tensor product basis

TensorBSplineBasis takes one KnotVector per direction. The parametric dimension is a type parameter and must be given explicitly:

kv_u = KnotVector([0.0, 0.0, 0.0, 1.0, 1.0, 1.0])  # quadratickv_v = KnotVector([0.0, 0.0, 1.0, 1.0])            # lineartb = TensorBSplineBasis{2}(kv_u, kv_v)

The size of the tensor basis is the product of the univariate sizes, and likewise for the element count:

(    size      = Int(size(tb)),               # 3 × 2    nelements = Int(numElements(tb)),    ntotal    = Int(numTotalElements(tb)),)
(size = 6, nelements = 1, ntotal = 1)

Direction-dependent queries take a 1-based direction index:

(degree(tb, 1), degree(tb, 2))
(2, 1)

Element counts are the exception: the second argument of numElements is a box side, not a direction. For per-direction counts go through the univariate component:

(Int(numElements(component(tb, 1))), Int(numElements(component(tb, 2))))
(1, 1)

TinyGismo.knots and TinyGismo.component reach into a single direction — the former gives the knot vector, the latter the whole univariate basis:

knotContainer(knots(tb, 1)), knotContainer(knots(tb, 2))
([0.0, 0.0, 0.0, 1.0, 1.0, 1.0], [0.0, 0.0, 1.0, 1.0])
u_basis = component(tb, 1)Int(size(u_basis)), degree(u_basis)
(3, 2)

A trivariate basis takes three knot vectors, and behaves the same way:

tb3 = TensorBSplineBasis{3}(kv_u, kv_v, kv_v)(    size      = Int(size(tb3)),    numActive = Int(numActive(tb3)),    degrees   = (degree(tb3, 1), degree(tb3, 2), degree(tb3, 3)),)
(size = 12, numActive = 12, degrees = (2, 1, 1))

Surfaces

TensorBSpline attaches control points to the basis. As in the univariate case there is one row per control point and one column per physical coordinate, but the rows are now ordered lexicographically with the first parametric direction running fastest: all $u$-indices for $v_1$, then all $u$-indices for $v_2$, and so on.

controlpoints = [0.0  0.0     # u1, v1                 0.5  0.4     # u2, v1                 1.0  0.0     # u3, v1                 0.0  1.0     # u1, v2                 0.5  1.4     # u2, v2                 1.0  1.0]    # u3, v2surface = TensorBSpline{2}(tb, controlpoints)(parDim = parDim(surface), targetDim = targetDim(surface), ncoefs = Int(coefsSize(surface)))
(parDim = 2, targetDim = 2, ncoefs = 6)

Evaluation takes one parameter per parametric direction:

x = gsMatrix()eval!(surface, [0.5, 0.5], x)toMatrix(x)
2×1 Matrix{Float64}:
 0.5
 0.7

The centre of the patch is pulled off the straight line $y = 0.5$ because the middle control points in both rows are offset — the surface is a curved sheet, not a bilinear patch.

Building a patch from its corners

There is also a corner-point form, which fills the given spline space with a quadrilateral patch. It expects a 4 × 3 matrix of three-dimensional corner points listed counterclockwise around the patch, and it produces a surface in 3D space (targetDim == 3) even when all four corners are coplanar:

kv_lin = KnotVector([0.0, 0.0, 1.0, 1.0])   # linear in both directionscorners = [0.0 0.0 0.0           4.0 0.0 0.0           3.0 2.0 0.0           1.0 2.0 0.0]trapezoid = TensorBSpline{2}(corners, kv_lin, kv_lin)targetDim(trapezoid), toMatrix(coefs(trapezoid))
(3, [0.0 0.0 0.0; 4.0 0.0 0.0; 1.0 2.0 0.0; 3.0 2.0 0.0])

The corners come back out at the corners of the parameter domain, and the interior is the bilinear blend of them:

map([[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0], [0.5, 0.5]]) do uv    x = gsMatrix()    eval!(trapezoid, uv, x)    uv => vec(toMatrix(x))end
5-element Vector{Pair{Vector{Float64}, Vector{Float64}}}:
 [0.0, 0.0] => [0.0, 0.0, 0.0]
 [1.0, 0.0] => [4.0, 0.0, 0.0]
 [1.0, 1.0] => [3.0, 2.0, 0.0]
 [0.0, 1.0] => [1.0, 2.0, 0.0]
 [0.5, 0.5] => [2.0, 1.0, 0.0]
The knot-vector constructors take a `gsMatrix`

TensorBSpline{2}(kv_u, kv_v, coefs) and its trivariate and rational siblings expect the coefficients as a gsMatrix rather than a Julia matrix. Fill one with TinyGismo.setValue! if you want that form; the TensorBSpline{N}(basis, coefs) form used throughout these examples is equivalent and takes a plain Julia matrix.

Volumes

A trivariate patch has three parametric directions. The row ordering of the control points extends the same way: $u$ fastest, then $v$, then $w$.

volume = createBSplineCube(1.0)(    parDim    = parDim(volume),    targetDim = targetDim(volume),    ncoefs    = Int(coefsSize(volume)),    degrees   = (degree(volume, 1), degree(volume, 2), degree(volume, 3)),)
(parDim = 3, targetDim = 3, ncoefs = 8, degrees = (1, 1, 1))
toMatrix(coefs(volume))
8×3 Matrix{Float64}:
 0.0  0.0  0.0
 1.0  0.0  0.0
 0.0  1.0  0.0
 1.0  1.0  0.0
 0.0  0.0  1.0
 1.0  0.0  1.0
 0.0  1.0  1.0
 1.0  1.0  1.0

Its basis is the TensorBSplineBasis{3} mentioned above:

vb = basis(volume)Int(size(vb)), Int(numElements(vb))
(8, 1)

Rational tensor product geometries

TensorNurbsBasis is a tensor B-spline basis plus one weight per basis function, supplied as a single-column matrix in the same lexicographic order as the control points:

w = 0.5 * sqrt(2)weightmatrix = reshape([1.0, w, 1.0, 1.0, w, 1.0], 6, 1)tnb = TensorNurbsBasis{2}(kv_u, kv_v, weightmatrix)Int(size(tnb))
6

Tensor product NURBS support the full geometry interface, as univariate Nurbs does. The quarter annulus is the standard example — an exact circular ring, which no polynomial B-spline can represent:

annulus = createNurbsQuarterAnnulus(1.0, 2.0)   # inner radius, outer radiustoMatrix(coefs(annulus))
6×2 Matrix{Float64}:
 1.0  0.0
 2.0  0.0
 1.0  1.0
 2.0  2.0
 0.0  1.0
 0.0  2.0

Reading the control points in the lexicographic order above shows how the patch is laid out: the first direction is radial (two control points, inner then outer) and the second is angular (three control points sweeping the quarter turn).

toVector(weights(annulus))
6-element Vector{Float64}:
 1.0
 1.0
 0.707106781186548
 0.707106781186548
 1.0
 1.0

The middle pair of weights is $\sqrt{2}/2$, the value that makes a quadratic rational Bézier segment trace a quarter circle exactly. Evaluating halfway along the inner edge — $u = 0$ is the inner radius, $v = 0.5$ is 45° — therefore lands exactly on the unit circle, which is where a polynomial approximation would fall short:

p = gsMatrix()eval!(annulus, [0.0, 0.5], p)point = toMatrix(p)point, sqrt(sum(abs2, point))
([0.7071067811865476; 0.7071067811865476;;], 1.0)

For a univariate Nurbs, TinyGismo.weight reads a single weight; on a tensor product geometry, index into the vector returned by weights or ask its basis, which carries the same weights:

circle = createNurbsCircle(1.0)weight(circle, 2), toVector(weights(annulus))[2], weight(basis(annulus), 2)
(0.707106781186548, 1.0, 1.0)

Parametric versus physical dimension

The two are independent, and tensor product geometries make that obvious. A NURBS sphere has two parametric directions but lives in three-dimensional space — it is a surface, not a volume, despite the name:

sphere = createNurbsSphere(1.0)(    parDim    = parDim(sphere),    targetDim = targetDim(sphere),    degrees   = (degree(sphere, 1), degree(sphere, 2)),)
(parDim = 2, targetDim = 3, degrees = (2, 2))

Its mesh is anisotropic — two elements around one direction, four around the other. TinyGismo.component is only available on B-spline bases, so on a rational basis count the spans in each knot vector instead:

sb = basis(sphere)elements(b, i) = length(unique(knotContainer(knots(b, i)))) - 1(elements(sb, 1), elements(sb, 2)), Int(numElements(sb))
((2, 4), 8)

A NURBS cube, by contrast, is genuinely trivariate:

nurbscube = createNurbsCube(1.0)parDim(nurbscube), targetDim(nurbscube)
(3, 3)

Because each direction carries its own knot vector, the two need not stay in step. Refining or elevating a single direction is covered in Refinement.