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};