Skip to content

feat: add armature-bend example (edit_bones + LBS closed-form witness)#58

Merged
TMHSDigital merged 1 commit into
mainfrom
feat/armature-bend-example
Jul 18, 2026
Merged

feat: add armature-bend example (edit_bones + LBS closed-form witness)#58
TMHSDigital merged 1 commit into
mainfrom
feat/armature-bend-example

Conversation

@TMHSDigital

Copy link
Copy Markdown
Owner

Summary

Adds examples/armature-bend — the highest-priority gallery coverage gap (rigging): a four-bone armature chain built with edit_bones skins a tapered, segmented tube through name-bound vertex groups with smoothstep blend zones, poses a curl, and reads the result back through the depsgraph.

API contract witnessed

  1. edit_bones lifetime — asserted empty in object mode; inside mode_set(mode='EDIT') the chain must exist with heads/tails at closed-form positions. Reads outside edit mode silently return nothing.
  2. Vertex groups bind by name — every group is named after its bone; a typo deforms nothing without erroring. The deform proves the binding.
  3. The armature modifier is exactly linear blend skinning — every depsgraph-evaluated vertex is compared against a re-implemented Σ wᵢ · (pose_bone.matrix @ bone.matrix_local.inverted()) @ rest (max error observed 4.77e-07); the root ring must stay pinned and the tip must deflect. A straight tube exits non-zero.

4.5/5.1 divergence: the armature API itself is identical on both — no version gate. A real portability hazard is documented in-code: holding a color_attributes reference across VertexGroup.add() dangles it when the deform CustomData layer allocates — a hard EXCEPTION_ACCESS_VIOLATION on 4.5.11 that 5.1.2 survives by luck. The script orders all weight writes before creating the attribute.

Visual notes

Rest → half curl → full curl left to right; the rigs are rotated so the curl sweeps across the picture plane. Per-bone weight bands (teal → cyan → amber → coral) are a BoneTint color attribute computed from the same weights the LBS check asserts, so the color blends at the joints are the contract. Dark-studio recipe matching the existing gallery. Inspected at full 1280×720 and at 1200×675 preview scale.

Test plan

Proven by live run (local):

  • Check-only path on Blender 4.5.11 LTS — exit 0, lbs_max_err=4.77e-07 tip_deflection=3.191
  • Check-only path on Blender 5.1.2 — exit 0, identical figures
  • --output render on 5.1.2 (EEVEE), pixels inspected at full size and thumbnail scale
  • python scripts/build_gallery.py regenerated (18 detail pages)
  • Local equivalents of validate-counts (12/6/2/17/18) and validate-manifest (all paths exist, examples list matches disk, version == VERSION)

Established by inspection only:

  • Generated gallery HTML diff limited to the new entry
  • CI smoke jobs (Linux/xvfb) — this PR's checks are the authoritative run

🤖 Generated with Claude Code

Nothing in the gallery touched rigging, and armature code is where
AI-generated Blender Python fails silently most often: edit_bones reads
outside edit mode return nothing, and a mistyped vertex-group name deforms
nothing without erroring. This example builds a four-bone chain via
edit_bones, skins a tapered tube through name-bound vertex groups with
smoothstep blend zones, poses a curl, and asserts the armature modifier is
exactly linear blend skinning — every depsgraph-evaluated vertex must equal
the re-implemented closed form (root ring pinned, tip deflected; a straight
tube fails). It also bakes in a portability hazard found while authoring:
holding a color-attribute reference across VertexGroup.add() dangles it when
the deform layer allocates — a hard crash on 4.5 LTS that 5.1 survives by
luck — so all weight writes finish before the attribute is created.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@github-actions github-actions Bot added documentation Improvements or additions to documentation ci labels Jul 18, 2026
@TMHSDigital
TMHSDigital merged commit 01c186b into main Jul 18, 2026
9 checks passed
@TMHSDigital
TMHSDigital deleted the feat/armature-bend-example branch July 18, 2026 22:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant