Mesh object model
A mesh object stores copied finite double-precision XYZ vertices plus 32-bit triangle indices in immutable local geometry. Object transforms, hierarchy, visibility, opacity and style are independent mutable state. Duplicating an object shares/reuses immutable geometry semantics while keeping independent placement/presentation state.
Create and import
| Operation | API | Contract |
|---|---|---|
| In-memory triangles | gx3de_object_create_mesh | Copies vertices and triangle indices. |
| OBJ/STL import | gx3de_object_import_mesh | Uses gx3de_mesh_import_spec, source and memory budgets. |
| Fast preview import | gx3de_object_import_mesh_preview | Creates a bounded preview representation without replacing authoritative source identity. |
| LOD derivation | gx3de_mesh_lod | Publishes a new mesh at Preview/Low/Medium/High/Full level. |
| Asynchronous preparation | gx3de_job_prepare_mesh_import / gx3de_job_prepare_mesh_lod | Moves blocking preparation to the job lifecycle; result is taken on caller thread. |
Topology inspection and repair
| Family | What it does | Important failure boundary |
|---|---|---|
| Diagnostics | gx3de_mesh_diagnose | Area, volume when well-defined, boundary/nonmanifold/orientation edges, disconnected components. |
| Boundary loops | gx3de_mesh_boundary_edges / gx3de_mesh_loops_create | Exposes real topology; branched or inconsistent loops are rejected. |
| Append / merge / weld | gx3de_mesh_append, gx3de_mesh_merge, gx3de_mesh_weld | Creates a new result; tolerance is explicit where applicable. |
| Duplicate cleanup | gx3de_mesh_clean_duplicates | Produces a cleaned object rather than editing source. |
| Orient normals | gx3de_mesh_orient_normals | Makes edge-manifold components consistently wound and positive-volume where closed. |
| Stitch / bridge / heal seam | gx3de_mesh_stitch, gx3de_mesh_bridge, gx3de_mesh_heal_seam | Conservative: requires uniquely pairable simple compatible loops and publishes only valid connected closed orientation. |
| Self intersections | gx3de_mesh_self_intersections / gx3de_mesh_intersection_pairs | Non-adjacent triangle-pair diagnostics with tolerance and deterministic records/witness points. |
Clipping
gx3de_mesh_clip is the uncapped VTK path. gx3de_mesh_clip_capped is deliberately conservative: it is intended for transverse cuts of closed, consistently wound meshes with safe simple section contours. It matches clipped boundaries to the section profile and validates the published result. Difficult vertex-crossing, ambiguous/nonmanifold or unsafe triangulation cases fail explicitly rather than returning a questionable solid.
Sections, profiles and projection
A section is a scene-owned snapshot of plane/object intersection segments. gx3de_profile_create snaps section endpoints at an explicit positive tolerance and derives ordered open/closed contours with length and planar area. Profiles can survive section destruction. Projection creates a reusable world-space projected object linked to source and plane; it can be refreshed explicitly while the source exists.
Repeated components
The repeat detector discovers repeated triangle components from a selected source triangle. A gx3de_repeat_result exposes prototype, placements and remainder. The optional presentation path draws captured placements through a shared prototype mapper rather than materializing one full mesh copy per occurrence. Persistent repeat cache statistics are separate from the normal mesh cache.
Fingerprints
gx3de_object_source_sha256identifies imported source bytes where available.gx3de_object_geometry_fingerprinthashes bounded immutable local geometry; object placement does not change the local-geometry digest.gx3de_object_derivation_fingerprintrepresents derived-state identity where supported.- Fingerprints help cache/provenance workflows; they do not make B-Rep subshape indices persistent across a Boolean, clip, rebuild or reimport.