using Index = std::uint32_t;

Vertex and triangle index type. Caps a mesh at 2^31-1 vertices.

using Scalar = float;

Floating scalar; becomes double under -DRF_DOUBLE_PRECISION=ON.

struct Vec3 { Scalar x, y, z; };

Three-component position or direction.

struct Vec2 { Scalar u, v; };

Texture coordinate pair.

struct Tri { Index v[3]; };

One triangle as three vertex indices.

struct AABB { Vec3 lo, hi; bool empty() const; Vec3 extent() const; };

Axis-aligned bounding box; empty() is true before any point is added.

enum class Status { Ok, FileNotFound, ParseError, UnsupportedFormat, EmptyMesh, NonManifold, InvalidOption, OutOfRange, Cancelled, WriteFailed };

Ten outcomes; only Ok means success. Carried by every Result.

template<class T> class Result { explicit operator bool() const noexcept; Status status() const noexcept; const char* message() const noexcept; T& value(); T& operator*(); };

Error channel used instead of exceptions. Falsy unless status()==Status::Ok.

operator bool

true exactly when the call succeeded

message()

static log string, never null, wording may change in a patch

value()

undefined unless bool(*this) is true

class Mesh { std::vector<Vec3> positions; std::vector<Tri> triangles; std::vector<Vec3> normals; std::vector<Vec2> uv; ... };

Indexed triangle mesh as a plain struct with helper methods; fill the vectors directly if needed.

members: vertex_count(), triangle_count(), has_normals(), has_uv(), bounds(), clear(), reserve(), validate()

AABB bounds() const noexcept;

Recomputed in linear time each call; returns an empty box for an empty mesh, never inverted.

Result<void> validate() const;

Checks index ranges, non-finite coordinates and attribute sizes. Linear, allocation-free. Call once after building by hand.

returns Ok, or OutOfRange / InvalidOption describing the first problem.

MeshView(const Vec3* pos, std::size_t nverts, const Tri* tris, std::size_t ntris) noexcept; MeshView(const Mesh&) noexcept;

Non-owning read-only view for algorithms that never mutate. Accepted by Stats::of and SelfIntersection::find.

struct Stats { std::size_t vertices, triangles, edges, boundary_loops, components, non_manifold_edges, non_manifold_vertices; int euler_characteristic, genus; bool closed, manifold, oriented; double area, volume; AABB bounds; static Stats of(MeshView); };

One pass answering most pre-flight questions. genus is -1 and volume 0.0 when their precondition fails.

static Stats of(MeshView);

Single linear pass over the mesh building one temporary edge table.

std::size_t weld_vertices(Mesh&, Scalar tolerance);

Merge vertices within tolerance on every axis via a uniform grid. Zero merges exact duplicates only (right for STL).

mesh

mesh mutated in place

tolerance

cell size; 0 = exact duplicates

returns count of vertices removed

std::size_t remove_degenerate(Mesh&, Scalar min_area);

Drop triangles at or below min_area, including those with two equal indices. Scale min_area to your model.

min_area

area threshold, relative to model scale

returns count of triangles removed

std::size_t remove_duplicate_triangles(Mesh&);

Remove triangles that repeat the same index triple.

returns count removed

std::size_t remove_small_components(Mesh&, std::size_t min_triangles);

Delete connected components below the threshold - the usual way to clear scanner speckle before decimating.

returns count of components deleted

Result<std::size_t> orient_consistently(Mesh&);

Flood-fill each component and flip faces to agree; for a closed component, flip the whole if signed volume is negative.

returns count flipped, or Status::NonManifold when an edge has >2 faces

Result<std::size_t> fill_holes(Mesh&, std::size_t max_loop_edges);

Ear-clip every boundary loop up to max_loop_edges in its best-fit plane; non-planar loops get a centroid fan.

max_loop_edges

largest loop to close; 0 closes nothing (not an error)

returns count of loops closed

struct DecimateOptions { std::size_t target_triangles=0; float target_ratio=0; Scalar max_error=0; bool preserve_boundary=true; bool preserve_ridges=false; float ridge_angle_deg=40; float max_aspect_ratio=20; bool allow_topology_change=false; const std::vector<Index>* locked_vertices=nullptr; Progress progress=nullptr; unsigned threads=0; };

Collapse controls. At least one of target_triangles, target_ratio or max_error must be non-zero or run returns InvalidOption.

explicit Decimator(DecimateOptions opt); Result<DecimateReport> run(Mesh& mesh);

Quadric-error edge-collapse decimator. Reusable across meshes; no state survives a run.

struct DecimateReport { std::size_t collapses, triangles_before, triangles_after; double max_applied_error; bool target_reached; };

What a run did. target_reached==false with status Ok is normal when locks block the target.

struct RidgeOptions { float min_angle_deg=35; float max_angle_deg=175; std::size_t min_edges=4; bool include_boundary=true; unsigned smooth_passes=0; bool split_at_junctions=true; };

Thresholds for which edges qualify and how chains are cut.

enum class RidgeKind { Ridge, Valley, Boundary };

Convex, concave or boundary; a chain changing sign is split so no line is half and half.

struct Polyline { std::vector<Index> vertices; RidgeKind kind; float mean_angle_deg; bool closed; };

One ordered chain. closed is true when first and last vertex coincide; the repeat is not stored twice.

explicit RidgeExtractor(RidgeOptions opt); Result<RidgeSet> run(const Mesh& mesh) const;

Chains sharp edges into ordered ridge/valley polylines rather than an unsorted edge set.

struct FindOptions { bool ignore_adjacent=true; std::size_t max_pairs=0; unsigned threads=0; };

Controls for exact detection; max_pairs=0 finds all.

Result<std::vector<TriPair>> find(MeshView, const FindOptions& = {});

Exact, tolerance-free detection through a bounding-volume hierarchy. Reports a pair iff the two closed triangles share a point.

returns list of intersecting triangle-index pairs

Result<ResolveReport> resolve(Mesh&, const ResolveOptions& = {});

Experimental. Moves vertices out of contact, else deletes the smaller offending triangle and recloses. Churns on nested shells.

struct RemeshOptions { Scalar target_edge_length=0; unsigned iterations=5; float feature_angle_deg=40; bool project_to_input=true; bool preserve_boundary=true; Progress progress=nullptr; };

Isotropic remeshing controls. target_edge_length 0 means the input mean edge length.

explicit Remesher(RemeshOptions opt); Result<void> run(Mesh& mesh);

Split, collapse, flip and tangential relaxation for a fixed iteration count. Experimental; isotropic only.

enum class Format { Auto, Obj, Ply, Stl };

Chosen by file extension unless passed explicitly.

struct WriteOptions { Format format=Format::Auto; bool binary=true; int float_digits=7; bool write_normals=false; };

Output controls; binary is ignored for OBJ.

Result<Mesh> read(const std::string& path); Result<Mesh> read(const std::string& path, Format);

Load OBJ, PLY (ascii+binary) or binary/ascii STL. STL has no vertex sharing, so weld after reading one.

returns the loaded Mesh, or a Status describing the failure

Result<void> write(const Mesh&, const std::string& path); Result<void> write(const Mesh&, const std::string& path, const WriteOptions&);

Write by extension or explicit options. OBJ and PLY carry normals and one UV set; STL carries positions only.

using Progress = std::function<bool(float fraction, const char* stage)>;

Return false to cancel; leaves a valid intermediate mesh and returns Status::Cancelled. Called from the calling thread only.