Deform Doctor

A single-file Blender add-on that is a deformation debugger and deformation fixer in one — built for skinned characters headed into game engines (VRChat in particular), where bad weights and pose-dependent deformation are the difference between a clean avatar and a melting one.

It diagnoses where a mesh deforms badly, lets you see before vs after as an overlay or side-by-side, verifies that no pose hides deformation, detects and resolves body-vs-clothing clipping, and fixes the underlying weight problems in place — all without touching topology.

What it does

Diagnose

• Audit Weights — counts unweighted verts, verts over the influence limit (VRChat caps at 4 bones/vert), and non-normalized verts. One-click select of each problem set.
• Distortion Heatmap — paints per-vertex stretch/compression between the rest pose and the current pose (blue = stable, red = stretched) into a color attribute.
• Sweep All Poses — steps through every pose frame you list (1,2,3 or ranges like 1-3,10), measures deformation in each, and paints the worst-case stretch any vertex sees across all of them, flagging the worst-offending pose. This is how you confirm no pose you forgot to check is quietly breaking.

Before / After

• Snap Before / Snap After — freeze the deformed geometry at any pose, before and after a fix.
• Overlay (ghost) — your live model stays on screen as the solid; the "Before" state rides on top as a red wireframe ghost. The live mesh is never hidden or made unselectable.
• Side by side — Before on the left, After on the right, clean solid shading.
• Diff Map (opt-in) — tints only the vertices that actually moved; everything unchanged stays neutral grey, so it never floods the model like a weight-paint dump.

Fix (operates directly on weight data — no mode juggling)

• Normalize — make per-vertex deform weights sum to 1.
• Limit Influences — cap influences per vertex to the limit (VRChat = 4), keeping the strongest and renormalizing.
• Prune Tiny Weights — drop weights below a threshold and renormalize.
• Remove Empty Groups — strip deform groups with no weight.
• Smooth Weights — relax deform weights across mesh edges (factor + iterations); respects a vertex selection when there is one.
• Mirror Weights — symmetrize weights left/right across X using .l/.r or _l/_r group pairs.
• Corrective Smooth — add or refresh a Corrective Smooth modifier after the Armature to relax deformation.
• Auto Clean Weights (one click) — runs the safe sequence normalize → smooth → normalize → limit-to-N → normalize, optionally snapshots Before/After, and re-audits. This is all most users need.

Order matters: smoothing spreads influence onto neighbouring bones, so capping to 4 before smoothing lets the smooth blow the cap right back open. Limit last, every time. Auto Clean already does this.

Works from any mode: the weight operators auto-switch to Object Mode for the write (Blender forbids weight edits in Edit / Weight-Paint Mode) and restore your mode afterward. If you select verts in Edit Mode, Smooth Weights affects only that selection.

Whole avatar + clothing

• Scope — switch between Active Mesh and Whole Avatar. In Whole-Avatar scope the audit and every fixer run across all meshes bound to the armature (body + clothing/accessory layers) in a single pass.
• Clothing / Clipping — detect where clothing penetrates the body at the current pose (Check Clipping) or worst-case across all listed poses (Sweep Clipping), painted per clothing mesh. Transfer Weights Body → Clothing copies the body's deform weights onto the clothing (Blender Data Transfer) so the two deform together. Run Limit-to-4 + Normalize (Whole-Avatar scope) afterward.
• Auto-Fix Clipping (one button) — geometrically resolves clipping either way: Tuck Body Under Clothing (when the body pokes out through the clothes) or Push Clothing Off Body (when clothing sinks into the body). Iterative, skinning-aware (maps the correction back through the vertex skinning to the base mesh), and shape-key-aware. Optional weight-transfer-first and all-poses resolution.

Simple vs Advanced

A Simple / Advanced toggle sits at the top of the panel. Simple shows only the essentials (Set From Selection, Audit, Sweep All Poses, Snap Before/After, and one-click Auto Clean Weights). Advanced reveals every operator and property. Full reference: DOCS.md.

How it works

The distortion metric is the mean fractional change in edge length between the rest pose and a posed state, measured per vertex against its edge-neighbours (0.0 = no local stretch). To keep vertex indices stable while sampling, non-armature modifiers are temporarily disabled and the armature's pose position is toggled between REST and POSE — so the heatmap reflects armature deformation only.

Clipping detection builds the body's armature-deformed surface into a BVH tree and tests each clothing vertex against it (nearest-point plus surface-normal side) for penetration depth. Auto-Fix pushes offending vertices to the correct side of the surface and maps that correction back through a per-vertex linear-blend-skinning matrix (and into shape-key data when present) so the edit survives posing.

All weight reads and writes go directly against mesh.data — no weight-paint operator round-trips — which is why the fixers are mode-independent.

Installation

1. Blender → Edit → Preferences → Add-ons → Install from Disk…
2. Pick deform_doctor.py (or a zipped release).
3. Enable "Deform Doctor".
4. In the 3D viewport press N to open the sidebar, then select the Deform Dr tab.

Use

1. Setup — set the Mesh + Armature (or hit Set From Selection), and choose the Fix scope.
2. Diagnose — Audit Weights, then Sweep All Poses to find the worst pose.
3. Before/After — Snap Before, run fixes, Snap After, compare.
4. Fix — Auto Clean Weights, or the manual normalize → smooth → normalize → limit → normalize path.
5. Re-sweep to confirm the numbers dropped without wrecking the silhouette.

Blender version support

• Declared minimum: Blender 2.93 (bl_info blender = (2, 93, 0)).
• Built and tested on: Blender 2.93.0 and 5.1.2 (heatmap runtime-verified on both); exercised across the 4.4+/5.x line.
• Cross-version note: the deformation heatmap uses mesh.color_attributes on Blender 3.2+ and falls back to loop-domain mesh.vertex_colors on 2.93–3.1 automatically.
• Dependencies: none beyond Blender's own bundled modules (bpy, bmesh, mathutils). OS-agnostic — identical on Windows / macOS / Linux.

Companion script: refit_rig.py

refit_rig.py is a separate helper script, not part of the add-on (no UI, no registration). Run it from Blender's Text editor after changing any MPFB macro (ethnicity, height, weight, proportions) on a rigged MakeHuman/MPFB avatar — those macros reshape the mesh but leave the bones behind. It re-fits standard bones via MPFB's RigService.refit_existing_armature, then recomputes custom twist bones (upperarm / lowerarm / thigh) and jiggle bones (butt / belly / thigh-jiggle) from the new mesh. The rest shape is unchanged — only bone rest positions move — so the bind stays valid and weight/VRChat-legality are untouched. Requires MPFB installed and expects the body object named Human and armature Human.rig (editable at the top of the script).

Part of the Unity AI Lab Blender suite

Deform Doctor is one of the Unity AI Lab Blender plugins. Each tool in the suite is standalone — install and use it on its own — but they are designed to interoperate cleanly with their siblings on the same avatar:

• Texturly — quick PBR materials, edge-trim, and bake-to-texture for VRChat worlds
• Cats Blender Expanded — avatar import, prep and optimization
• Jiggle Lab — measured jiggle-physics rigging (routes its weight cleanup through Deform Doctor when present)

Self-hosted on Forgejo at git.unityailab.com, org UnityAILab. Clone: git@git.unityailab.com:UnityAILab/blender-deform-doctor.git

License

Not yet declared in-repo (no LICENSE file, no bl_info license field). The Unity AI Lab Blender suite ships under GPL-3.0-or-later; a matching LICENSE for Deform Doctor is pending. Until it lands, treat usage terms as reserved by Unity AI Lab.