docs(conductor): ACVD remeshing feature plan - #23
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
conductor/tracks/acvd_20260904/spec.mdconductor/tracks/acvd_20260904/plan.mdconductor/tracks/acvd_20260904/{index,metadata}.json/mdpending)conductor/tracks.md,conductor/index.mdThe 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.mdand #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:
clustering (cluster count = output vertex count, triangles fall out of the
dual directly). Face clustering changes the dual rule and boundary handling.
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
4) is deferred as highest-risk and least load-bearing for our meshes
QEM edge-collapse decimation were both scoped and deliberately dropped;
parallelism is not a target
Recorded findings worth not re-deriving
spec.mdcaptures a few things that were verified numerically while planning:m_a‖γ_a − p‖²/(m_a − ρ_s) > m_b‖γ_b − p‖²/(m_b + ρ_s)— translationinvariant, cancellation-free, checked against brute-force energy recomputation
to 1.8e-13 over 400 random moves
Q − Σ‖c‖²/m: in float32 atscan-scale coordinates it returns a negative energy (measured: true 57,442,
computed −262,144)
ρ = h⁻⁴, to be treated as a calibration andverified numerically
normalize()has nozero guard (NaN face normals on degenerate faces),
interior_angle()doesn'tclamp its
acos,Mesh::insert_vertexclears the whole face-normal cache,and
educelab::randomis not seedableClean-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.mdfor the implementation phases.Phase 0 adds the three papers to
docs/citations.bib(already wired intoDoxygen, currently empty) so the new headers can cite them via
@cite.CI
Docs only — no compiled code touched.