Architecture

meshio++ is one C++ core with six language surfaces on top of it and a set of tools built on those surfaces. This page is the map; every box below links to the page that owns it.

One C++ core

Everything compiles into a single object library, meshioplusplus_core_obj (C++20), and every optional dependency compiles out when it is absent, so the core is dependency-free by default. Four things live in it.

• The format registry — 43 readable and 46 writable formats, each a reader and a writer over the uniform mesh API, registered in one dispatch table (registry.cpp: format name to reader and writer, file extension to default format). The Python binding keeps one function per format and dispatches in Python; every flat binding (C, Fortran, Julia, R, WebAssembly, the native CLI) dispatches through this table, which is why a new C++ format must be registered there to be reachable from them.
• The operations layer — 34 mesh operations and 5 data operations, described below.
• The detail/ kernels — the shared machinery the formats and operations are built from: the face and edge tables (cell_faces, cell_edges), the single owners of cell indexing and region remapping (cell_index, region_remap), the marching-tetrahedra cutter, the spatial hash, the polyhedron kernel, the refinement templates and the provenance scope.
• The mesh backend — exactly one per build, selected by MESHIOPLUSPLUS_MESH_BACKEND: the meshio-mirroring MESHIO layout the Python wheel uses, the canonical NATIVE layout the WebAssembly build uses, or the Kratos-style KRATOS ModelPart. Formats, operations and bindings never touch a backend's own members; they go through the uniform mesh API, which is what lets one implementation compile under all three.

The in-memory model those pieces share is the Mesh data model: points, a list of homogeneous cell blocks, data aligned to points or to blocks, and named regions. Ragged cells (polygons and polyhedra) have their own representation and cross every flat binding as CSR arrays.

The operations layer

An operation is a computation on a mesh rather than a file format: it is written against the uniform mesh API only, parallelises its hot loop with parallel_for, and is exposed on every binding surface plus a CLI verb and an MCP tool. They group naturally.

Group	Operations
Inspection and topology	quality, stats, diff, extract_surface, extract_skin, reorder, transform, clean, merge, crop, split, partition, convert_cells
Refinement and coarsening	refine, undo_green, subdivide, agglomerate, decimate, decimate_volume
Remeshing and smoothing	remesh, remesh_volume, optimize_volume, smooth
Fields	interpolate, conservative_interpolate, gradient, hessian, estimate_error, data_integrate
Cutting, grids and distance	slice, isosurface, grid and voxelize, signed distance
Data operations	manage, average, calc, condition, info — the five that never touch geometry

Two things tie the operations together. Chains of them are described declaratively by the settings pipeline, whose typed layer (run_pipeline_steps) is the single owner of the step dispatch on every surface, and the sequence driver runs such a chain once per step of a transient dataset with at most one mesh alive at a time. Every write can carry a provenance record of where the mesh came from and what was done to it.

The language surfaces

• Python — the meshioplusplus._core pybind11 extension with zero-copy numpy at the I/O boundary, wrapped by one shim per format that falls back to the pure-Python reference implementation on any exception. This is the surface the Python CLI, the MCP server and the integrations are built on.
• C — libmeshioplusplus, a pure C99 header with SOVERSION 0 and append-only option structs, compiled under every mesh backend. Fortran, Julia and R ride on it, each in its own idiom for handles, ownership and indexing.
• WebAssembly — the @meshioplusplus/wasm npm package (embind over the NATIVE backend), in a sequential and a threaded build, working on a MEMFS virtual filesystem.
• C++ — the installable C++ API, one real library per backend exported into the same CMake package as the C API, under a deliberate ABI contract; or the single-header amalgamation for a build with no CMake at all.

The tools built on them

The Python CLI and the Python-free native CLI mirror each other verb for verb. The MCP server exposes the whole Python surface to AI agents as stateless, file-path-based tools. The browser viewer and dataset manager consume the published WebAssembly package, while the Polyscope viewer is a Python extra. The Blender add-on and ParaView plugin bring meshio++'s formats into those applications, and the interoperability, GPU, machine-learning, dataset and PhysicsNeMo layers hand meshes to the wider Python ecosystem without a file round-trip.

Two patterns that recur

A pure layer under gated wrappers. The interoperability, GPU, MCP, Blender and viewer modules all split the same way: the bulk of the logic is a pure payload layer that imports no optional library, mutates nothing and is tested in the default CI matrix with none of the targets installed, and the public functions are thin wrappers that import their target inside the function and raise a named install hint when it is missing. A feature that needs a heavy or version-pinned dependency never makes the core, or its tests, depend on it.

A single owner for anything two places could compute. The block-major cell index (detail/cell_index.hpp), the remapping of regions through an operation (detail/region_remap.hpp), the refinement templates, the marching cutter, the provenance credit line and the pipeline step dispatch each live in exactly one place and are reused by every consumer, including the numpy twins on the Python side, which are pinned byte-for-byte against the C++ path by tests. Where a second implementation would have to reproduce a discrete branch on a sign (a winding repair, a flip acceptance, a warp), the operation is C++-core only and says so by name.

Where to go next

Start with the quickstart, then the format table and the CLI reference. The roadmap lists what is not built yet.