nurbspy
Description
Python library for B-Spline and NURBS curves and surfaces, with analytical derivatives, geometric analysis and support for shape optimization. The classes and methods were inspired by the algorithms presented in The NURBS Book and the code uses vectorized NumPy operations, with optional Numba just-in-time compilation for faster basis-function evaluation.
nurbspy aims to be a simple NURBS library, not a fully fledged CAD kernel. If you need a powerful, open source CAD kernel we recommend you to check out the C++ OpenCascade library. If you feel that OpenCascade is too complex or you are not sure how to start using it, this repository might be useful for you!
📚 Documentation: https://turbo-sim.github.io/nurbspy/
Capabilities
nurbspy represents both curves and surfaces as rational or non-rational Bézier / B-Spline / NURBS geometries, built directly from control points, weights, and knot vectors. For both, it provides:
- Evaluation of coordinates and arbitrary-order analytical derivatives
- Curvature (and, for surfaces, mean and Gaussian curvature)
- Point projection / point inversion
- Optional interactive desktop and embedded geometry viewing/editing
- Matplotlib static and diagnostic plots
Curves additionally offer the tangent, normal, and binormal unit vectors (Frenet-Serret frame), torsion, and arc-length by numerical quadrature. Surfaces additionally offer unit normal vectors, u- and v-isoparametric curves, and constructors for common special surfaces: bilinear, ruled, extruded, revolution, and Coons.
nurbspy also works with real and complex data types natively, so shape derivatives can be computed to machine precision with the complex-step method instead of finite differences. This is useful for shape-optimization problems with many design variables that rely on gradient-based algorithms; nurbspy is, to our knowledge, the only Python NURBS package with native complex-number support.
An optional JAX backend (nurbspy.jax) additionally provides automatic differentiation and JIT compilation, see Installation.
For repeated JAX calculations at fixed knots and parameter locations,
prepare_curve and prepare_surface reuse polynomial basis tables while
control points and weights vary. prepare_surface_projection reuses the
initialization grid for repeated queries onto one fixed surface. See the
JAX performance guide
for usage, lifetimes, and tradeoffs.
See the documentation for the theory behind these capabilities (Bézier, B-Spline, NURBS, and G² continuity) and the examples gallery, with complete scripts and their numerical and graphical output.
Numbered tutorials
Start with basis functions, curves, and surfaces, ordered from simple geometry to construction, derivatives, projection, merging, and STL export. The scripts focus on the public APIs and display the relevant graphical features in one editor per script. Planar and spatial examples are separate, and every example retains a background grid. Display quality uses Auto by default, without a numerical resolution setting.
poetry run python demos/01_curves/01_bezier_planar.py
poetry run python demos/02_surfaces/01_bilinear_planar.py
The teaching scripts do not generate images, reports, or variable archives.
Use main(show=False) to reuse their figures from other Python code. STL files
are written only by the STL export example. See the Figure guide
for PNG export and self-contained read-only interactive HTML with fig.to_html().
To export matching PNG/HTML files for all curve and surface demos, run
python docs/export_demo_figures.py; outputs stay beside the corresponding demo folders.
Interactive geometry viewing and editing
The primary interactive geometry interface uses the shared visualization/
renderer. Desktop windows start no web server. Desktop visualization and Dash
embedding are included in the standard dependencies. Install from this checkout,
then run a curve or surface example:
poetry install
poetry run python demos/03_viewer/01_curve.py
poetry run python demos/03_viewer/02_surface.py
Set EDITABLE = True in either script for editing, or False for read-only
viewing. DISPLAY controls appearance, and display quality defaults to Auto.
import nurbspy as nrb
curve = nrb.NurbsCurve([nrb.Point(0, 0), nrb.Point(1, 2), nrb.Point(3, 0)])
curve.show()
edited = curve.edit()
if edited is not None:
edited.to_yaml("edited_curve.yaml")
View and edit use the same 3D/orthographic viewport, navigation dropdown, ViewCube, solid-colour defaults, diagnostics, and optional STL mesh display. Editors add direct X/Y/Z coordinates, constrained dragging, positive weights, and Reset. Original inputs are unchanged; Apply returns a new NumPy geometry, including for JAX inputs. YAML can restore that geometry through either backend. Editors support Shift-click/Shift-drag multi-selection, group dragging, and Undo/Redo for geometry edits. File dialogs are omitted.
For a host-owned Dash application, use
GeometryView or GeometryEditor. See the guide
and separate runnable examples. Existing
.plot() methods retain their Matplotlib signatures; use .show()/.edit()
for the new geometry experience or show(backend="matplotlib") explicitly.
Use nrb.Figure(geometry) to retain camera and appearance settings, combine named
geometries, save a self-contained YAML view, and export PNG files with the same
Three.js renderer. Headless export and scripted frame generation are described
in the figure guide.
Installation
The development version requires Python 3.12 or 3.13. Install the latest release from PyPI:
pip install nurbspy
The default installation uses NumPy and does not require Numba. To add optional acceleration:
pip install "nurbspy[numba]"
Numba is used automatically when it is available. Without it, the same
functions run with NumPy; the API and numerical algorithms are unchanged,
but evaluation can be slower. If Numba raises an import error (for example,
because it does not support the installed NumPy version), nurbspy warns
and uses NumPy. Installing the extra still requires versions compatible
with Numba's own NumPy constraints.
To also install the optional JAX backend and its supporting libraries:
pip install "nurbspy[jax]"
Use import nurbspy as nrb (or explicitly import nurbspy.numpy as nrb) for
the NumPy interface, or
import nurbspy.jax as nrb for the JAX interface. The default installation
does not install Numba or JAX. The JAX extra does not require Numba; both
extras can be installed with pip install "nurbspy[numba,jax]".
The JAX backend currently uses the CPU.
Verify the installation:
python -c "import nurbspy; print(nurbspy.__version__)"
If you installed the JAX extra, check it with:
python -c "import nurbspy.jax"
For installing from source, contributing, and running the test suite, see Getting started in the documentation.
Minimal working examples
NURBS curves
nurbspy can be used to create Bézier, B-Spline and NURBS curves. The type of curve depends on the arguments used to initialize the curve class. As an example, the following piece of code can be used to generate a degree four Bézier curve in two dimensions:
# Import packages
import numpy as np
import nurbspy as nrb
import matplotlib.pyplot as plt
# Define the array of control points
P = np.zeros((2,5))
P[:, 0] = [0.20, 0.50]
P[:, 1] = [0.40, 0.70]
P[:, 2] = [0.80, 0.60]
P[:, 3] = [0.80, 0.40]
P[:, 4] = [0.40, 0.20]
# Create and plot the Bezier curve
bezierCurve = nrb.NurbsCurve(control_points=P)
bezierCurve.plot()
plt.show()
If the installation was successful, you should be able to see the Bézier curve when you execute the previous code snippet.
Check out the documentation examples directory to see more examples showing the capabilities of the library and how to use them.
NURBS surfaces
Similarly, nurbspy can be used to create Bézier, B-Spline and NURBS surfaces. The type of surface depends on the arguments used to initialize the surface class. As an example, the following code snippet can be used to generate a simple Bézier surface of degree 3 in the u-direction and degree 2 in the v-direction:
# Import packages
import numpy as np
import nurbspy as nrb
import matplotlib.pyplot as plt
# Define the array of control points
n_dim, n, m = 3, 4, 3
P = np.zeros((n_dim, n, m))
# First row
P[:, 0, 0] = [0.00, 0.00, 0.00]
P[:, 1, 0] = [1.00, 0.00, 1.00]
P[:, 2, 0] = [2.00, 0.00, 1.00]
P[:, 3, 0] = [3.00, 0.00, 0.00]
# Second row
P[:, 0, 1] = [0.00, 1.00, 1.00]
P[:, 1, 1] = [1.00, 1.00, 2.00]
P[:, 2, 1] = [2.00, 1.00, 2.00]
P[:, 3, 1] = [3.00, 1.00, 1.00]
# Third row
P[:, 0, 2] = [0.00, 2.00, 0.00]
P[:, 1, 2] = [1.00, 2.00, 1.00]
P[:, 2, 2] = [2.00, 2.00, 1.00]
P[:, 3, 2] = [3.00, 2.00, 0.00]
# Create and plot the Bezier surface
bezierSurface = nrb.NurbsSurface(control_points=P)
bezierSurface.plot(control_points=True, isocurves_u=6, isocurves_v=6)
plt.show()
If the installation was successful, you should be able to see the Bézier surface when you execute the previous script.
Check out the documentation examples directory to see more examples showing the capabilities of the library and how to use them.
Development
The Python package lives under src/nurbspy. Install the checkout in editable
mode before running local scripts or tests:
python -m pip install -e . pytest
python -m pytest
To test both optional backends, install -e ".[numba,jax]" instead and run
python -m pytest --require-backend=numba --require-backend=jax.
poetry install --with dev --all-extras also installs the checkout in editable
mode; use poetry run python -m pytest in that environment.
Contact information
nurbspy was originally developed by Roberto Agromayor under the supervision of Associate Professor Lars O. Nord at the Norwegian University of Science and Technology (NTNU) as part of his PhD on turbomachinery shape optimization, and has since been maintained and extended. Please, drop us an email to roberto.agromayor@ntnu.no if you have questions about the code or you have a bug to report!
Development and citation
Roberto Agromayor is the main developer of nurbspy.
Citation metadata is provided in CITATION.cff. For version-specific reproducibility, also record the release or commit used.
Plotting with numerical backends
NumPy and JAX geometry share the Matplotlib plotting implementation. Plotting JAX models copies their current arrays to the host; it does not modify the model. Call plotting methods outside JIT-compiled or differentiated functions. Numerical evaluation and automatic differentiation remain on the selected backend.
Readable control points
Use immutable Point values directly through the existing constructor:
import nurbspy as nrb
curve = nrb.NurbsCurve(
control_points=[nrb.Point(0, 0), nrb.Point(1, 2), nrb.Point(3, 2), nrb.Point(4, 0)],
degree=3,
)
Lists and tuples of Point objects are converted once to backend arrays.
Weights are supplied separately. Reusing a Point does not link geometries.
Numeric lists, tuples, and arrays retain the existing coordinate-first convention
P[coordinate, point_index]; their layout is never guessed from shape or type.
The same Point is available from nurbspy, nurbspy.numpy, and nurbspy.jax.
Array-based construction continues to support arbitrary coordinate dimensions,
complex numbers, and JAX transformations. Point coordinates can also be complex
or scalar JAX values, including traced values inside differentiated functions.
For surfaces, supply a rectangular Point grid. The outer index advances in
u, the inner index in v, and weights[i][j] belongs to points[i][j]:
surface = nrb.NurbsSurface(control_points=[
[nrb.Point(0, 0, 0), nrb.Point(0, 1, 0)],
[nrb.Point(1, 0, 0), nrb.Point(1, 1, 1)],
[nrb.Point(2, 0, 0), nrb.Point(2, 1, 0)],
])
Internally this is still P[:, i, j]. Numerical arrays and nested numerical
lists retain shape (dimension, number_u, number_v). A flat Point sequence is
not a surface grid. Mixed Point/numeric input, ragged rows, inconsistent Point
dimensions, and mismatched weight grids raise clear errors.
Individual locations also accept Point: circular-arc centers, bilinear-patch
corners, and revolution-axis points. Direction vectors remain numerical arrays
or sequences. The bilinear helper retains its historical argument order:
P00=S(0,0), P01=S(1,0), P10=S(0,1), and P11=S(1,1).
Geometry files and STL export
NumPy and JAX curves/surfaces share YAML persistence. Trimesh and NetworkX are standard dependencies, so STL export works with a normal nurbspy installation. They are imported only when exporting; native tessellation does not load them.
curve.to_yaml("curve.yaml")
restored = nrb.NurbsCurve.from_yaml("curve.yaml")
vertices, faces = surface.tessellate(nu=80, nv=30)
surface.export("surface.stl", nu=80, nv=30)
For multi-patch shells, use nrb.export_stl(patches, "solid.stl", require_closed=True).
See geometry I/O for backend selection, sampling,
closure checks, and the limits of STL precision and solid validation.
Plot and export an exact NURBS torus and a sampled ruled-surface oloid:
python demos/02_surfaces/21_stl_torus.py --quality print
python demos/02_surfaces/22_stl_oloid.py --quality print
See the printing walkthrough for all sampling/export parameters, preview/fine presets, dimensions, and slicer units.
Metadata
Release files for nurbspy 1.7.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nurbspy-1.7.1.tar.gz | 617.3 kB | Without provenance | Details for nurbspy-1.7.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nurbspy-1.7.1-py3-none-any.whl | Python 3 | none | any | Details for nurbspy-1.7.1-py3-none-any.whl |
Total release size: 1.3 MB
Release files / nurbspy-1.7.1.tar.gz
| Download URL | nurbspy-1.7.1.tar.gz |
|---|---|
| Size | 617.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cc78edf20889ed9df36c7aeb247585fac0323ec9c991d1e925fbf02a22446572
|
|
BLAKE2b-256 checksum How to use checksums |
b29645483a8d8a7369e822de55fd336a500ae65a7c77042d59e7dfb72bfc9bf8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.4 CPython/3.12.16 Linux/7.0.0-1019-azure
|
Release files / nurbspy-1.7.1-py3-none-any.whl
| Download URL | nurbspy-1.7.1-py3-none-any.whl |
|---|---|
| Size | 655.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
149a29a6d0c83e79ddc121def8686d7dc8a353faed7dfd6893bca558e3f8e8dd
|
|
BLAKE2b-256 checksum How to use checksums |
bd54ed01c9cfeaf590ed339ea312980ae72d3eb12a238010ba64fc92ef431d04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.4 CPython/3.12.16 Linux/7.0.0-1019-azure
|
Security for nurbspy 1.7.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.