GizStackGizStack
View .mdOpen in ChatGPTOpen in Claude

gizlang/retarget

a humanoid motion moved onto another humanoid skeleton, whatever its rest pose and proportions.

The two skeletons' joints are matched by the humanoid bones they are (VRM's names): the limbs and the head by the names motion files and character tools give them, the spine by its place between the hips and the neck. A skeleton whose joints have no such names (a rig a model drew) is read by its shape: the lowest joint on each side of the highest one are the feet, the joint they and the highest hang from the hips, and the two chains of farthest reach that leave the spine's upper half and stay above the hips the arms (a cape or a tail hangs lower), the left one whose shoulder is more to +x (hands that hold one sword cross). A source joint's motion is its world rotation over the clip's mean world rotation; the target joint takes that turn from its own rest, so a character keeps how it stands (arms holding a sword, an A pose, a T pose) and moves as the source does about it. A limb takes the turn as far as its rest agrees with the source's mean pose of it (the cosine of its bones' directions, the least of the limb's): legs that stand as the walker's walk as it does, arms that hold a sword forward keep holding it and move with the chest. Hands that hold one thing together (closer than a fifth of the hips' height) keep it whole: both arms, from the upper arms out, move as one stiff part. It rides the joint the arms part at (the chest) and turns about the line through the shoulders, the one turn that keeps both shoulders in place, by the mean angle the source's hands turn about its own shoulders' line: a two-handed blow swings the blade, arms that swing against each other in a walk leave it still. The clip is cut to the loop whose ends are most alike, turned so the source walks toward +z (glTF's front, whose left is +x), and played in place: the root keeps its sway and bounce, scaled by the hips' heights.

gizlang
import * as Retarget from "gizlang/retarget";

Types

Rest

gizlang
type Rest = { names: Vec<string>; parents: Vec<i64>; offsets: Vec<Point3>; rotations: Vec<Rotation>; }

A skeleton at rest: each joint's name, parent (-1: a root; parents come first), offset from its parent and rotation in its parent's frame.

  • names: Vec<string>
  • parents: Vec<i64>
  • offsets: Vec<gizlang_geometry.Point3>
  • rotations: Vec<gizlang_geometry.Rotation>

Frames

gizlang
type Frames = { rest: Rest; rotations: Vec<Vec<Rotation>>; roots: Vec<Point3>; seconds: f64; }

A motion of a skeleton at rest: each frame's joint rotations (in their parents' frames) and its root's position.

  • rest: gizlang_retarget.Rest
  • rotations: Vec<Vec<gizlang_geometry.Rotation>>
  • roots: Vec<gizlang_geometry.Point3>
  • seconds: f64

Clip

gizlang
type Clip = { name: string; times: Vec<f64>; rotations: Vec<Vec<Rotation>>; root: i64; positions: Vec<Point3>; }

A clip for a skeleton: its times in seconds, each time's joint rotations (in their parents' frames), and the root joint (root) with each time's position.

  • name: string
  • times: Vec<f64>
  • rotations: Vec<Vec<gizlang_geometry.Rotation>>
  • root: i64
  • positions: Vec<gizlang_geometry.Point3>

Way

gizlang
type Way = { cut: bool; reference?: Frames; }

How a motion becomes a clip: CUT, to its best loop (a motion capture's take; none: whole, as a clip made to loop or to play once is), and REFERENCE, the motion whose mean pose each bone's turn is taken from (none: the motion's own; one pose for all the clips of a source, such as its idle, keeps a fall lying and a sitting seated).

  • cut: bool
  • reference: _gizlang_sdk_core.Option<gizlang_retarget.Frames>

Functions

humanoid

gizlang
function humanoid(r: Rest): Vec<i64> throws string

Each joint of skeleton R as a humanoid bone (an index of BONES), -1 for none: by its joints' names where they name the hips, the neck and the legs, else by its shape. Throws where neither finds a humanoid.

Effects: fail, read, write, console, io, alloc.

retarget

gizlang
function retarget(motion: Frames, target: Rest, name: string, fps: f64 = 30.0, how: Way = { cut: true }): Clip throws string

MOTION (a humanoid's) as a clip NAME of skeleton TARGET (a humanoid's) at FPS frames a second (the header).

Effects: fail, read, write, console, io, alloc.

Constants

BONES

gizlang
const BONES: Vec<string> = ["hips", "spine", "chest", "upperChest", "neck", "head", "leftShoulder", "leftUpperArm", "leftLowerArm", "leftHand", "rightShoulder", "rightUpperArm", "rightLowerArm", "rightHand", "leftUpperLeg", "leftLowerLeg", "leftFoot", "leftToes", "rightUpperLeg", "rightLowerLeg", "rightFoot", "rightToes"]

The humanoid bones (VRM): the body's, then each side's arm and leg.