docs: record why bone-scale volume preservation does not work here

Tried widening the helper bone to cancel the joint collapse. The geometry is
right — blending two rotations θ apart thins anything perpendicular to the bend
by exactly cos(θ/2), which is |q.w| of the pose rotation, so scaling the helper
across the bone by the reciprocal is the exact correction.

It does not work, because a BONE scale is the wrong granularity. It fattens
every vertex weighted to the helper whether or not that vertex was collapsing:
parts of the thigh ballooned to 167% while the worst-collapsing vertices, which
are not on the helper at all, stayed at 0.83. The idea needs per-vertex
correction and a bone cannot express it. Removed, with the reasoning kept in the
file so it is not retried.

Hip joints were also retested, since two other variables had changed since the
first attempt (one-joint-per-vertex, and the limb gate removed). Same verdict a
second time: upper thigh 0.90 -> 0.84, and the skirt 0.80 -> 0.72. Knees only.

Shipped state is unchanged from the previous commit; this is the reasoning and a
revert of an experiment.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
Nicholas Butzke
2026-07-22 08:49:14 -04:00
co-authored by Claude Opus 4.8
parent 1ab7e99231
commit d33f9cd812
+13
View File
@@ -108,6 +108,19 @@ static func _dist_to_chain(p: Vector3, chain: PackedVector3Array) -> float:
## Drive the helpers. MUST run inside the skeleton's modification pass. ## Drive the helpers. MUST run inside the skeleton's modification pass.
##
## Two things happen per joint:
##
## ROTATION — the helper takes half the child's bend, so no vertex ever blends
## across the full angle.
##
## Scaling the helper to widen the joint back out was tried and removed. The
## geometry is right — a blend across θ thins by cos(θ/2), which is |q.w| — but a
## BONE scale is far too blunt an instrument for it: it fattens every vertex on
## the helper regardless of whether that vertex was collapsing, which ballooned
## parts of the thigh to 167% while the worst-collapsing vertices (which are not
## on the helper at all) did not move off 0.83. Per-vertex correction is what
## that idea needs, and a bone cannot express it.
static func update(skeleton: Skeleton3D, driven: Array) -> void: static func update(skeleton: Skeleton3D, driven: Array) -> void:
for d in driven: for d in driven:
skeleton.set_bone_pose_rotation(d[1], skeleton.set_bone_pose_rotation(d[1],