# gizlang/rigging

a character's parts rigged on its skin, one way for every maker of characters (a MetaHuman's import, a person made from a photograph). A part takes the weights of the skin under it (bind: Robust Skin Weights Transfer, Abdrashitov and others 2023), so it bends as the skin does and the skin shows through it nowhere. Where a part and the skin cross at rest, the one that is a guess yields to the other as a smooth field (conform, as Character Creator conforms clothes). Its loose parts hang on chains of joints that a game swings (swung: VRMC_springBone, gizlang/gltf Rig), resting on colliders fitted inside the skin (collided).

```gizlang
import * as Rigging from "gizlang/rigging";
```

## Types

### `Skin`

```gizlang
type Skin = { skeleton: Gltf.Skeleton; positions: Vec<f64>; triangles: Vec<i64>; joints: Vec<i64>; weights: Vec<f32>; lanes: i64; }
```

A skin to rig parts on: its SKELETON, its places (x, y, z a vertex) and triangles, and each vertex's LANES joints
and their weights.

- `skeleton`: `gizlang_gltf.Skeleton`
- `positions`: `Vec<f64>`
- `triangles`: `Vec<i64>`
- `joints`: `Vec<i64>`
- `weights`: `Vec<f32>`
- `lanes`: `i64`

### `Weights`

```gizlang
type Weights = { joints: Vec<i64>; weights: Vec<f32>; }
```

Each vertex's joints and weights, as many a vertex as its skin's lanes.

- `joints`: `Vec<i64>`
- `weights`: `Vec<f32>`

### `Edges`

```gizlang
type Edges = { one: Vec<i64>; near: Vec<Vec<i64>>; }
```

A surface's edges: each vertex's neighbours, the copies of one place (a texture's seam splits them) joined as the
first of them (ONE).

- `one`: `Vec<i64>`
- `near`: `Vec<Vec<i64>>`

### `Walk`

```gizlang
type Walk = { distance: Vec<f64>; origin: Vec<i64>; }
```

Each vertex's distance over EDGES (of POSITIONS) from the nearest of SOURCES, and that source (-1, -1: none
reaches it; Dijkstra). A vertex is its first copy's (Edges one).

- `distance`: `Vec<f64>`
- `origin`: `Vec<i64>`

## Functions

### `edgesOf`

```gizlang
function edgesOf(positions: Vec<f64>, triangles: Vec<i64>): Edges
```

Effects: fail, alloc.

### `walked`

```gizlang
function walked(p: Vec<f64>, edges: Edges, sources: Vec<i64>): Walk
```

Effects: fail, alloc.

### `bind`

```gizlang
function bind(positions: Vec<f64>, triangles: Vec<i64>, skin: Skin, joins: ((a: i64, b: i64) => bool) | undefined = undefined): Weights
```

The weights of the part POSITIONS and TRIANGLES on SKIN, its lanes a vertex (Robust Skin Weights Transfer,
Abdrashitov and others 2023): a vertex with a confident match (near, its normal agreeing, and no part of the part much
nearer that skin vertex: a sleeve over the arm matches, jeans beside a hand do not) takes the skin vertex's weights;
the others are inpainted along the part's edges (from the nearest matched vertex, then averaged until they settle).
JOINS, when given, says which joints' parts join (a hand fused to a thigh beside it does not): the weights settle
again without the edges between parts that never join.

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

### `heaviest`

```gizlang
function heaviest(w: Weights, lanes: i64): Vec<i64>
```

Each vertex's heaviest joint of W (LANES a vertex).

Effects: fail, alloc.

### `kept`

```gizlang
function kept(joints: Vec<i64>, weights: Vec<f64>, lanes: i64): Weights
```

One vertex's weights: the LANES heaviest of JOINTS (their WEIGHTS), summing to one, the rest of the lanes joint 0
at no weight; what a skin keeps of a vertex that more joints pull.

Effects: fail, alloc.

### `bound`

```gizlang
function bound(part: Gltf.Written, skin: Skin): Gltf.Written
```

PART on SKIN: its weights (bind) and its skeleton the skin's.

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

### `conform`

```gizlang
function conform(soft: Vec<f64>, softs: Vec<i64>, hard: Vec<f64>, hards: Vec<i64>, gap: f64, reach: f64, side: f64): Vec<f64>
```

The places of the surface SOFT (x, y, z a vertex; SOFTS its triangles) that yield to the surface HARD (HARDS its
triangles) where they cross: SIDE 1 keeps SOFT outside HARD by GAP (a garment over fitted skin), -1 inside it by GAP
(skin that is a guess, under a garment). Each vertex on the wrong side moves along HARD's normal there to GAP; the
move spreads over SOFT as a smooth field, each vertex taking its nearest moved vertex's move (over SOFT's edges),
less with the distance, to none at REACH: a collar or a hat grows evenly and keeps its shape, where vertices moved one
by one tore it into shards. HARD is looked for within REACH of each vertex.

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

### `swung`

```gizlang
function swung(parts: Vec<Gltf.Written>, skin: Skin): Vec<Gltf.Written> throws string
```

PARTS with their loose parts on chains that swing. Of each garment or hair part on SKIN's skeleton, the vertices that
hang SWINGS or more from where the skin holds them fall into clumps; each clump becomes a chain of joints from the
clump's bone, its vertices bending onto it the farther they hang. The skeleton carries the chains' springs and the
colliders fitted to SKIN (collided), and its behavior a rest frame for each new joint; every part on it takes it.

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

### `collided`

```gizlang
function collided(skin: Skin): Vec<Gltf.Collider> throws string
```

The colliders of SKIN's skeleton that its loose parts rest on: a sphere about the head, capsules along the neck, the
chest and each shoulder, upper arm and thigh, each holding all but INSIDE of the skin's vertices about it and none of
the skeleton's springs' swinging joints.

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

### `skinOf`

```gizlang
function skinOf(parts: Vec<Gltf.Written>): Skin throws string
```

The skin of PARTS (written parts on one skeleton, as many joints a vertex each): their places, triangles and weights
as one surface.

Effects: fail, alloc.

## Methods

### `Reached.less`

```gizlang
function Reached.less(self: Reached, other: Reached): bool
```

