feat: Multi-chart UV packing (PackCharts)

[csparker247]

Summary

Implements F2 — Multi-chart UV packing (closes #18): geometry-only free functions PackCharts<MeshType> and MergeMeshes<MeshType> for laying out and merging already-parameterized charts into a shared coordinate frame.

PackCharts rotates, translates, and (optionally) uniformly scales each chart's 2D vertex positions in place using shelf packing, without touching topology or indices. Each chart is first rotated within its UV plane to its minimum-area bounding box and stood on its long axis; charts are then sorted by height and laid out left-to-right, wrapping to a new shelf when the row width exceeds the target (defaults to sqrt(total area) for a roughly square atlas).

MergeMeshes concatenates a vector of charts into a single mesh, returning provenance maps (vertex_source, face_source) so the atlas can be traced back through the component's vertex_map/face_map to the original torn mesh.

Also fixes a pre-existing correctness bug in HalfEdgeMesh's connected-component traversal (#103) that made multi-chart extraction unusable on real meshes — see Carried bug fix below.

Design (resolved via design review)

• Geometry-only / in-place. Both functions mutate only vertex pos; topology and indices unchanged, so any ExtractedComponent back-maps the caller holds stay valid.
• Per-wedge UV recipe documented, not owned. OpenABF does not ship a UVMap type. The updated MultiChartFlatten example documents how to build a per-corner UV map from the packed atlas using back-maps, keyed by vertex identity (not corner position).
• Bounding-box minimization (default on). Shelf packing reasons about axis-aligned boxes, so a chart that arrives rotated wastes atlas area equal to the slack between its AABB and its true footprint. Each chart is rotated in-plane to its minimum-area box (monotone-chain convex hull, then test the orientation induced by each hull edge — the min-area enclosing rectangle always has an edge collinear with a hull edge), then stood on its long axis to match the tallest-first shelf strategy. The transform is a rigid rotation (determinant +1), so winding order and texture handedness are preserved along with topology and vertex identity. Disable with minimize_bounding_box = false.
• Scaling. Absolute (physical) scale preserved by default (translate-only); opt-in normalize applies a single global uniform scale to fit [0,1]², preserving relative chart sizes and cross-chart texel density.
• Padding. The padding option surrounds every chart on all four sides, including against the atlas boundary. Perimeter charts are inset from the packed extent by padding, not merely separated from neighbors. Library default is padding = 0; the example sets a visible padding = 0.1f to prevent texture filtering bleed.
• Layout. Shelf packing, charts sorted by height; target shelf width defaults to sqrt(Σ chart bbox area), overridable via PackOptions.
• Measured extent. The returned atlas extent is measured from where the charts actually landed and the transform shifts by that corner, so "the atlas lower corner sits on the origin" holds by construction rather than by assumption about the layout loop.
• API. PackOptions<T>{minimize_bounding_box, normalize, target_width, padding} and PackResult<VecType>{min, max} (packed atlas extent). PackResult carries the meshes' own position vector type so the extent needs no conversion to compare against vertex positions; only u/v are meaningful. MergeMeshes returns MergedMesh{mesh, vertex_source, face_source}. Both functions take std::vector<std::shared_ptr<MeshType>>, so MeshType is deduced at the call site — PackCharts(charts) — with the explicit PackCharts<Mesh>(charts) spelling still supported.
• Validation. All options and chart pointers are checked before any chart is modified, so a rejected input leaves every chart untouched. Empty list → empty extent; zero-area chart placed; null/empty chart, negative padding, or non-positive target_width → std::invalid_argument; static_assert(PositionType::Dimensions >= 2) on the vertex position type.

Carried bug fix (#103)

Found while running this pipeline on a real partitioned mesh. num_connected_components() and connected_components() marked a face visited when it was dequeued rather than when it was enqueued, so a face adjacent to two or more still-queued faces was enqueued once per incident interior edge and appeared multiple times in the component's face list.

This was a correctness bug, not just redundant work: on a 4×4 grid (18 faces) the single component came back with 38 faces, and extract_connected_components() then cloned the same face twice and threw "Attempted to add non-manifold face". Any mesh with mutually-adjacent interior faces hit it; the existing component tests used one- and two-triangle meshes, which have no mutually-adjacent neighbors, so nothing caught it.

The fix marks faces visited at push time in both traversals. It ships here rather than in a standalone PR because F2's pipeline cannot run without it; it is tracked as its own bug issue (#103, Conductor track B10) with a regression test confirmed Red against develop's traversal.

Changes

Core Implementation:

• New include/OpenABF/ChartPacking.hpp — PackCharts, PackOptions, PackResult, detail::MinimizeChartBoundingBox
• New include/OpenABF/MeshMerge.hpp — MergeMeshes, MergedMesh
• Updated include/OpenABF/HalfEdgeMesh.hpp — BFS visit-on-enqueue fix in both component traversals (extract_connected_components throws on any mesh with mutually-adjacent interior faces (BFS marks visited on dequeue) #103); new public PositionType alias
• Updated include/OpenABF/Vec.hpp — public static constexpr std::size_t Dimensions for the position-dimension static_assert
• Updated include/OpenABF/OpenABF.hpp and CMakeLists.txt — includes and multiheader install entries for both new headers
• Updated single_include/OpenABF/OpenABF.hpp — regenerated via amalgamation

Tests:

• New tests/src/TestChartPacking.cpp — 22 cases: bbox correctness, non-overlap with padding, perimeter padding inset, absolute/normalize scaling, normalization fits [0,1]², extent containment, bounding-box minimization (tightens a rotated chart, stands a wide chart upright, can be disabled), topology/index invariance, face-orientation preservation, target_width wrapping, degenerate and rejected inputs, end-to-end tear→extract→flatten→pack with per-wedge recovery
• New tests/src/TestMeshMerge.cpp — 9 cases: concatenation counts, vertex/face provenance including index alignment, merged-mesh edge ownership, degenerate inputs, round-trip extract→merge identity recovery
• Updated tests/src/TestHalfEdgeMesh.cpp — ConnectedComponentsVisitEachFaceOnce regression test for extract_connected_components throws on any mesh with mutually-adjacent interior faces (BFS marks visited on dequeue) #103

Example:

• Rewritten examples/src/MultiChartFlatten.cpp — tears a mesh, extracts and parameterizes components, packs them into a single atlas using PackCharts with visible padding, merges back via MergeMeshes, and writes a single packed atlas .obj. Chart flattening is wrapped in try/catch on SolverException: not every chart topology is solvable, and one unsolvable chart should not abort the atlas; if no chart survives, the example exits with a message rather than writing an empty atlas. Includes extensive reference documentation for building a per-wedge UV map from the merged result and back-maps.

Documentation / project bookkeeping:

• Conductor F2 spec/plan record Phase 5 (MergeMeshes), Phase 6 (perimeter padding), Phase 7 (bounding-box minimization, incl. why default-on is safe), and Phase 8 (the carried BFS fix); spec Decisions 1/5/6 updated and Decision 7 added.
• Conductor track B10 registered for extract_connected_components throws on any mesh with mutually-adjacent interior faces (BFS marks visited on dequeue) #103; track B9 created earlier for No recoverable mapping from torn seam-duplicate vertices back to the consumer's pre-HEM mesh #100 (mapping from torn/parameterized mesh back to the original input topology).
• .gitignore now covers openabf_example_*.obj/.ply so running the examples no longer dirties the tree.

Review follow-ups

Applied after code review of the initial implementation:

• PackCharts no longer partially mutates on throw. Validation was interleaved with the in-place rotation, so a null chart partway through the list threw only after earlier charts had already been rotated — with no way for the caller to tell which. All inputs are now validated in a dedicated pass first.
• The returned extent can no longer disagree with the geometry. PackResult::min was hard-coded to the origin; the atlas corner is now measured from actual placements and applied as part of the transform.
• Negative padding and non-positive target_width are rejected rather than silently producing a degenerate layout.
• MergeMeshes no longer depends on implicit copy-constructor behavior to avoid carrying Vertex::edge pointers across meshes; it nulls edge explicitly, matching clone() and extract_connected_components().
• MeshType is deducible for both functions; HalfEdgeMesh::PositionType replaces a decltype/declval expression in PackCharts's return type.
• New regression coverage for the invariants the documentation promises but CI did not enforce: topology/index invariance across a pack, rigid-rotation (no reflection) of the bbox minimization, target_width wrapping, face_source index alignment, and merged-vertex edge ownership.

Known and tracked, not addressed here: the default shelf-width heuristic and the wrap test disagree on padding, so the atlas wastes area and can be far from square (#104, track P7). The layout stays valid and non-overlapping.

Verification

• ctest: 8/8 suites pass (incl. OpenABF_TestChartPacking at 22 cases and OpenABF_TestMeshMerge at 9).
• Single-header build (-DOPENABF_MULTIHEADER=OFF) configures, compiles, and passes all 8 suites.
• Amalgamated single_include/OpenABF/OpenABF.hpp verified byte-identical to a fresh amalgamation run.
• MultiChartFlatten example builds and runs, writing a packed 12-vertex / 8-face atlas.
• #103 regression test verified Red against develop's traversal and Green with the fix. The three validation tests were likewise verified Red against the pre-review implementation.
• clang-format clean.

Complexity

O(n log n) in chart count + O(V) in total vertices; O(n) memory. With minimize_bounding_box, each chart additionally costs an O(v log v) convex hull plus an O(h²) orientation search over its h hull points.

🤖 Generated with Claude Code