PoseWeave User Manual

Interactive IK Character Posing Tool for Blender

Overview

PoseWeave helps Blender artists pose supported humanoid armatures using target-driven inverse kinematics (IK). It combines limb posing, rig mapping, contact controls, checkpoints, pose mirroring, and keyframing utilities in one workflow.

Main features

• Two-bone IK for supported arms and legs.

• Interactive hand and foot targets.

• Viewport target dragging with axis and plane constraints.

• Rig discovery, mapping, and validation.

• Foot locking and hand pinning.

• Named pose checkpoints.

• Pose mirroring.

• Keyframe insertion.

• Reachability and contact diagnostics.

1. System requirements

• Blender: 4.2 LTS or 4.5.

• Software category: Animation and rigging.

• License: MIT.

Rig compatibility depends on the armature structure and rig adapter. Mapping a rig's bone names does not guarantee compatibility with its constraints, drivers, or control system.

2. Installation

1. Download the PoseWeave ZIP supplied by the publisher.

2. Open Blender and navigate to Edit → Preferences.

3. Open the add-on or extension installation area available in your Blender version.

4. Install PoseWeave from the supplied ZIP.

5. Enable the add-on.

6. Open the 3D Viewport and press N to display the Sidebar.

7. Select the PoseWeave tab.

If the panel does not appear, verify that the add-on is enabled and check the Blender console for errors.

3. Your first posing session

1. Open a scene containing a humanoid armature.

2. Select and activate the armature.

3. Open PoseWeave in the 3D Viewport Sidebar.

4. Run Discover / Map Rig.

5. Inspect the mapping and validation messages.

6. Resolve missing or ambiguous bone roles before continuing.

7. Begin a posing session.

8. Select the hand or foot target you want to manipulate.

9. Set the target position or use the viewport dragging tool.

10. Run Solve Target.

11. Inspect the reachability status and residual.

12. Apply contact controls, create checkpoints, or mirror the pose as needed.

13. Insert keyframes when you want to record the pose.

14. Commit the session to keep your changes or cancel it to restore the starting state.

Panel labels may vary slightly between builds.

4. Working with IK targets

Inverse kinematics calculates a supported limb configuration to move an endpoint toward a target.

PoseWeave uses two-bone IK. A target may be unreachable if it lies outside the limb's geometric reach.

• Reachable: The requested target is within the solver's valid range.

• Approximated or unreachable: The exact target cannot be achieved; inspect the reported status.

• High residual: The resulting endpoint or contact differs noticeably from the requested position.

To troubleshoot an unreachable target, move it closer to the limb, check the mapping, and inspect active contacts.

5. Viewport target manipulation

PoseWeave provides a target-dragging workflow with axis and plane constraints.

• Use the available controls to constrain movement along X, Y, or Z.

• The documented plane constraints use Shift+X, Shift+Y, and Shift+Z.

• Confirm the drag with a click.

• Press Right Mouse Button or Esc to cancel and restore the drag's starting position.

If viewport dragging behaves unexpectedly, cancel the operation and use numeric target-position controls where available.

6. Foot locking and hand pinning

These controls capture an endpoint position and ask the solver to preserve it as a high-priority contact during subsequent posing operations.

For best results:

1. Position the foot or hand where you want the contact.

2. Enable the appropriate lock or pin.

3. Make further posing changes.

4. Review the contact residual and diagnostic messages.

Conflicting contacts or unreachable targets may prevent perfect contact. Object-relative contact locks are not implemented in this release.

7. Pose checkpoints

Checkpoints let you save named pose states before experimenting.

1. Create a checkpoint.

2. Give it a meaningful name.

3. Modify the pose.

4. Restore the checkpoint if you want to return to the saved state.

5. Rename or delete checkpoints as needed.

Avoid deleting or replacing the active armature while a posing session is running.

8. Pose mirroring

Pose mirroring reflects target records between sides and re-solves the corresponding limbs. It can speed up the creation of symmetrical starting poses.

Always inspect the result. Asymmetrical rigs, custom bone axes, different limb proportions, and unsupported constraints can affect the mirrored pose.

9. Keyframing

PoseWeave can insert keyframes on mapped control bones at the current frame.

1. Move the timeline to the desired frame.

2. Create and inspect the pose.

3. Use the keyframing action.

4. Scrub the timeline to check the result.

5. Repeat on other frames as required.

Existing keys on relevant channels are protected unless overwrite is explicitly requested. A Python API utility, animation_tools.bake_frames, is documented for frame baking; this should not be interpreted as a complete one-click baking interface.

Save a separate project copy before substantial animation edits.

10. Rig mapping and compatibility

PoseWeave recognises common humanoid naming conventions, including some Mixamo-style names and common prefixes.

The supplied rig documentation explicitly marks test_humanoid_v1 as tested. Other rigs may be mapped, but successful name matching does not guarantee full support.

For unsupported or incorrectly mapped rigs:

1. Confirm the correct armature is selected.

2. Inspect the relevant bone names.

3. Resolve missing or ambiguous roles using available mapping controls.

4. Run validation again.

5. Test a simple pose before production use.

Universal compatibility with Rigify, Auto-Rig Pro, Mixamo, or arbitrary custom rigs is not claimed.

11. Troubleshooting

12. Known limitations

• Full-body IK optimisation and automatic balance are outside the scope of this release.

• Only test_humanoid_v1 is explicitly marked as tested in the supplied rig-support documentation.

• Generic bone-name matching does not guarantee third-party rig compatibility.

• Object-relative contact locks are not implemented.

• Non-uniform armature-object scale is detected and may cause validation to reject the setup.

• Poses and keyframes should be verified on the specific rig before production use.

13. Support

For support, include your PoseWeave version, Blender version, operating system, rig type, steps to reproduce the problem, and any exact error message.

Support email: [email protected]

14. License

PoseWeave is distributed under the MIT License. See the included LICENSE file for the full terms.