fix: rebuild the elbow as a readable hinge in vertex-weight-limit

docs/gallery/vertex-weight-limit/index.html

@@ -183,12 +183,12 @@ <h1>vertex-weight-limit</h1>
       <button class="copy-btn" id="copyRun" type="button">Copy</button>
     </div>
     <section class="detail-section md">
-<p>A runnable example that rigs a mech arm — bolted pedestal and shoulder fairing, an upper arm ending in clevis cheeks, the elbow hinge pin capped through a ribbed flex bellows, a long plated forearm, wrist bellows and collar, and a three-finger gripper — with deliberately rich five-bone weight bumps in the bellows, then enforces the game-engine <strong>maximum of four bone influences per vertex</strong> through the data API, following <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/skills/mesh-editing-and-bmesh/SKILL.md"><code>mesh-editing-and-bmesh</code></a> and building on the linear-blend-skinning precedent of <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/armature-bend"><code>armature-bend</code></a>.</p>
+<p>A runnable example that rigs a mech arm — bolted pedestal and shoulder fairing, an upper arm ending in clevis cheeks, the elbow hinge pin and knuckle barrel capped through a ribbed flex cuff, a long plated forearm, wrist cuff and collar, and a three-finger gripper — with deliberately rich five-bone weight bumps in the bellows, then enforces the game-engine <strong>maximum of four bone influences per vertex</strong> through the data API, following <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/skills/mesh-editing-and-bmesh/SKILL.md"><code>mesh-editing-and-bmesh</code></a> and building on the linear-blend-skinning precedent of <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/armature-bend"><code>armature-bend</code></a>.</p>
 <p><strong>Pipeline arc:</strong> modeling/LOD in <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/lod-decimate-chain"><code>lod-decimate-chain</code></a>, weighting here, export in <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/gltf-export-roundtrip"><code>gltf-export-roundtrip</code></a>.</p>
 <p><strong>What it witnesses:</strong> the skinning constraint every game engine enforces and AI-generated rigging code most often violates silently.</p>
 <p>1. <strong>The limit is a data-API operation, not a context operator.</strong> Instead of <code>bpy.ops.object.vertex_group_limit_total</code>, the example reads each vertex&#x27;s groups, keeps the top four by weight, <code>VertexGroup.remove</code>s the rest, and renormalizes the survivors. Dropping without renormalizing leaves sums at 0.986 — a mesh that shrinks toward the origin under load (the check&#x27;s measured failure, 1.438e-02 off unit sum). 2. <strong>The armature modifier is still exactly linear blend skinning</strong> after the limit: every depsgraph-evaluated vertex equals <code>Σ wᵢ · (pose.matrix @ bone.matrix_local.inverted()) @ rest</code>, with the weights <strong>read back from the mesh&#x27;s own deform layer</strong> (<code>v.groups</code>) — the weights on the mesh are the contract, not the weights you meant to write. Measured <code>lbs_err = 3.0e-07</code>. 3. <strong>Pruning must not damage the pose.</strong> Evaluated positions before and after the limit are held within 0.05 (measured 3.0e-03), the pedestal mount stays exactly pinned (Root is unposed), and the pre-limit authoring really carries five influences in the boots — otherwise the witness would be vacuous.</p>
 <p>The vertex-group API (<code>v.groups</code>, <code>VertexGroup.add</code>/<code>remove</code>) is stable between Blender 4.5 LTS and 5.1 — the example runs identically on both, which is itself the version witness (measured values match to the digit).</p>
-<p>The render shows the pruned arm mid-pose: the flex bellows carry the teal accent — the five-influence zones the limit prunes glow at the elbow hinge and wrist, sealed by the bright ring on the elbow bellows — proof that the limited weights still deform as authored.</p>
+<p>The render shows the pruned arm mid-pose: the flex cuffs carry the teal accent — the five-influence zones the limit prunes glow at the elbow hinge and wrist, sealed by the bright hoop on the elbow cuff — proof that the limited weights still deform as authored.</p>
 <h2>Run</h2>
 <pre><code># Cheap correctness check (no render) — the CI check:
 blender --background --python vertex_weight_limit.py --
@@ -337,23 +337,26 @@ <h2>Source</h2>
         tag(lathe_part(bm, [(<span class="n">0.10</span>, <span class="n">0.14</span>), (<span class="n">0.30</span>, <span class="n">0.19</span>), (<span class="n">0.45</span>, <span class="n">0.19</span>),
                             (<span class="n">0.60</span>, <span class="n">0.23</span>), (<span class="n">0.80</span>, <span class="n">0.24</span>), (<span class="n">1.00</span>, <span class="n">0.23</span>),
                             (<span class="n">1.15</span>, <span class="n">0.21</span>)], ORANGE), <span class="s">&quot;Shoulder&quot;</span>)
-        <span class="c"># clevis cheeks the hinge pin rides in (rigid on Shoulder)</span>
+        <span class="c"># clevis cheek plates flanking the joint (rigid on Shoulder)</span>
         <span class="k">for</span> sy <span class="k">in</span> (-<span class="n">1</span>, <span class="n">1</span>):
-            box_part(bm, (<span class="n">0.12</span>, <span class="n">0.05</span>, <span class="n">0.42</span>), (<span class="n">0.0</span>, sy * <span class="n">0.165</span>, <span class="n">1.24</span>),
+            box_part(bm, (<span class="n">0.10</span>, <span class="n">0.06</span>, <span class="n">0.50</span>), (<span class="n">0.0</span>, sy * <span class="n">0.175</span>, <span class="n">1.30</span>),
                      (<span class="n">0</span>, <span class="n">0</span>, <span class="n">0</span>), ORANGE, part_of, <span class="s">&quot;Shoulder&quot;</span>)
-        <span class="c"># elbow flex bellows: the five-influence zone the limit prunes</span>
-        tag(lathe_part(bm, [(<span class="n">1.15</span>, <span class="n">0.21</span>), (<span class="n">1.20</span>, <span class="n">0.19</span>), (<span class="n">1.26</span>, <span class="n">0.21</span>),
-                            (<span class="n">1.33</span>, <span class="n">0.19</span>), (<span class="n">1.40</span>, <span class="n">0.21</span>), (<span class="n">1.47</span>, <span class="n">0.19</span>),
-                            (<span class="n">1.55</span>, <span class="n">0.19</span>)], RUBBER), <span class="s">&quot;FLEX&quot;</span>)
-        <span class="c"># the hinge pin through the cheeks, capped both ends (rides Elbow)</span>
-        cone_part(bm, <span class="n">0.15</span>, <span class="n">0.15</span>, <span class="n">0.46</span>, (<span class="n">0.0</span>, <span class="n">0.0</span>, <span class="n">1.35</span>), (<span class="n">90</span>, <span class="n">0</span>, <span class="n">0</span>),
+        <span class="c"># elbow flex cuff behind the hinge: the five-influence zone the</span>
+        <span class="c"># limit prunes (every ring inside the five-bump z window)</span>
+        tag(lathe_part(bm, [(<span class="n">1.33</span>, <span class="n">0.17</span>), (<span class="n">1.38</span>, <span class="n">0.19</span>), (<span class="n">1.43</span>, <span class="n">0.17</span>),
+                            (<span class="n">1.49</span>, <span class="n">0.19</span>), (<span class="n">1.55</span>, <span class="n">0.18</span>)], RUBBER), <span class="s">&quot;FLEX&quot;</span>)
+        <span class="c"># the hinge pin stays with the clevis (Shoulder): the forearm&#x27;s</span>
+        <span class="c"># knuckle barrel (Elbow) rotates around it — pin caps must not tilt</span>
+        cone_part(bm, <span class="n">0.13</span>, <span class="n">0.13</span>, <span class="n">0.44</span>, (<span class="n">0.0</span>, <span class="n">0.0</span>, <span class="n">1.35</span>), (<span class="n">90</span>, <span class="n">0</span>, <span class="n">0</span>),
+                  GUNMETAL, part_of, <span class="s">&quot;Shoulder&quot;</span>)
+        cone_part(bm, <span class="n">0.165</span>, <span class="n">0.165</span>, <span class="n">0.26</span>, (<span class="n">0.0</span>, <span class="n">0.0</span>, <span class="n">1.35</span>), (<span class="n">90</span>, <span class="n">0</span>, <span class="n">0</span>),
                   GUNMETAL, part_of, <span class="s">&quot;Elbow&quot;</span>)
         <span class="k">for</span> sy <span class="k">in</span> (-<span class="n">1</span>, <span class="n">1</span>):
-            cone_part(bm, <span class="n">0.17</span>, <span class="n">0.17</span>, <span class="n">0.05</span>, (<span class="n">0.0</span>, sy * <span class="n">0.215</span>, <span class="n">1.35</span>),
-                      (<span class="n">90</span>, <span class="n">0</span>, <span class="n">0</span>), GUNMETAL, part_of, <span class="s">&quot;Elbow&quot;</span>)
-        <span class="c"># bright seal ring on the bellows middle — the accent marking the</span>
-        <span class="c"># primary pruned-weight zone</span>
-        tag(lathe_part(bm, [(<span class="n">1.33</span>, <span class="n">0.215</span>), (<span class="n">1.37</span>, <span class="n">0.215</span>)], ACCENT), <span class="s">&quot;Elbow&quot;</span>)
+            cone_part(bm, <span class="n">0.17</span>, <span class="n">0.17</span>, <span class="n">0.05</span>, (<span class="n">0.0</span>, sy * <span class="n">0.225</span>, <span class="n">1.35</span>),
+                      (<span class="n">90</span>, <span class="n">0</span>, <span class="n">0</span>), GUNMETAL, part_of, <span class="s">&quot;Shoulder&quot;</span>)
+        <span class="c"># bright seal hoop on the cuff — the accent marking the primary</span>
+        <span class="c"># pruned-weight zone</span>
+        tag(lathe_part(bm, [(<span class="n">1.42</span>, <span class="n">0.20</span>), (<span class="n">1.46</span>, <span class="n">0.20</span>)], ACCENT), <span class="s">&quot;Elbow&quot;</span>)
         <span class="c"># long plated forearm with two ridges (rigid on Elbow)</span>
         tag(lathe_part(bm, [(<span class="n">1.55</span>, <span class="n">0.19</span>), (<span class="n">1.75</span>, <span class="n">0.21</span>), (<span class="n">1.80</span>, <span class="n">0.23</span>),
                             (<span class="n">1.86</span>, <span class="n">0.21</span>), (<span class="n">2.05</span>, <span class="n">0.20</span>), (<span class="n">2.18</span>, <span class="n">0.22</span>),
@@ -373,8 +376,8 @@ <h2>Source</h2>
         <span class="c"># three two-segment fingers, splayed (rigid on Claw)</span>
         <span class="k">for</span> a_deg <span class="k">in</span> (<span class="n">90.0</span>, <span class="n">210.0</span>, <span class="n">330.0</span>):
             a = math.radians(a_deg)
-            <span class="k">for</span> pos, tilt, size <span class="k">in</span> (((<span class="n">0.08</span>, <span class="n">3.08</span>), <span class="n">12.0</span>, (<span class="n">0.075</span>, <span class="n">0.11</span>, <span class="n">0.22</span>)),
-                                    ((<span class="n">0.14</span>, <span class="n">3.26</span>), <span class="n">26.0</span>, (<span class="n">0.06</span>, <span class="n">0.095</span>, <span class="n">0.18</span>))):
+            <span class="k">for</span> pos, tilt, size <span class="k">in</span> (((<span class="n">0.08</span>, <span class="n">3.08</span>), <span class="n">12.0</span>, (<span class="n">0.085</span>, <span class="n">0.13</span>, <span class="n">0.22</span>)),
+                                    ((<span class="n">0.14</span>, <span class="n">3.26</span>), <span class="n">26.0</span>, (<span class="n">0.07</span>, <span class="n">0.11</span>, <span class="n">0.18</span>))):
                 off, z = pos
                 m = (mathutils.Matrix.Translation((<span class="n">0.0</span>, <span class="n">0.0</span>, z))
                      @ mathutils.Matrix.Rotation(a, <span class="n">4</span>, <span class="s">&#x27;Z&#x27;</span>)

examples/vertex-weight-limit/README.md

@@ -1,9 +1,9 @@
 # Vertex Weight Limit
 
 A runnable example that rigs a mech arm — bolted pedestal and shoulder
-fairing, an upper arm ending in clevis cheeks, the elbow hinge pin capped
-through a ribbed flex bellows, a long plated forearm, wrist bellows and
-collar, and a three-finger gripper — with deliberately rich five-bone weight
+fairing, an upper arm ending in clevis cheeks, the elbow hinge pin and
+knuckle barrel capped through a ribbed flex cuff, a long plated forearm,
+wrist cuff and collar, and a three-finger gripper — with deliberately rich five-bone weight
 bumps in the bellows, then enforces the game-engine
 **maximum of four bone influences per vertex** through the data API, following
 [`mesh-editing-and-bmesh`](../../skills/mesh-editing-and-bmesh/SKILL.md) and
@@ -37,9 +37,9 @@ The vertex-group API (`v.groups`, `VertexGroup.add`/`remove`) is stable between
 Blender 4.5 LTS and 5.1 — the example runs identically on both, which is itself
 the version witness (measured values match to the digit).
 
-The render shows the pruned arm mid-pose: the flex bellows carry the teal
+The render shows the pruned arm mid-pose: the flex cuffs carry the teal
 accent — the five-influence zones the limit prunes glow at the elbow hinge
-and wrist, sealed by the bright ring on the elbow bellows — proof that the
+and wrist, sealed by the bright hoop on the elbow cuff — proof that the
 limited weights still deform as authored.
 
 ## Run

examples/vertex-weight-limit/vertex_weight_limit.py

@@ -131,23 +131,26 @@ def tag(rings_verts, bone):
         tag(lathe_part(bm, [(0.10, 0.14), (0.30, 0.19), (0.45, 0.19),
                             (0.60, 0.23), (0.80, 0.24), (1.00, 0.23),
                             (1.15, 0.21)], ORANGE), "Shoulder")
-        # clevis cheeks the hinge pin rides in (rigid on Shoulder)
+        # clevis cheek plates flanking the joint (rigid on Shoulder)
         for sy in (-1, 1):
-            box_part(bm, (0.12, 0.05, 0.42), (0.0, sy * 0.165, 1.24),
+            box_part(bm, (0.10, 0.06, 0.50), (0.0, sy * 0.175, 1.30),
                      (0, 0, 0), ORANGE, part_of, "Shoulder")
-        # elbow flex bellows: the five-influence zone the limit prunes
-        tag(lathe_part(bm, [(1.15, 0.21), (1.20, 0.19), (1.26, 0.21),
-                            (1.33, 0.19), (1.40, 0.21), (1.47, 0.19),
-                            (1.55, 0.19)], RUBBER), "FLEX")
-        # the hinge pin through the cheeks, capped both ends (rides Elbow)
-        cone_part(bm, 0.15, 0.15, 0.46, (0.0, 0.0, 1.35), (90, 0, 0),
+        # elbow flex cuff behind the hinge: the five-influence zone the
+        # limit prunes (every ring inside the five-bump z window)
+        tag(lathe_part(bm, [(1.33, 0.17), (1.38, 0.19), (1.43, 0.17),
+                            (1.49, 0.19), (1.55, 0.18)], RUBBER), "FLEX")
+        # the hinge pin stays with the clevis (Shoulder): the forearm's
+        # knuckle barrel (Elbow) rotates around it — pin caps must not tilt
+        cone_part(bm, 0.13, 0.13, 0.44, (0.0, 0.0, 1.35), (90, 0, 0),
+                  GUNMETAL, part_of, "Shoulder")
+        cone_part(bm, 0.165, 0.165, 0.26, (0.0, 0.0, 1.35), (90, 0, 0),
                   GUNMETAL, part_of, "Elbow")
         for sy in (-1, 1):
-            cone_part(bm, 0.17, 0.17, 0.05, (0.0, sy * 0.215, 1.35),
-                      (90, 0, 0), GUNMETAL, part_of, "Elbow")
-        # bright seal ring on the bellows middle — the accent marking the
-        # primary pruned-weight zone
-        tag(lathe_part(bm, [(1.33, 0.215), (1.37, 0.215)], ACCENT), "Elbow")
+            cone_part(bm, 0.17, 0.17, 0.05, (0.0, sy * 0.225, 1.35),
+                      (90, 0, 0), GUNMETAL, part_of, "Shoulder")
+        # bright seal hoop on the cuff — the accent marking the primary
+        # pruned-weight zone
+        tag(lathe_part(bm, [(1.42, 0.20), (1.46, 0.20)], ACCENT), "Elbow")
         # long plated forearm with two ridges (rigid on Elbow)
         tag(lathe_part(bm, [(1.55, 0.19), (1.75, 0.21), (1.80, 0.23),
                             (1.86, 0.21), (2.05, 0.20), (2.18, 0.22),
@@ -167,8 +170,8 @@ def tag(rings_verts, bone):
         # three two-segment fingers, splayed (rigid on Claw)
         for a_deg in (90.0, 210.0, 330.0):
             a = math.radians(a_deg)
-            for pos, tilt, size in (((0.08, 3.08), 12.0, (0.075, 0.11, 0.22)),
-                                    ((0.14, 3.26), 26.0, (0.06, 0.095, 0.18))):
+            for pos, tilt, size in (((0.08, 3.08), 12.0, (0.085, 0.13, 0.22)),
+                                    ((0.14, 3.26), 26.0, (0.07, 0.11, 0.18))):
                 off, z = pos
                 m = (mathutils.Matrix.Translation((0.0, 0.0, z))
                      @ mathutils.Matrix.Rotation(a, 4, 'Z')