Creating geometries

using TinyGismousing TinyGismo: knots, degree, basis, order, unique

A spline geometry in TinyGismo is always built from two ingredients: a basis, which fixes the spline space, and a matrix of control points (coefficients), which places that space in physical space. The basis in turn is built from one knot vector per parametric direction.

This page walks that chain from the bottom up, and then shows the create* functions that skip it when you only need a standard shape.

Knot vectors

A KnotVector is a non-decreasing sequence of parameter values. Repeating a value raises its multiplicity, which lowers the continuity of the spline there; repeating the end values $p+1$ times gives the usual clamped (open) knot vector that interpolates the first and last control point.

kv = KnotVector([0.0, 0.0, 0.0, 0.5, 1.0, 1.0, 1.0])knotContainer(kv)
7-element Vector{Float64}:
 0.0
 0.0
 0.0
 0.5
 1.0
 1.0
 1.0

The degree is implied rather than stored: with 3 repetitions at each end, this is a quadratic knot vector. The queries below describe it:

(    nknots       = Int(size(kv)),        # counting multiplicities    nunique      = Int(uSize(kv)),       # distinct values    nelements    = Int(numElements(kv)), # non-empty knot spans)
(nknots = 7, nunique = 3, nelements = 2)

TinyGismo.unique gives the distinct breakpoints and multiplicities how often each occurs:

unique(kv), multiplicities(kv)
([0.0, 0.5, 1.0], Int32[3, 1, 3])

From knot vector to basis

BSplineBasis turns a knot vector into a univariate spline basis. The degree is deduced from the end multiplicities, and the number of basis functions follows as $n = m - p - 1$ for $m$ knots and degree $p$:

b = BSplineBasis(kv)(    degree    = degree(b),    order     = order(b),          # degree + 1    nfunctions = Int(size(b)),    nelements = Int(numElements(b)),)
(degree = 2, order = 0x00000003, nfunctions = 4, nelements = 2)

The basis keeps a reference to its knot vector, which you can read back:

knotContainer(knots(b))
7-element Vector{Float64}:
 0.0
 0.0
 0.0
 0.5
 1.0
 1.0
 1.0

From basis to geometry

BSpline combines the basis with a control point matrix. The matrix has one row per control point and one column per physical coordinate, so the number of rows must equal the number of basis functions:

controlpoints = [0.0  0.0                 1.0  1.5                 2.0 -0.5                 3.0  1.0]curve = BSpline(b, controlpoints)(    parDim    = parDim(curve),      # number of parameters    targetDim = targetDim(curve),   # dimension of the physical space    ncoefs    = Int(coefsSize(curve)),)
(parDim = 1, targetDim = 2, ncoefs = 4)

The column count is what decides the target dimension — the same basis with a single column of coefficients gives a scalar function of one parameter rather than a plane curve:

scalar = BSpline(b, [0.0, 1.0, -1.0, 0.5])parDim(scalar), targetDim(scalar)
(1, 1)

Evaluating the curve at a parameter gives a targetDim × npoints matrix:

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

Several parameters at once are passed as a 1 × n matrix — one column per point, which is the same layout the result uses:

u = collect(range(0.0, 1.0; length = 5))'  # 1 × 5X = gsMatrix()eval!(curve, Matrix(u), X)toMatrix(X)
2×5 Matrix{Float64}:
 0.0  0.875  1.5  2.125  3.0
 0.0  0.875  0.5  0.125  1.0

NURBS curves

NurbsBasis adds one weight per basis function. Weights let a spline reproduce conic sections exactly, which a polynomial B-spline cannot do:

w = 0.5 * sqrt(2)quarterarc = NurbsBasis(KnotVector([0.0, 0.0, 0.0, 1.0, 1.0, 1.0]), [1.0, w, 1.0])Int(size(quarterarc)), degree(quarterarc)
(3, 2)

Attaching control points gives a Nurbs curve, which supports the full geometry interface. A NURBS circle is the standard demonstration — it is exactly round, which a polynomial B-spline cannot manage:

circle = createNurbsCircle(1.0)p = gsMatrix()eval!(circle, [0.3], p)point = toMatrix(p)point, sqrt(sum(abs2, point))
([-0.2938119377115879; 0.9558632461069743;;], 1.0)

The weights are what make that possible:

toVector(TinyGismo.weights(circle))
9-element Vector{Float64}:
 1.0
 0.707106781186548
 1.0
 0.707106781186548
 1.0
 0.707106781186548
 1.0
 0.707106781186548
 1.0

The convenience functions

For standard shapes the create* factories skip the whole chain. They take positional arguments only — keyword arguments are not supported, because these functions come straight from the C++ layer.

rect = createBSplineRectangle(0.0, 0.0, 2.0, 1.0)   # low_x, low_y, upp_x, upp_y(parDim = parDim(rect), targetDim = targetDim(rect), ncoefs = Int(coefsSize(rect)))
(parDim = 2, targetDim = 2, ncoefs = 9)

Every argument has a default, so the bare call gives the unit shape:

toMatrix(coefs(createBSplineSquare()))
4×2 Matrix{Float64}:
 0.0  0.0
 1.0  0.0
 0.0  1.0
 1.0  1.0

The factories cover a range of parametric and physical dimensions. A quarter annulus is a rational surface in the plane:

annulus = createNurbsQuarterAnnulus(1.0, 2.0)   # inner radius, outer radius(typeof = nameof(typeof(annulus)), parDim = parDim(annulus), targetDim = targetDim(annulus))
(typeof = :TensorNurbsAllocated, parDim = 2, targetDim = 2)

a cube is a trivariate volume:

cube = createBSplineCube(1.0)(parDim = parDim(cube), targetDim = targetDim(cube), ncoefs = Int(coefsSize(cube)))
(parDim = 3, targetDim = 3, ncoefs = 8)

and a sphere is a surface — two parameters embedded in three-dimensional space:

sphere = createNurbsSphere(1.0)(parDim = parDim(sphere), targetDim = targetDim(sphere), ncoefs = Int(coefsSize(sphere)))
(parDim = 2, targetDim = 3, ncoefs = 45)

Note that "B-spline" in a factory name refers to the shape being polynomial, not to the parametric dimension: createBSplineFatCircle returns a curve in the plane, while createBSplineFatDisk returns a surface.

circleboundary = createBSplineFatCircle(1.0)disk = createBSplineFatDisk(1.0)(circle = parDim(circleboundary), disk = parDim(disk))
(circle = 1, disk = 2)

See Geometry Factories for the full list, including the test shapes (createBSplineAmoeba, createBSplineFish, createNurbsQrtPlateWHoleC0, …) that are not exported but reachable as TinyGismo.createBSplineFish().

Extracting boundaries

boundary pulls a side out of a geometry as a geometry of one lower parametric dimension. Sides are numbered in the G+Smo convention: 1 and 2 are the west and east edges ($u = 0$ and $u = 1$), 3 and 4 the south and north edges.

The result is a C++ unique_ptr to the abstract geometry base class, so dereference it with [] before using it:

west = boundary(rect, 1)[](parDim = parDim(west), targetDim = targetDim(west))
(parDim = 1, targetDim = 2)

The west edge of the $[0,2] \times [0,1]$ rectangle is the segment $x = 0$:

toMatrix(coefs(west))
3×2 Matrix{Float64}:
 0.0  0.0
 0.0  0.5
 0.0  1.0

Applied to a basis instead, boundary returns the indices of the basis functions that are nonzero on that side:

toVector(boundary(basis(rect), 1))
3-element Vector{Int32}:
 1
 4
 7