nx_uvunwrap_lib.nx

nx_uvunwrap_lib.nx -- A GENERAL UV UNWRAP FOR AN ARBITRARY MESH, WITH A DISTORTION REFEREE (/compare/dcc DC5). WHAT WAS ABSENT, MEASURED NOT ASSERTED. nx_capsearch over 6,892 organs (1,375 tools + 5,517 libs, corpus_complete=1) returned NO general parameterisation: the estate's only unwrap is ntx_apply in nx_nxa_texc_lib, a bone-anchored CYLINDRICAL map that reads SKEL parents and SKIN weights and refuses outright without them ("no SKIN section -- refusing to fabricate bone ownership"). That is the right design for a humanoid NXA and it is unreachable for everything else: a sculpt, a boolean result, a terrain patch, a retopologised prop has no skeleton to anchor to, so it could not be unwrapped AT ALL, and texture painting was blocked for every non-humanoid asset in the estate. OUTPUT IS WIRE-COMPATIBLE WITH THE INCUMBENT BAKE PATH ON PURPOSE. uv_emit_texc writes exactly the TEXC payload nx_nxa_texbake_lib already consumes -- header [nv][stride 3][atlas grid g][reserved 0] then per vertex [u Q16][v Q16][chart], charts owning disjoint tiles of a g x g grid with a one-unit gutter, the same shape and the same fixed-point scale ntx_apply emits. So a mesh unwrapped here bakes through the existing sampler with nothing else changed. BUT THE BRIDGE IS LOSSY AND IT SAYS SO. TEXC is PER VERTEX and a seam is exactly the place where one mesh vertex needs TWO texture coordinates, so the incumbent wire format cannot represent a seam at all. This library solves per CORNER (a mesh vertex split by seams into several UV vertices, which is what makes a cut actually cut), and uv_emit_texc COUNTS the vertices whose extra coordinates the per-vertex form drops, into UV_H_TEXCLOSS. A lossy conversion that reports zero loss would be the defect; one that names its loss is a bridge. THE HONEST ALGORITHM. A least-squares conformal map (Levy et al., LSCM) needs a linear solve, and there is no linear solver in this estate and no float type to build one on. So this is an ITERATIVE relaxation toward the same stationary condition, and every part of that choice is declared rather than hidden: * The energy is the LSCM energy in its Dirichlet-minus-area form, E = sum_edges W|dU|^2 - 2 sum_t A_t. THAT SECOND TERM IS THE WHOLE REASON THIS DOES NOT COLLAPSE. A pure harmonic (Dirichlet-only) relaxation with a free boundary and two pinned vertices has its minimum at the degenerate map that puts every vertex on the segment between the pins -- a fold, scoring zero by every naive measure. The -2*area term rewards area and makes the non-degenerate map the minimiser instead. * Setting dE/dU_p = 0 gives a closed-form per-vertex update, so this is a damped Jacobi sweep over the exact stationary condition rather than an invented heuristic. Interior vertices see a pure cotangent-Laplacian average (their one-ring area terms telescope to zero); the area term acts only on the boundary, pushing it outward. That is LSCM, iterated. * TWO PINNED VERTICES PER CHART, the standard LSCM constraint: the conformal energy is invariant to translation, rotation and scale, so two pins remove exactly the null space and no more. * The iteration bound is DERIVED FROM THE CHART, the convergence criterion is DECLARED, and a chart that reaches neither is REFUSED BY NAME (UV_E_NOCONVERGE) rather than emitted folded. THE REFEREE IS THE POINT. uv_distortion reports angle (quasi-conformal dilatation) and area distortion