.git/MERGE_MSG

doc/architecture/overall_pipeline.md

@@ -0,0 +1,110 @@
+Draft
+
+
+
+High-level geometry pipeline
+The following diagram sketches the planned high-level geometry pipeline for ConformalLab++. It shows how different input types are funneled through adapter layers into a universal half-edge mesh representation, processed by the core, and then exported or visualized.
+
+text
+graph TD
+    A["INPUT SOURCES"]
+    A1["Explicit<br/>(OBJ, PLY, STL)"]
+    A2["Implicit<br/>(SDF, Formulas)"]
+    A3["Parametric<br/>(NURBS, Curves)"]
+    A4["Procedural<br/>(Noise, L-Sys)"]
+    
+    A --> A1
+    A --> A2
+    A --> A3
+    A --> A4
+    
+    A1 --> ADAPTER1["Adapter Layer"]
+    A2 --> ADAPTER1
+    A3 --> ADAPTER1
+    A4 --> ADAPTER1
+    
+    ADAPTER1 <--> UNIVERSAL["UNIVERSAL REPRESENTATION FORM<br/>(HalfEdge Mesh Interface)<br/>- Vertices<br/>- Halfedges<br/>- Faces"]
+    
+    ADAPTER1 <--> EXT["EXTERNAL LIBRARIES<br/>(Plugin System)<br/>- CGAL<br/>- OpenMesh<br/>- PyNoise<br/>- PointCloud Lib"]
+    
+    EXT <--> UNIVERSAL
+    
+    UNIVERSAL --> PROCESSING["PROCESSING CORE"]
+    
+    PROCESSING --> OPT["Optimization<br/>- Decimation<br/>- Denoising<br/>- Remeshing"]
+    PROCESSING --> ALGO["Algorithmic<br/>- Boolean Ops<br/>- Smoothing<br/>- Hole Filling"]
+    PROCESSING --> OTHER["Other<br/>- Custom Algos<br/>- Transforms<br/>- Filters"]
+    
+    OPT --> UNIVERSAL
+    ALGO --> UNIVERSAL
+    OTHER --> UNIVERSAL
+    
+    UNIVERSAL --> EXPORT_ADAPTER["Export Adapter Layer"]
+    
+    EXPORT_ADAPTER --> EXPORT["Export Formats<br/>- OBJ<br/>- PLY<br/>- STL<br/>- Custom"]
+    EXPORT_ADAPTER --> VIZ["Visualization<br/>- OpenGL<br/>- QT<br/>- Screenshot"]
+    
+    style UNIVERSAL fill:#90EE90,stroke:#000,stroke-width:3px,color:#000
+    style PROCESSING fill:#87CEEB,stroke:#000,stroke-width:2px,color:#000
+    style EXT fill:#DDA0DD,stroke:#000,stroke-width:2px,color:#000
+    style ADAPTER1 fill:#FFB347,stroke:#000,stroke-width:2px,color:#000
+    style EXPORT_ADAPTER fill:#FFB347,stroke:#000,stroke-width:2px,color:#000
+All external inputs (file-based, implicit, parametric, procedural) are first converted by an adapter layer into a single universal half-edge mesh interface, which is the canonical internal representation used by the preprocessing and processing stages. The processing core operates on this universal representation and can use external libraries via a plugin-like extension layer, while results are passed through an export adapter to file formats or visualization frontends.
+
+
+Three-stage processing pipeline
+The geometry processing pipeline in ConformalLab++ is structured into three main stages, all operating on the same universal mesh representation.
+
+Preprocessing
+
+Converts all external inputs (files, analytic models, procedural sources) into the canonical half-edge mesh form.
+
+Performs optional cleaning and normalization (e.g. fixing degeneracies, rescaling, enforcing orientation).
+
+Guarantees that downstream stages see a well-formed, consistent mesh (or fail early with clear errors).
+
+Processing (core processing units)
+
+Runs one or more core processing units in sequence on the canonical mesh.
+
+Each unit takes a mesh of the same type as input and produces a mesh of the same type as output (possibly with enriched attributes).
+
+Examples: remeshing, conformal parameterization, smoothing, boolean operations, experiment-specific transforms.
+
+Postprocessing
+
+Adapts the processed mesh for external consumption: export to file formats, visualization, analysis tools.
+
+May attach or convert attribute data (e.g. colors, scalar fields, experiment results) into a format suitable for rendering or further tools.
+
+Does not change the core topology or semantics of the processed mesh, only its representation for the outside world.
+
+This structure makes it easy to reason about where data enters, is modified, and leaves the system, and keeps experimental algorithms clearly separated from IO concerns.
+
+Role of the universal mesh representation
+The universal mesh representation (a half-edge mesh interface) is the shared contract between all pipeline stages.
+
+Single input/output type
+Every core processing unit exposes the same function shape conceptually:
+UniversalMesh → UniversalMesh.
+This allows units to be chained in arbitrary order as long as their preconditions on the mesh are satisfied.
+
+Local, topology-aware access
+The half-edge structure encodes vertices, halfedges, faces, and their adjacency relations, which is essential for typical geometry operations (e.g. local neighborhood queries, traversal, edge flips).
+
+Algorithms do not need to know where the mesh came from (file vs. analytic vs. procedural); they only rely on this uniform interface.
+
+Extensibility via attributes
+The universal mesh may carry extensible per-vertex, per-edge, and per-face attributes (e.g. UVs, curvature, experimental scalar fields).
+Core units can read and write these attributes while still conforming to the same mesh type, enabling complex pipelines without changing the central data structure.
+
+Because all processing units speak the same “mesh language”, you can build pipelines like:
+
+text
+Preprocessing
+  -> RemeshingUnit
+  -> ConformalMapUnit
+  -> ExperimentSpecificFilter
+  -> Export/Postprocessing
+without changing the basic function signature or the surrounding infrastructure, only by reordering or swapping units.
+