Skip to content

docs(conductor): ACVD remeshing feature plan - #23

Merged
csparker247 merged 1 commit into
developfrom
feat/acvd_20260904
Sep 4, 2026
Merged

docs(conductor): ACVD remeshing feature plan#23
csparker247 merged 1 commit into
developfrom
feat/acvd_20260904

Conversation

@csparker247

Copy link
Copy Markdown
Member

What this is

The feature plan for ACVD remeshing, nothing more. Docs only — no library
code, no tests, no build changes. Merging this records the plan in the
repository; it does not start implementation.

Closes nothing. Tracks #22. Companion adapter work: educelab/OpenABF#62.

Contents

File What
conductor/tracks/acvd_20260904/spec.md Full specification — algorithm, derivations, proposed API, testing strategy, dependencies and hazards, effort estimate, open questions
conductor/tracks/acvd_20260904/plan.md 7 phases / 26 tasks, phased by paper layer
conductor/tracks/acvd_20260904/{index,metadata}.json/md Track navigation and metadata (status pending)
conductor/tracks.md, conductor/index.md Registry entries

The plan in one paragraph

The three reference papers describe one clustering engine, not three
algorithms
— what differs between them is the weight attached to each mesh
element and where the output vertex lands. So the phases are the weight
policies, layered on a single minimizer: a design gate, mesh topology, uniform
ACVD (2004), curvature-adaptive weights plus quadric placement (2008 scalar),
anisotropic metric tensors (2008 full), approach-guided density fields (2011),
and optional extras. Phases 0–2 are the useful milestone — roughly a week
for a uniform remesher that stands alone.

The engine lives in libcore rather than OpenABF because ACVD needs no sparse
linear algebra (dense 3×3 is the largest system it solves), so libcore can host
all three papers without gaining a dependency; and because ACVD never mutates
topology, so a half-edge structure buys it nothing. Dependency direction stays
OpenABF → libcore. Full rationale in spec.md and #22.

Not starting yet — phase 0 gates the rest

Two questions have to be settled against the paper PDFs before the minimizer is
written, because the rest of the code shapes itself around them:

  1. Vertices or faces as the clustered items? The spec assumes vertex
    clustering (cluster count = output vertex count, triangles fall out of the
    dual directly). Face clustering changes the dual rule and boundary handling.
  2. Boundary treatment for open meshes. Presumed approach is a separate 1D
    clustering along each boundary loop. This matters more for EduceLab meshes
    than for the papers' test cases — most of ours are open patches, where a
    shrinking or ragged boundary is disqualifying.

Four further open questions (gradation formula, curvature estimator, extent of
topology repair, UV map contract) are recorded in spec.md.

What's worth reviewing

  • The layer split and phase ordering — particularly that anisotropic (phase
    4) is deferred as highest-risk and least load-bearing for our meshes
  • The two gating decisions above
  • The out-of-scope calls: deviation-metric-driven iterative coarsening and
    QEM edge-collapse decimation were both scoped and deliberately dropped;
    parallelism is not a target
  • The effort estimate, if this needs scheduling against other tracks

Recorded findings worth not re-deriving

spec.md captures a few things that were verified numerically while planning:

  • The exact O(1) reassignment test,
    m_a‖γ_a − p‖²/(m_a − ρ_s) > m_b‖γ_b − p‖²/(m_b + ρ_s) — translation
    invariant, cancellation-free, checked against brute-force energy recomputation
    to 1.8e-13 over 400 random moves
  • Why not to use the subtractive energy form Q − Σ‖c‖²/m: in float32 at
    scan-scale coordinates it returns a negative energy (measured: true 57,442,
    computed −262,144)
  • The density/edge-length relation ρ = h⁻⁴, to be treated as a calibration and
    verified numerically
  • Hazards in existing code the implementation will hit: normalize() has no
    zero guard (NaN face normals on degenerate faces), interior_angle() doesn't
    clamp its acos, Mesh::insert_vertex clears the whole face-normal cache,
    and educelab::random is not seedable

Clean-room

A reference implementation of ACVD exists online. This plan was derived only
from the papers' described methods, with no reference implementation consulted,
and the constraint is documented in spec.md for the implementation phases.
Phase 0 adds the three papers to docs/citations.bib (already wired into
Doxygen, currently empty) so the new headers can cite them via @cite.

CI

Docs only — no compiled code touched.

Register track acvd_20260904 for ACVD (Approximated Centroidal Voronoi
Diagrams) mesh remeshing, tracking #22 with companion
adapter work in educelab/OpenABF#62.

The three reference papers describe one clustering engine with layered
weight policies, not three algorithms, so the plan is phased by layer:
design gate, mesh topology, uniform ACVD (2004), curvature-adaptive
weights and quadric placement (2008 scalar), anisotropic metrics (2008
full), approach-guided density fields (2011), and optional extras.

Spec records the energy formulation, the exact O(1) reassignment test,
the float32 failure of the subtractive energy form, the density/edge
length relation, the proposed API, the testing strategy, hazards in
existing code, and six unresolved questions to settle against the paper
PDFs. Clean-room constraint documented: derived from the papers only.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@csparker247
csparker247 merged commit 643ea26 into develop Sep 4, 2026
5 checks passed
@csparker247
csparker247 deleted the feat/acvd_20260904 branch September 4, 2026 13:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant