ordito 0.1.0

ordito puts mesh processing on the GPU. Geometry, topology, repair, remeshing, spatial queries, discrete differential operators, geodesics, point-cloud reconstruction, and registration — as plain array-in / array-out functions backed by NVIDIA Warp kernels, with a trimesh-inspired API. Every function runs on CUDA when a GPU is available and falls back to CPU otherwise, with the same code.

Ordito (or-DEE-toh) is Italian for the warp of a fabric, and an anagram of toroid: a fitting name for a mesh library built on Warp.

Highlights

• One dependency. The runtime depends on warp-lang alone; NumPy comes with Warp; nothing else (no SciPy, PyTorch or trimesh) is needed at runtime.
• Broad coverage. Hundreds of functions across dozens of public modules, spanning primitives, topology, repair, remeshing, spatial queries, discrete differential operators, geodesics, sampling, surface reconstruction, and registration.
• Stays on the device. Functions take Warp arrays and return Warp arrays, so pipelines compose without host round-trips; device placement follows the inputs.
• Optional Trimesh object. A frozen mesh class with lazily cached derived quantities (normals, adjacency, boundary loops, manifoldness and watertightness predicates, BVH) for when an object API is more convenient than free functions.
• Fully typed (py.typed), documented per module at https://lucagrementieri.github.io/ordito/, and validated function-by-function against eleven reference implementations — nine established geometry-processing libraries plus SciPy and NumPy (see below).

Learn more

• Getting started — install, the mental model, and a first repair-then-remesh pipeline.
• Examples — a gallery of runnable examples with the images they produce: cleaning a scan, point clouds to watertight surfaces, geodesic distance fields, aligning two scans, and many more.
• Migrating from another library — already know trimesh, libigl, Open3D, MeshLab, potpourri3d, or PyTorch3D? Start here for a function-by-function map.
• Performance — why the GPU path is fast, and how to check any speed claim yourself.

One GPU library instead of nine

Mesh processing in Python has long meant stitching together several excellent — but mostly CPU-bound and stylistically different — libraries. ordito consolidates the functionality it needs from each of them behind a single GPU-accelerated API:

SciPy's spatial.KDTree and sparse.csgraph (covered by neighbors, graph and proximity) and NumPy's array primitives (array, reduce, grouping, linalg) round the set out to the eleven reference implementations the suite measures against.

These libraries are not runtime dependencies; they are test oracles. Wherever one of them computes the same quantity as an ordito function, a regression test compares the two outputs value by value. A parity gate in the test suite fails the build if any library the benchmarks time against ordito is neither compared in a test nor exempted with a written reason. Every (group, library) pair in the benchmark suite is either covered by a value test or carries a written exemption (typically a different algorithm answering a related question); none are uncovered, and python -m tests.parity prints the current matrix. Where ordito and a reference disagree by definition rather than by rounding (a sign convention, a squared distance), the docstring says so and the test pins the difference.

Install

uv add ordito

or with pip:

pip install ordito

Requires Python ≥ 3.11 and warp-lang ≥ 1.18. A CUDA-capable GPU is recommended but not required — every function also runs on Warp's CPU backend. Mesh file I/O via meshio is an optional extra: pip install "ordito[io]".

Tested on Linux, with and without CUDA, and on macOS (Apple Silicon, CPU backend). The wheel is pure Python and warp-lang supports Windows, so ordito is expected to work there, but it is not verified — see Platform support.

Quickstart

import ordito as od

# Parametric primitives allocate directly on the default device (CUDA if available).
vertices, faces = od.creation.icosphere(subdivisions=4)

# Optional object API: derived quantities are computed on first access and cached.
mesh = od.Trimesh(vertices, faces)
print(f"{mesh.area:.4f}")  # 12.5514
print(mesh.is_watertight)  # True
print(mesh.euler_characteristic)  # 2

Everything the Trimesh class offers is also available as free functions over raw Warp arrays, so pipelines stay on the device end to end:

import numpy as np
import warp as wp

import ordito as od

vertices, faces = od.creation.icosphere(subdivisions=4)

# Geodesic distance from vertex 0 via the heat method (two sparse solves, on the device).
sources = wp.array([0], dtype=wp.int32, device=vertices.device)
distance = od.heat.heat_geodesic(vertices, faces, sources)

# Uniform, area-weighted surface sampling.
points, face_ids = od.sample.sample_surface(vertices, faces, 10_000, seed=0)

# Feature-preserving isotropic remeshing (split / collapse / flip / smooth / reproject).
remeshed_vertices, remeshed_faces = od.remesh.isotropic_remesh(vertices, faces, target_length=0.05)

Interop with NumPy is a wp.array(...) / .numpy() pair away, and od.mesh.Trimesh.from_warp_mesh / mesh.warp_mesh bridge to Warp's own wp.Mesh BVH for ray and proximity queries. For a pipeline that starts from a realistically messy input — a hole to close, stray debris to drop — see the one-call watertight solid example.

What's inside

50 public modules in total — the full API reference, generated per module, lives at https://lucagrementieri.github.io/ordito/.

Design

• Arrays in, arrays out. The core API is free functions over wp.array buffers — no mandatory mesh object, no hidden state. Faces are a flat int32 index buffer, vertices a wp.vec3 array, the same convention everywhere.
• The device follows the data. Every kernel launch and allocation inherits the device of its inputs; there are no global device switches.
• Host syncs are budgeted. Wrappers avoid device-to-host readbacks, and where one is unavoidable the reason is documented; bounds a caller already knows can be passed in to skip the inference.
• Measured, not assumed. Every public module has both a test file and a benchmark file; performance work lands only with a before/after measurement, and correctness is asserted on values, never just shapes.

Status

ordito is pre-1.0 (0.x): the test suite is extensive (thousands of tests per device, an eleven-library parity gate with no uncovered pair) and the library is safe to build on, but a public signature may still shift a positional argument to a keyword or gain a required parameter between minor versions until 1.0. Released versions are recorded in CHANGELOG.md.

Development

git clone https://github.com/lucagrementieri/ordito
cd ordito
uv sync --all-groups            # runtime + dev + test + docs + bench dependencies

uv run pytest                   # regression tests against the reference libraries
uv run ruff format ordito tests && uv run ruff check ordito tests
uv run basedpyright             # type checking (0 errors expected)

uv run zensical serve           # preview the docs locally

uv run pytest --device=cpu -n 4 --cov=ordito   # coverage, the way CI measures it

The coverage badge measures the Python wrapper layer on the CPU backend, which is what CI can run, and is refreshed by the main build. It deliberately excludes ordito/kernels/: a @wp.kernel body is compiled from its AST and executed on the device, never called as Python, so coverage.py reports every line of a constantly-running kernel as unexecuted. Device-side behaviour is covered instead by running the suite on both backends (uv run python -m tests.devices), which is a two-process job and needs a GPU.

The test environment installs the reference stack (trimesh, libigl, Open3D, potpourri3d, PyMeshLab, PyVista, MeshLib, PyMeshFix, PyTorch3D, SciPy, and more) so the comparison suite runs in full. Benchmarks live in benchmarks/ and use pytest-benchmark; PyTorch3D is the one reference with CUDA kernels of its own, so it is also the suite's only GPU-against-GPU comparison. To reproduce them, follow benchmarks/README.md § Reproduce: a two-step install, then uv run pytest benchmarks/. The scan meshes are downloaded on first use from the meshes-v1 release and checked against pinned SHA-256 hashes.

Bug reports, reproductions and pull requests are welcome — see CONTRIBUTING.md for the development loop, the bar a pull request has to clear, and where the internal engineering reference lives.

Links

• Documentation: https://lucagrementieri.github.io/ordito/
• Source: https://github.com/lucagrementieri/ordito
• Issues: https://github.com/lucagrementieri/ordito/issues
• NVIDIA Warp: https://nvidia.github.io/warp/

Citation

If ordito is useful in your research, please cite it:

@software{grementieri_ordito,
  author  = {Grementieri, Luca},
  title   = {{ordito}: GPU-accelerated triangular mesh processing on NVIDIA Warp},
  year    = {2026},
  url     = {https://github.com/lucagrementieri/ordito},
  version = {0.1.0}
}

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in ordito by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.