fix: connect vertex-weight-limit's arm parts and straighten the reach

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

@@ -183,7 +183,7 @@ <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, a shoulder hub and clevis-ended upper arm, the elbow hinge pin inside 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 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><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>
@@ -248,7 +248,7 @@ <h2>Source</h2>
 BONE_SPANS = {<span class="s">&quot;Root&quot;</span>: (-<span class="n">0.35</span>, <span class="n">0.10</span>), <span class="s">&quot;Shoulder&quot;</span>: (<span class="n">0.10</span>, <span class="n">1.35</span>),
               <span class="s">&quot;Elbow&quot;</span>: (<span class="n">1.35</span>, <span class="n">2.55</span>), <span class="s">&quot;Wrist&quot;</span>: (<span class="n">2.55</span>, <span class="n">2.90</span>), <span class="s">&quot;Claw&quot;</span>: (<span class="n">2.90</span>, <span class="n">3.35</span>)}
 BONE_CENTERS = {b: (s[<span class="n">0</span>] + s[<span class="n">1</span>]) / <span class="n">2</span> <span class="k">for</span> b, s <span class="k">in</span> BONE_SPANS.items()}
-POSE_DEG = {<span class="s">&quot;Shoulder&quot;</span>: -<span class="n">8.0</span>, <span class="s">&quot;Elbow&quot;</span>: -<span class="n">35.0</span>, <span class="s">&quot;Wrist&quot;</span>: -<span class="n">18.0</span>, <span class="s">&quot;Claw&quot;</span>: <span class="n">12.0</span>}
+POSE_DEG = {<span class="s">&quot;Shoulder&quot;</span>: -<span class="n">8.0</span>, <span class="s">&quot;Elbow&quot;</span>: -<span class="n">35.0</span>, <span class="s">&quot;Wrist&quot;</span>: -<span class="n">14.0</span>, <span class="s">&quot;Claw&quot;</span>: <span class="n">6.0</span>}
 
 <span class="c"># armor palette slots</span>
 GUNMETAL, ORANGE, RUBBER, ACCENT = <span class="n">0</span>, <span class="n">1</span>, <span class="n">2</span>, <span class="n">3</span>
@@ -332,25 +332,24 @@ <h2>Source</h2>
             cone_part(bm, <span class="n">0.05</span>, <span class="n">0.04</span>, <span class="n">0.06</span>,
                       (<span class="n">0.36</span> * math.cos(a), <span class="n">0.36</span> * math.sin(a), <span class="n">0.03</span>),
                       (<span class="n">0</span>, <span class="n">0</span>, <span class="n">0</span>), GUNMETAL, part_of, <span class="s">&quot;Root&quot;</span>)
-        <span class="c"># shoulder hub poking through the fairing (rigid on Shoulder)</span>
-        cone_part(bm, <span class="n">0.19</span>, <span class="n">0.19</span>, <span class="n">0.56</span>, (<span class="n">0.0</span>, <span class="n">0.0</span>, <span class="n">0.62</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"># upper arm shell, slimmer than the old barrel (rigid on Shoulder)</span>
-        tag(lathe_part(bm, [(<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"># upper arm shell rooted deep inside the fairing — no gap at the</span>
+        <span class="c"># shoulder when the joint articulates (rigid on Shoulder)</span>
+        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="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>),
                      (<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.17</span>), (<span class="n">1.20</span>, <span class="n">0.20</span>), (<span class="n">1.26</span>, <span class="n">0.16</span>),
-                            (<span class="n">1.33</span>, <span class="n">0.20</span>), (<span class="n">1.40</span>, <span class="n">0.16</span>), (<span class="n">1.47</span>, <span class="n">0.20</span>),
-                            (<span class="n">1.55</span>, <span class="n">0.17</span>)], RUBBER), <span class="s">&quot;FLEX&quot;</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>),
                   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.18</span>, <span class="n">0.18</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>),
+            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>
@@ -363,19 +362,19 @@ <h2>Source</h2>
         box_part(bm, (<span class="n">0.10</span>, <span class="n">0.05</span>, <span class="n">0.60</span>), (<span class="n">0.0</span>, <span class="n">0.235</span>, <span class="n">2.02</span>),
                  (<span class="n">0</span>, <span class="n">0</span>, <span class="n">0</span>), ORANGE, part_of, <span class="s">&quot;Elbow&quot;</span>)
         <span class="c"># wrist flex bellows (second blend zone) + collar</span>
-        tag(lathe_part(bm, [(<span class="n">2.45</span>, <span class="n">0.16</span>), (<span class="n">2.51</span>, <span class="n">0.19</span>), (<span class="n">2.57</span>, <span class="n">0.15</span>),
-                            (<span class="n">2.64</span>, <span class="n">0.18</span>), (<span class="n">2.70</span>, <span class="n">0.15</span>), (<span class="n">2.75</span>, <span class="n">0.16</span>)],
+        tag(lathe_part(bm, [(<span class="n">2.45</span>, <span class="n">0.18</span>), (<span class="n">2.51</span>, <span class="n">0.20</span>), (<span class="n">2.57</span>, <span class="n">0.16</span>),
+                            (<span class="n">2.64</span>, <span class="n">0.19</span>), (<span class="n">2.70</span>, <span class="n">0.16</span>), (<span class="n">2.75</span>, <span class="n">0.17</span>)],
                        RUBBER), <span class="s">&quot;FLEX&quot;</span>)
         tag(lathe_part(bm, [(<span class="n">2.75</span>, <span class="n">0.16</span>), (<span class="n">2.85</span>, <span class="n">0.175</span>), (<span class="n">2.90</span>, <span class="n">0.16</span>)],
                        GUNMETAL), <span class="s">&quot;Wrist&quot;</span>)
         <span class="c"># palm block (rigid on Wrist)</span>
-        box_part(bm, (<span class="n">0.26</span>, <span class="n">0.20</span>, <span class="n">0.14</span>), (<span class="n">0.0</span>, <span class="n">0.0</span>, <span class="n">2.99</span>),
+        box_part(bm, (<span class="n">0.30</span>, <span class="n">0.22</span>, <span class="n">0.24</span>), (<span class="n">0.0</span>, <span class="n">0.0</span>, <span class="n">2.98</span>),
                  (<span class="n">0</span>, <span class="n">0</span>, <span class="n">0</span>), GUNMETAL, part_of, <span class="s">&quot;Wrist&quot;</span>)
         <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.09</span>, <span class="n">3.11</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.15</span>, <span class="n">3.28</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.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>))):
                 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,10 +1,10 @@
 # Vertex Weight Limit
 
 A runnable example that rigs a mech arm — bolted pedestal and shoulder
-fairing, a shoulder hub and clevis-ended upper arm, the elbow hinge pin inside
-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
+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
 **maximum of four bone influences per vertex** through the data API, following
 [`mesh-editing-and-bmesh`](../../skills/mesh-editing-and-bmesh/SKILL.md) and
 building on the linear-blend-skinning precedent of

examples/vertex-weight-limit/vertex_weight_limit.py

@@ -42,7 +42,7 @@
 BONE_SPANS = {"Root": (-0.35, 0.10), "Shoulder": (0.10, 1.35),
               "Elbow": (1.35, 2.55), "Wrist": (2.55, 2.90), "Claw": (2.90, 3.35)}
 BONE_CENTERS = {b: (s[0] + s[1]) / 2 for b, s in BONE_SPANS.items()}
-POSE_DEG = {"Shoulder": -8.0, "Elbow": -35.0, "Wrist": -18.0, "Claw": 12.0}
+POSE_DEG = {"Shoulder": -8.0, "Elbow": -35.0, "Wrist": -14.0, "Claw": 6.0}
 
 # armor palette slots
 GUNMETAL, ORANGE, RUBBER, ACCENT = 0, 1, 2, 3
@@ -126,25 +126,24 @@ def tag(rings_verts, bone):
             cone_part(bm, 0.05, 0.04, 0.06,
                       (0.36 * math.cos(a), 0.36 * math.sin(a), 0.03),
                       (0, 0, 0), GUNMETAL, part_of, "Root")
-        # shoulder hub poking through the fairing (rigid on Shoulder)
-        cone_part(bm, 0.19, 0.19, 0.56, (0.0, 0.0, 0.62), (90, 0, 0),
-                  GUNMETAL, part_of, "Shoulder")
-        # upper arm shell, slimmer than the old barrel (rigid on Shoulder)
-        tag(lathe_part(bm, [(0.45, 0.19), (0.60, 0.23), (0.80, 0.24),
-                            (1.00, 0.23), (1.15, 0.21)], ORANGE), "Shoulder")
+        # upper arm shell rooted deep inside the fairing — no gap at the
+        # shoulder when the joint articulates (rigid on Shoulder)
+        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)
         for sy in (-1, 1):
             box_part(bm, (0.12, 0.05, 0.42), (0.0, sy * 0.165, 1.24),
                      (0, 0, 0), ORANGE, part_of, "Shoulder")
         # elbow flex bellows: the five-influence zone the limit prunes
-        tag(lathe_part(bm, [(1.15, 0.17), (1.20, 0.20), (1.26, 0.16),
-                            (1.33, 0.20), (1.40, 0.16), (1.47, 0.20),
-                            (1.55, 0.17)], RUBBER), "FLEX")
+        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),
                   GUNMETAL, part_of, "Elbow")
         for sy in (-1, 1):
-            cone_part(bm, 0.18, 0.18, 0.05, (0.0, sy * 0.225, 1.35),
+            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
@@ -157,19 +156,19 @@ def tag(rings_verts, bone):
         box_part(bm, (0.10, 0.05, 0.60), (0.0, 0.235, 2.02),
                  (0, 0, 0), ORANGE, part_of, "Elbow")
         # wrist flex bellows (second blend zone) + collar
-        tag(lathe_part(bm, [(2.45, 0.16), (2.51, 0.19), (2.57, 0.15),
-                            (2.64, 0.18), (2.70, 0.15), (2.75, 0.16)],
+        tag(lathe_part(bm, [(2.45, 0.18), (2.51, 0.20), (2.57, 0.16),
+                            (2.64, 0.19), (2.70, 0.16), (2.75, 0.17)],
                        RUBBER), "FLEX")
         tag(lathe_part(bm, [(2.75, 0.16), (2.85, 0.175), (2.90, 0.16)],
                        GUNMETAL), "Wrist")
         # palm block (rigid on Wrist)
-        box_part(bm, (0.26, 0.20, 0.14), (0.0, 0.0, 2.99),
+        box_part(bm, (0.30, 0.22, 0.24), (0.0, 0.0, 2.98),
                  (0, 0, 0), GUNMETAL, part_of, "Wrist")
         # 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.09, 3.11), 12.0, (0.075, 0.11, 0.22)),
-                                    ((0.15, 3.28), 26.0, (0.06, 0.095, 0.18))):
+            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))):
                 off, z = pos
                 m = (mathutils.Matrix.Translation((0.0, 0.0, z))
                      @ mathutils.Matrix.Rotation(a, 4, 'Z')