Skip to main content

gaia/
lib.rs

1//! # gaia
2//!
3//! State-of-the-art watertight CFD mesh generation for millifluidic devices.
4//!
5//! This crate provides the canonical indexed and half-edge mesh representations,
6//! a complete Boolean CSG pipeline, spatial-hash vertex welding, exact
7//! geometric predicates, manifold/watertight checking, and OpenFOAM-compatible
8//! I/O — all targeting millimetre-scale microfluidic channel geometries.
9//!
10//! ## Quick Start
11//!
12//! ```rust,no_run
13//! // Illustrative — see MeshBuilder for the full builder API.
14//! use gaia::MeshBuilder;
15//! let mesh: gaia::IndexedMesh = MeshBuilder::new().build();
16//! assert!(mesh.face_count() == 0);
17//! ```
18//!
19//! ## Architecture Diagram
20//!
21//! ```text
22//! ┌─ gaia crate ─────────────────────────────────────────────────────────┐
23//! │                                                                           │
24//! │  Entry points                                                             │
25//! │  ┌──────────────────┐    ┌───────────────────┐    ┌──────────────────┐   │
26//! │  │  with_mesh(f)    │    │   MeshBuilder     │    │  csg_boolean_*   │   │
27//! │  │  HalfEdgeMesh    │    │   IndexedMesh     │    │  CsgNode tree    │   │
28//! │  └────────┬─────────┘    └────────┬──────────┘    └────────┬─────────┘   │
29//! │           │                       │                         │             │
30//! │  ┌────────▼─────────┐    ┌────────▼──────────┐   ┌────────▼──────────┐  │
31//! │  │ permission/      │    │ storage/           │   │ csg/              │  │
32//! │  │  GhostToken      │    │  VertexPool        │   │  BspTree          │  │
33//! │  │  GhostCell       │    │  FaceStore         │   │  BvhTree          │  │
34//! │  └────────┬─────────┘    │  EdgeStore         │   │  boolean pipeline │  │
35//! │           │              └────────┬──────────┘   └───────────────────┘  │
36//! │  ┌────────▼─────────┐            │                                       │
37//! │  │ topology/        │    ┌────────▼──────────┐                           │
38//! │  │  halfedge kernel │    │ geometry/          │                           │
39//! │  │  BoundaryPatch   │    │  exact predicates  │                           │
40//! │  │  ElementType     │    │  AABB, Plane, NURBS│                           │
41//! │  └──────────────────┘    └───────────────────┘                           │
42//! │                                                                           │
43//! │  Cross-cutting: welding/  watertight/  quality/  io/  core/              │
44//! └───────────────────────────────────────────────────────────────────────────┘
45//! ```
46//!
47//! ## Module Overview
48//!
49//! | Module | Contents |
50//! |--------|---------|
51//! | `domain::mesh` | `HalfEdgeMesh`, `IndexedMesh`, `MeshBuilder` |
52//! | `domain::topology` | Half-edge structures, boundary patches, element types |
53//! | `domain::geometry` | Exact predicates, AABB, plane, NURBS, builders |
54//! | `application::welding` | 26-neighbor `SnappingGrid`, `SpatialHashGrid`, `MeshWelder` |
55//! | `infrastructure::storage` | `VertexPool`, `FaceStore`, `EdgeStore`, `SlotPool` |
56//! | `application::watertight` | Manifold check, Euler characteristic, repair |
57//! | `application::quality` | Triangle quality metrics and validation reports |
58//! | `infrastructure::permission` | `GhostToken`, `GhostCell`, `PermissionedArena` |
59//! | [`core`] | Scalar types, indices (`VertexKey`, `VertexId`, …), errors |
60//! | `infrastructure::io` | STL and VTK mesh I/O |
61//! | `application::csg` | BSP-tree + BVH boolean operations |
62//!
63//! ## Invariants
64//!
65//! The following mesh invariants are enforced at all API boundaries:
66//!
67//! 1. **Manifold half-edge**: every interior edge is shared by exactly 2 faces;
68//!    `twin(twin(he)) == he` and `next(prev(he)) == he`.
69//! 2. **Spatial deduplication**: `VertexPool` and `SnappingGrid` guarantee that
70//!    no two vertex positions are closer than `TOLERANCE` apart.
71//! 3. **Watertight closure**: `IndexedMesh::is_watertight()` verifies zero
72//!    boundary edges (every edge has exactly 2 adjacent faces).
73//! 4. **Generational key safety**: `VertexKey` / `FaceKey` values are valid
74//!    only within the mesh that created them; stale keys return `None`.
75
76// The lint floor lives in Cargo.toml `[lints]`, where CI can deny it. The
77// block that used to sit here declared `warn` levels nothing ever ran under
78// `-D warnings`, so it enforced nothing; twelve of its allows were also dead
79// (the lints no longer fire, or no longer exist in the pedantic group).
80//
81// Test code is exempt from the panic-policy lint: an `unwrap()` in a test is
82// the assertion, not an input-dependent failure path. This is the crate-root
83// half of that carve-out; the example, bench, bin and integration-test targets
84// carry their own, since they are separate crates.
85#![cfg_attr(
86    test,
87    expect(
88        clippy::unwrap_used,
89        reason = "test code: an unwrap is the assertion, not an input-dependent failure path"
90    )
91)]
92// Test code is exempt from the float-comparison lint: exact float equality in
93// test assertions verifies IEEE-754 behaviour of specific computations (e.g.
94// that a GWN on an empty mesh is exactly 0.0, or that two constants derived
95// from the same formula agree bit-for-bit).
96#![cfg_attr(
97    test,
98    expect(
99        clippy::float_cmp,
100        reason = "test code: direct float equality assertions verify exact computed values and IEEE-754 properties"
101    )
102)]
103// Test code is exempt from integer-truncation and floating-point precision-loss
104// lints: test fixtures deliberately use raw casts to construct boundary values,
105// small mesh counts, and coordinate arrays that are known to be in range.
106#![cfg_attr(
107    test,
108    expect(
109        clippy::cast_possible_truncation,
110        reason = "test code: truncation casts in known-bounded test fixture values"
111    )
112)]
113#![cfg_attr(
114    test,
115    expect(
116        clippy::cast_precision_loss,
117        reason = "test code: precision-loss casts for test fixture coordinates and counts"
118    )
119)]
120
121pub mod application;
122pub mod domain;
123pub mod infrastructure;
124#[cfg(test)]
125pub mod test_support;
126
127/// Unified error type for all gaia operations.
128pub use domain::core::error::{Error, ErrorContext, NurbsKind, Result};
129
130/// Canonical watertight-first indexed surface mesh.
131pub use domain::mesh::IndexedMesh;
132
133/// Ergonomic builder for `IndexedMesh`.
134pub use domain::mesh::MeshBuilder;
135
136/// Validated tetrahedral volume-mesh builder.
137pub use domain::mesh::TetrahedralMeshBuilder;
138
139/// Branded half-edge surface mesh.
140pub use domain::mesh::HalfEdgeMesh;
141
142/// Canonical entry point for branded mesh operations.
143pub use domain::mesh::with_mesh;
144
145// ── Convenience re-exports ────────────────────────────────────────────────────
146
147/// Normal-orientation analysis report for `IndexedMesh` surfaces.
148pub use application::quality::{analyze_normals, NormalAnalysis};
149
150/// Named CFD boundary patch (Inlet / Outlet / Wall / Symmetry / Periodic).
151pub use domain::topology::halfedge::BoundaryPatch;
152
153/// CFD boundary patch type discriminant.
154pub use domain::topology::halfedge::PatchType;
155
156/// Open polyline — the canonical curve type for tractography streamlines.
157pub use domain::geometry::Polyline;
158
159/// Polyline construction and operation errors.
160pub use domain::geometry::PolylineError;
161
162/// Deterministic geodesic samples carrying a unit-vector invariant.
163pub use domain::geometry::UnitSphereDirectionSet;
164
165/// Exact Shewchuk orientation result.
166pub use domain::geometry::Orientation;
167
168/// Directed half-line with a normalized direction and its construction error.
169pub use domain::geometry::{Ray, RayError};
170
171/// Axis-aligned bounding box — the ray/voxel traversal companion to [`Ray`]
172/// (`Ray::intersect_aabb`), consumed by downstream imaging and dose ray-tracers.
173pub use domain::geometry::Aabb;
174
175/// Analytic mesh primitives (26 builders from tetrahedron to truncated icosahedron).
176pub use domain::geometry::primitives;
177
178/// Primitive builder re-exports for ergonomic top-level access.
179pub use domain::geometry::{
180    Antiprism,
181    BiconcaveDisk,
182    Capsule,
183    Cone,
184    Cube,
185    Cuboctahedron,
186    Cylinder,
187    Disk,
188    Dodecahedron,
189    Elbow,
190    Ellipsoid,
191    // TPMS expansion: Neovius, Lidinoid, I-WP, Split P, FRD, Fischer-Koch C(Y)
192    FischerKochCySphere,
193    FrdSphere,
194    Frustum,
195    GeodesicSphere,
196    GyroidSphere,
197    HelixSweep,
198    Icosahedron,
199    IwpSphere,
200    LidinoidSphere,
201    LinearSweep,
202    NeoviusSphere,
203    Octahedron,
204    Pipe,
205    Pyramid,
206    RevolutionSweep,
207    RoundedCube,
208    SchwarzDSphere,
209    SchwarzPSphere,
210    SerpentineTube,
211    SphericalShell,
212    SplitPSphere,
213    StadiumPrism,
214    Tetrahedron,
215    Torus,
216    TruncatedIcosahedron,
217    UvSphere,
218};
219
220/// Application-level channel builders.
221pub use application::channel::{
222    BranchingMeshBuilder, ChannelPath, ChannelPathError, ChannelProfile, SerpentineMeshBuilder,
223    SubstrateBuilder, SweepError, SweepMesher, VenturiMeshBuilder,
224};