@rig-c/parts 1.10.0 → 1.11.0

package/docs/AUTHORING.md

@@ -95,6 +95,7 @@ read by no CPU stage).
 | `meshes.<part>` | rig | **proposed**, then corrected. Exactly one of `grid` (the lattice: cell size, px — what `propose` writes: by default one spacing for the figure, round(H / 37) rig px with H the height of every part's box together, a part whose tenth of its short side is already coarser keeping that, and under `propose --grid-rule part` the reference's tenth of the part's short side clamped to 5..36, issue #265), `contour` (the outline mode, authored; the next row and "A contour mesh" below) or `auto` (the automatic mode, authored; "An automatic mesh" below) — two, or none, is `CONFIG_MESH_MODE`. In every mode: `r` (added to every distance before weighting: `w = 1/(d + r)²`), `segments` (a chain name, a bone name with a `tip`, or `[bone, [x0,y0], [x1,y1]]`), and, **authored**, optional, `exponent` (issue #161): a number above 0 that replaces the 2 in that rule, `w = 1/(d + r)^exponent` — a larger one hands each vertex more fully to its nearest bone; absent is 2 and changes no byte, a value that is not a number above 0 is `CONFIG_FIELD_TYPE` at `meshes.<part>.exponent`, and a declared one is echoed as `exponent` in the mesh's `mesh_report.json` row; the exponent is the distance rule's, so declared beside `rule: "heat"` it is refused (`CONFIG_FIELD_TYPE` at `meshes.<part>.exponent`). The segment list is the one authored decision about a layer: which bones may pull it. The slot's bone is the first segment's. Optional `rule` (issue #161): `"distance"` — the rule above, and what an absent `rule` means (every byte is the same) — or `"heat"`, bone heat over the part's own silhouette, in every mode: the lattice's art (alpha above 8) with holes filled, or for `contour` and `auto` the silhouette their outline is traced from (that mode's art — alpha above 8 for `contour`, alpha 1 and above for `auto` — less any island a declared `stray` left out, holes filled, grown by its `margin`); each bound bone's sources are the silhouette pixels whose centre lies within 0.75 px of its segment (a pixel two bones reach goes to the nearer, a tie to the first listed), held at 1 for that bone and 0 for the others; the field is solved by row-major Gauss–Seidel over-relaxation to a sweep change under 1e-7 within 20000 sweeps; a vertex reads the nearest silhouette pixel and takes the same cap and floor (and `regions`) as the distance rule; `r` is not read. The mesh's `mesh_report.json` row gains `heat` (the constants, each bone's sources and sweeps, the residual). Any other value is `CONFIG_FIELD_TYPE`; a bound bone with no source pixel is `RIG_HEAT_BONE_SOURCE`, an island no bone has a source in `RIG_HEAT_ISLAND_SOURCE`, a solve past its sweep bound `RIG_HEAT_CONVERGED` — none is weighted 0 |
 | `meshes.<part>.contour` | rig | **authored**, optional (issue #84): `{tolerance, margin, spacing, maxEdge?, budget?, stray?, regions?}`. `tolerance` — rig-c's Douglas–Peucker tolerance on the traced outline, px, 0 or more; `margin` — how far the silhouette grows before it is traced, px: 0, or 1 or more (a pixel joins when its centre lies within `margin` of an art pixel's centre; a value above 0 and below 1 adds nothing and is refused, `CONFIG_FIELD_TYPE`); `spacing` — the background interior spacing, px, above 0; `maxEdge` (issue #265) — the longest outline edge, px, above 0: every simplified edge longer than it is cut into `ceil(length / maxEdge)` equal pieces, each cut point on the 1/256 px grid, before any region or rib touches the outline (absent: nothing is cut, and no byte moves; under 2/256 px the rig stage refuses it, `CONTOUR_PARAMETER`, because two cut points could snap together); the row echoes it in `params` and counts the points it added in `contour.outlineCut`, both only when declared; `budget` — the most vertices the mesh may have (refused above it, nothing thinned); `stray` — the largest island, in art pixels, that may be left out of the mesh (absent: none is); `regions` — local deformation regions, each `{name, shape, bone, spacing, band}` with `shape` `"circle"` (`cx, cy, r`) or `"polygon"` (`points`, 3 or more): `bone` is the region's control bone (any bone `bones` declares), `spacing` the interior spacing inside the region and its band, `band` the width the bone's weight falls across. Every length and position is **rig px**, like every other in the config; the part image is the rig less `(x − 4, y − 4)` (its box less the pad), a translation, so a length is the same number in both. A region's `cx`, `cy`, `r`, `band` and `points` are multiples of 1/256 px (`CONFIG_FIELD_TYPE` otherwise); region names are unique per mesh (`CONFIG_REGION_NAME_UNIQUE`). The alpha threshold is not a field: art is alpha above 8, the lattice's and `check`'s |
 | `meshes.<part>.ribs` | rig | **authored**, optional (issue #188), in the `contour` and `auto` modes: `{<chain>: {stations}, …}`, each key a chain this mesh's `segments` name. Each link of the chain gets a row of vertices across the part at its origin and at `stations` points evenly between its origin and its end (`stations`, a whole number, 0 or more, required; a chain of L links carries L × (stations + 1) ribs), each rib a row of vertices across the part, kept as a row of locked edges; the rule is "Ribs along a chain" under "A contour mesh". Absent places none and changes no byte. Refused: a lattice mesh with ribs (`CONFIG_RIBS_MODE` — its vertices are its grid's corners), a key that is not one of the mesh's chains (`CONFIG_NAME_RESOLVES`), an object naming no chain or a `stations` that is not a whole number from 0 (`CONFIG_FIELD_TYPE`); at the rig stage `CONTOUR_RIB_ART`, `CONTOUR_RIB_LINK`, `CONTOUR_RIB_CROSSING`, `CONTOUR_RIB_EDGE` (the contour refusals). The mesh's `mesh_report.json` row gains `ribs` — the declaration, the ribs placed and the vertices they hold — and its contour report (the source's, in `auto`) lists each rib's vertices |
+| `meshes.<part>.influences` | rig | **authored**, optional (issue #284), in the `grid` and `contour` modes: `{maxInfluences?, floor?}`, at least one. `maxInfluences` — the most bones that pull one vertex, a whole number 1 or more, or `null`, no cap (every bone the mesh's `segments` name; `null` is the config's spelling of a bound declared absent, as in `maxOvershoot` and `weightJump`); absent is 4. `floor` — `"cut"` (the capped shares normalised, any under 0.03 dropped, the rest normalised again; what an absent `floor` means) or `"continuous"` (0.03 subtracted from every capped share, those at or below 0 dropped, the rest normalised again, so a bone fades out of a vertex instead of leaving it in one step). Absent, the mesh is weighted at 4 and the cut and every byte is the one written before the field existed; declared, it applies under either `rule`, and is echoed as `influences` in the mesh's `mesh_report.json` row. `propose` never writes it, and `mesh-draft` carries a lattice's declaration to the contour candidate it drafts. A cap that is not a whole number 1 or more or `null` (the string `"none"` included), another `floor`, or an object naming neither is `CONFIG_FIELD_TYPE`; a vertex the declared cut leaves with no bone is `RIG_INFLUENCES_KEPT`; beside `auto` it is `CONFIG_INFLUENCES_MODE` (that mode's cap and floor are `auto.influences`). What each setting trades is "The weight cut" below |
 | `regions.<part>` | rig | **proposed**: the bone a rigid part rides. Every plan part is exactly one of a mesh or a region (`CONFIG_PART_ATTACHED`) |
 | `motion.duration` | rig; check (the loop is measured at this time) | proposed as 40 frames at 12 fps, `40/12` s, written `3.3333333333333335` (issue #252; the reference proposed 4 s, and every period it drafted is scaled with it so each track keeps its cycles per idle); a whole number of 1/12 s ticks, because `check` renders at 12 fps and compares frame 0 with the frame at this time — read within 10^-9 s (`TIME_SLACK`, issue #244), since a whole number of frames is often not exact in binary: rigc's 40th frame sits at `40 × (1/12)` = `3.333333333333333`. Half a frame off is `CHECK_LOOP_LAST_FRAME_AT_DURATION` |
 | `motion.tracks` | rig | **proposed**, then tuned. Single `{bone, prop, amp, period, phase, base?}` or chain `{chain, amps, period, phase, lag}` — one amplitude per link, link `i` at phase `phase + lag·i`. Every `period` must divide `duration` (`CONFIG_PERIOD_DIVIDES_DURATION`). A bone property is keyed by one track (`CONFIG_BONE_PROPERTY_KEYED_ONCE`): a chain keys `rotate` on every link, the blink's `eyes` group `scaley` and its `brows` group `translatey` on every member, so a single track on any of those is a second track on it — rigc would refuse it one stage later, `animation "idle" has two tracks on eye.scaley`. The proposed breath (issues #252, #270) is `chest` `translatey` travelling 2.5 % of the torso's length peak to peak — the distance from the `neck` bone to the `hip` bone as the proposal writes them, the run the chest sits half way along, whichever rule placed them — (amplitude half of it to two decimals, `base` the amplitude, so the chest rises from the setup pose and returns); the `breath:` note prints the fraction, the length, the two bones and the pixels. Until #270 it was 2.5 % of the `topwear` part's height, and a sweater to the thighs (`scarf`, 690 px) breathed 2.9 times as deep as `demo`; on neck → hip `scarf` reads 431 px (10.78 px) and `demo` 192 px (4.80 px). Neck and hip on one point: no length to scale by, so the breath keeps the reference's amplitude 1.3 (2.6 px peak to peak) and the note says so — scale it to the figure. `chest` `scalex` and the `head` and `neck` rolls are a ratio and angles and are proposed the same on every figure. A chain link is turned along its chain (the `bones` row), so a `translatex`/`translatey` key on a bone whose parent is a turned link, or a `scale`/`shear` key on a turned link, would move or stretch along the link and not along the picture's axis: the rig stage refuses it (`RIG_KEY_FRAME_UNTURNED`); `rotate` is keyed on any bone |
@@ -374,6 +375,75 @@ top edge instead would close the eye upward onto the upper lid and still move wh
 above it by (1 − squash) × its height above the pivot, so the cut, not the pivot, is what
 holds the crease.
 
+### The weight cut (`meshes.<part>.influences`, issue #284)
+
+The distance rule (and bone heat) shares a vertex among the bones its mesh's segments name,
+then cuts the list: the 4 largest kept, any share under 0.03 dropped. Both numbers are the
+reference implementation's (`[:4]` and `>= 0.03`), carried over as port constants. Neither
+is a limit of the format — spine-core reads a weighted vertex as a bone count followed by
+that many bindings, with no bound on the count — and rig-c neither refuses nor warns above
+four: its one assertion on a mesh's weights, `A20_MESH_WEIGHTS_COHERENT`, checks that they
+are coherent, not how many there are (`docs/evidence/weight-cap.md`, *Where four comes
+from*, in the repository). The cut is where a vertex changes hands in one step, and in the
+lattice and contour modes a mesh may declare it:
+
+```json
+"bottomwear": { "grid": 25, "r": 10, "segments": [["hip", [232, 425], [601, 425]], "skirt_r", "skirt_c", "skirt_l"], "influences": { "maxInfluences": 6, "floor": "continuous" } }
+```
+
+**When to reach for it:** a part that folds where two chains meet, or at the end of a curl.
+The default does not move; a fold is today found by looking at a build that passes every
+bar, and this field is what there is to turn once one is seen.
+
+**What it trades.** Every figure below is issue #284 Stage E's, verbatim from
+[`docs/evidence/weight-cap.md`](evidence/weight-cap.md), on every lattice mesh of `demo`,
+`scarf` and the trailer (`rig-c/trailer` at a99d976): the inverted triangles at the bend
+sets (±15° on every chain link; on the trailer also ± the film's own bends, after the
+slash), the largest idle displacement against today's rig in rig px (the part in the
+survey's tables), and the cost — bindings (one per bone per vertex) in the whole
+`rig.json`, `rig.json`'s length and the compiled `skeleton.json`'s, in bytes. Every
+setting passed every `check` bar on all three examples, and `rigc render`'s time did not
+separate them (the run's own spread was as large). "Cap none" is the survey's name for
+`maxInfluences: null`.
+
+| setting | inverted at the bends: demo / scarf / trailer ±15° / trailer film | idle vs today, rig px: demo / scarf / trailer | bindings: demo / scarf / trailer | `rig.json` bytes: demo / scarf / trailer | `skeleton.json` bytes: demo / scarf / trailer |
+| --- | --- | --- | --- | --- | --- |
+| cap 4, cut (today, absent) | 1 / 36 / 6 / 7 | — | 3008 / 4192 / 5014 | 471635 / 665178 / 773228 | 648296 / 886481 / 993045 |
+| cap 4, continuous | 1 / 42 / 5 / 0 | 1.252 / 0.676 / 1.471 | 3008 / 4192 / 5014 | 471627 / 665230 / 773235 | 648282 / 886533 / 993052 |
+| cap 5, cut | 1 / 35 / 5 / 1 | 1.853 / 1.291 / 1.875 | 3257 / 4546 / 5337 | 502053 / 707658 / 812385 | 670404 / 917493 / 1021528 |
+| cap 5, continuous | 1 / 46 / 3 / 0 | 1.293 / 1.139 / 1.580 | 3257 / 4546 / 5337 | 502059 / 707681 / 812407 | 670410 / 917516 / 1021550 |
+| cap 6, cut | 1 / 41 / 7 / 0 | 2.417 / 1.274 / 2.235 | 3423 / 4787 / 5562 | 522287 / 736622 / 839712 | 685243 / 938707 / 1041677 |
+| cap 6, continuous | 1 / 45 / 3 / 0 | 1.329 / 1.132 / 1.750 | 3423 / 4787 / 5561 | 522272 / 736693 / 839600 | 685228 / 938778 / 1041595 |
+| cap 8, cut | 1 / 43 / 20 / 3 | 3.350 / 1.274 / 3.106 | 3532 / 4969 / 5692 | 535476 / 758656 / 855632 | 694930 / 954712 / 1053604 |
+| cap 8, continuous | 1 / 46 / 7 / 0 | 1.365 / 1.122 / 2.248 | 3532 / 4969 / 5692 | 535455 / 758684 / 855638 | 694909 / 954740 / 1053610 |
+| cap none, cut | 1 / 43 / 22 / 3 | 3.350 / 1.291 / 3.179 | 3514 / 4987 / 5684 | 533305 / 760874 / 854648 | 693337 / 956381 / 1052864 |
+| cap none, continuous | 1 / 47 / 7 / 0 | 1.365 / 1.114 / 2.197 | 3513 / 4987 / 5684 | 533169 / 760956 / 854631 | 693238 / 956463 / 1052847 |
+| every bone, nothing dropped (the survey's reference; not a setting) | 0 / 36 / 0 / 0 | 3.350 / 1.336 / 3.286 | 5446 / 8969 / 9087 | 770980 / 1244841 / 1270495 | 866749 / 1314917 / 1358750 |
+
+In the survey's words: cap 5 adds 6.4–8.4 % bindings, cap 6 10.9–14.2 %, cap 8 13.5–18.5 %,
+no cap 13.4–19.0 %; `rig.json` grows 5.1–6.5 % at cap 5 and 10.5–14.4 % with no cap, the
+compiled `skeleton.json` 2.9–3.5 % and 6.0–7.9 %; nothing dropped at all costs 81–114 % more
+bindings. Read per part, where the folds are: on the trailer the skirt's hem corner at the
+film's bends folds 5 today and none at caps 5 and 6 with either floor, and none at any cap
+with the continuous floor; the long hair's curl tips fold 4 at ±15° today and none at caps
+5 and 6 with the continuous floor, and more, not fewer, above six with the cut (17 at cap
+8, 19 with no cap); demo's one fold, on the fringe, is there under every setting. The idle
+moves under every setting that changes a weight: that column is the price of the change
+itself, not a defect of the setting, and it is what to look at on the part before keeping
+one. The survey's own pages hold the per-part tables and the pictures.
+
+**What a declaration writes.** On `demo` and `scarf`, a config declaring each setting on
+every lattice mesh writes, at every lattice vertex, the bones and weights the survey wrote
+for that setting (measured when the field landed: 0 vertices differ in each of the twenty
+builds), so the bindings and the largest count are the table's. `rig.json`'s length matches
+the table at cap 4 and is a little shorter above it (demo at cap 5: 500517 bytes against
+the survey's 502053), because the survey bound a bone new to a vertex at an offset read off
+the rendered setup pose, and the rig stage writes that offset exactly, as it writes every
+other. Under the continuous floor a share can round to 0, so such a mesh is rounded as a
+contour region is (each share to 5 places, a 0 dropped, the remainder to the heaviest); under
+the cut it is rounded as the lattice always was. In the contour mode a region's bone counts
+toward the cap like any other (*The vertex's weights* in `src/localweights.ts`).
+
 ### A contour mesh (`meshes.<part>.contour`, issue #84)
 
 The lattice keeps every grid cell that holds an art pixel, so its boundary and its interior
@@ -1773,6 +1843,7 @@ See-through with another seed.
 | `CONFIG_BONE_UNIQUE` | a bone or chain declared twice, or `root` declared | `bones` |
 | `CONFIG_PART_ATTACHED` | a plan part or a cut's piece with neither or both of a mesh and a region; a patch with a mesh, or with no region | `meshes` / `regions` |
 | `CONFIG_RIBS_MODE` | `meshes.<part>.ribs` on a lattice (`grid`) mesh: its vertices are its grid's corners, which no row can move (issue #188) | put the part in `contour` or `auto`, or remove `ribs` |
+| `CONFIG_INFLUENCES_MODE` | `meshes.<part>.influences` on an automatic (`auto`) mesh: that mode's cap and floor are `auto.influences`, which rig-c's reduction is handed (issue #284) | declare them in `auto.influences`, or remove `influences` |
 | `CONFIG_PATCH_BOX` | an `assemble.patches` box with `x1 <= x0` or `y1 <= y0` | that patch's `box` (`x1`, `y1` are exclusive) |
 | `CONFIG_AMPS_MATCH_CHAIN` | a chain track's `amps` is not one per link | that track's `amps` |
 | `CONFIG_PERIOD_DIVIDES_DURATION` | a period that is not a whole fraction of the idle — the loop could not close | that track's `period`, or `motion.duration` |
@@ -1852,6 +1923,7 @@ See-through with another seed.
 | `RIG_PART_PRESENT`, `RIG_PART_ATTACHED` | a `meshes`/`regions` key that is not in `parts.json`, a part with neither, or a `painting:` part with a mesh | the config and the plan must name the same parts; a patch is a region |
 | `RIG_PNG_PRESENT`, `RIG_PNG_MATCHES_BOX`, `RIG_PART_HAS_ART` | a part's PNG is missing, the wrong size, or has no art pixel | re-run assemble |
 | `RIG_NAME_RESOLVES`, `RIG_SEGMENT_DEFINED`, `RIG_CHAIN_POINTS` | a segment names an undeclared bone, a bone with no `tip` and no next link, or a chain too short to make a link | that bone's `tip`, or write the segment out as `[bone, [x0,y0], [x1,y1]]` |
+| `RIG_INFLUENCES_KEPT` | a mesh's declared `influences` leaves a vertex with no bone: every capped share is under 0.03 (at or under it, for the continuous floor). The largest of k shares is at least 1/k, so this needs 34 or more kept bones; the default cap of 4 never reaches it (issue #284). The detail names the first vertex, how many more, and its largest share | declare `maxInfluences` 33 or less, or name fewer bones in `segments` |
 | `RIG_LATTICE_ONE_LOOP` | the lattice over a part does not close into one outline even after the repair passes | that mesh's `grid` |
 | `RIG_CONTROL_NAME_FREE` | a keyed, mesh-weighted bone needs `<bone>_ctl` and that name is taken | rename the declared bone |
 | `RIG_TURN_NAME_FREE` | with `turn`: a twin (`turn_<part>_<bone>`), the control `turn` or a transform constraint `turn_<part>` the turn writes is a name the rig already holds | rename the declared bone or constraint |

package/docs/STABILITY.md

@@ -124,7 +124,8 @@ part name, `[i]` an entry of a list):
 - **assemble.cuts[i].draw**, when an object — required: `before`
 - **bones[i]**, a single bone — required: `name`, `parent`, `at`; optional: `tip`
 - **bones[i]**, a chain — required: `chain`, `parent`, `points`, `tip`
-- **meshes.<part>** — exactly one of `grid`, `contour`, `auto`; required in every mode: `r`, `segments`; optional in every mode: `exponent`, `rule`; optional with `contour` or `auto`: `ribs`
+- **meshes.<part>** — exactly one of `grid`, `contour`, `auto`; required in every mode: `r`, `segments`; optional in every mode: `exponent`, `rule`; optional with `contour` or `auto`: `ribs`; optional with `grid` or `contour`: `influences` (issue #284; beside `auto` it is refused, CONFIG_INFLUENCES_MODE)
+- **meshes.<part>.influences** — optional, at least one: `maxInfluences` (a whole number, 1 or more, or null for no cap), `floor` ("cut" or "continuous")
 - **meshes.<part>.ribs.<chain>** — required: `stations`
 - **meshes.<part>.contour** — required: `tolerance`, `margin`, `spacing`; optional: `maxEdge`, `budget`, `stray`, `regions`
 - **meshes.<part>.contour.regions[i]** — required: `name`, `shape`, `bone`, `spacing`, `band`, and `cx`, `cy`, `r` for a circle or `points` for a polygon
@@ -170,7 +171,7 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 | --- | --- | --- |
 | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px`, `seam_override_px`, and `fringe_pushed_back` when not empty); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242) |
 | `rig/rig.json`, `rig/motion.json`, `rig/images/` | `rig`, `build`, `compose` | rig-c's rig spec and motion spec, `spec` `rigc-rig/1` and `rigc-motion/1`: the format is rig-c's, and this package writes only what rig-c's parser accepts |
-| `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones`, `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `mode` "contour" with `params`, `contour`, `regions` (`params.maxEdge` and `contour.outlineCut` only when the mesh declares `contour.maxEdge`); or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`); `ribs` when a contour or auto mesh declares them (after `exponent`, or after `mode`), and then `contour.ribs` (`source.contour.ribs` in the automatic mode) |
+| `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones`, `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `mode` "contour" with `params`, `contour`, `regions` (`params.maxEdge` and `contour.outlineCut` only when the mesh declares `contour.maxEdge`); or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`); `influences`, as declared, when a lattice or contour mesh declares it (after `exponent`, or where `exponent` would be); `ribs` when a contour or auto mesh declares them (after `exponent`, or after `mode`), and then `contour.ribs` (`source.contour.ribs` in the automatic mode) |
 | `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements`, and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
 | `proposal.json`, `render/landmarks*.png` | `propose` | the config's four rig sections, `turn` with `--full`/`--head`, and `notes` |
 | `basis.json` | `propose` | spec `spine-parts-basis/1` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/parts",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {

package/src/config.ts

@@ -92,6 +92,7 @@ import { type Problem, refuseIfAny } from './errors.ts';
 import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
 import { acceptedTagNames, AUTHOR_LABEL_RULE, AUTHOR_PREFIX, readLayerTag } from './tags.ts';
 import { TURN_BONE, type TurnSpec, turnNearest } from './turn.ts';
+import { FLOOR_FORMS, type FloorForm, type MeshInfluences } from './weights.ts';
 
 export type Point = [number, number];
 
@@ -275,6 +276,8 @@ export interface LatticeMeshSpec {
   exponent?: number;
   /** Absent: `"distance"`. */
   rule?: WeightRule;
+  /** The cap and the floor's form (issue #284); absent is 4 and the cut at 0.03, the rule as it always was. */
+  influences?: MeshInfluences;
 }
 
 export interface ContourMeshSpec {
@@ -285,6 +288,8 @@ export interface ContourMeshSpec {
   exponent?: number;
   /** Absent: `"distance"`. */
   rule?: WeightRule;
+  /** As the lattice's (issue #284). */
+  influences?: MeshInfluences;
   /** Rows of vertices across the part along the chains named here (issue #188); absent places none. */
   ribs?: RibsSpec;
 }
@@ -1660,7 +1665,7 @@ function checkMeshes(c: Check, v: Json, bones: Set<string>, chains: Map<string,
     const at = `config.meshes.${part}`;
     // The known keys keep their old order (grid, r, segments) with contour after them, and `r` and `segments` are
     // required in the place and words the object check uses, so a lattice mesh's refusals read as they did.
-    const m = c.object(at, spec, [], ['grid', 'r', 'segments', 'contour', 'auto', 'exponent', 'rule', 'ribs']);
+    const m = c.object(at, spec, [], ['grid', 'r', 'segments', 'contour', 'auto', 'exponent', 'rule', 'ribs', 'influences']);
     if (m === null) continue;
     for (const key of ['r', 'segments']) if (!(key in m)) c.fail('CONFIG_FIELD_PRESENT', `${at}.${key}`, 'is absent and required');
     const modes = ['grid', 'contour', 'auto'].filter((k) => k in m);
@@ -1701,6 +1706,7 @@ function checkMeshes(c: Check, v: Json, bones: Set<string>, chains: Map<string,
       });
     }
     if ('ribs' in m) checkRibs(c, `${at}.ribs`, m, chains);
+    if ('influences' in m) checkMeshInfluences(c, `${at}.influences`, m);
     if ('auto' in m && typeof m.auto === 'object' && m.auto !== null && !Array.isArray(m.auto) && 'stimulus' in m.auto) {
       checkStimulus(c, `${at}.auto.stimulus`, (m.auto as Record<string, Json>).stimulus, m, chains);
     }
@@ -1746,6 +1752,29 @@ function checkStimulus(c: Check, at: string, v: Json, m: Record<string, Json>, c
   });
 }
 
+/**
+ * `meshes.<part>.influences` (issue #284): the lattice and contour modes' cut, the author's per mesh —
+ * `maxInfluences`, a whole number 1 or more or `null` (no cap), and `floor`, `"cut"` or `"continuous"` (`FloorForm`,
+ * `src/weights.ts`). Either may be absent (4, and the cut); an object naming neither is refused, since it would
+ * declare nothing. The automatic mode states its cap and floor in `auto.influences`, which rig-c's reduction is
+ * handed, so this field beside `auto` is refused by name (`CONFIG_INFLUENCES_MODE`) rather than read by nothing.
+ */
+function checkMeshInfluences(c: Check, at: string, m: Record<string, Json>): void {
+  if ('auto' in m) {
+    c.fail('CONFIG_INFLUENCES_MODE', at, `is ${show(m.influences)} on an automatic mesh (auto); the automatic mode states its cap and floor in auto.influences (maxInfluences, minWeight), which rig-c's reduction is handed — declare them there, or remove influences`);
+    return;
+  }
+  const l = c.object(at, m.influences, [], ['maxInfluences', 'floor']);
+  if (l === null) return;
+  if (!('maxInfluences' in l) && !('floor' in l)) c.fail('CONFIG_FIELD_TYPE', at, `is ${show(m.influences)}, which names neither maxInfluences nor floor; remove influences to keep the cap of 4 and the cut at 0.03`);
+  if ('maxInfluences' in l && l.maxInfluences !== null && !(typeof l.maxInfluences === 'number' && Number.isInteger(l.maxInfluences) && l.maxInfluences >= 1)) {
+    c.fail('CONFIG_FIELD_TYPE', `${at}.maxInfluences`, `is ${show(l.maxInfluences)}; an integer at or above 1, or null (no cap: every bone the mesh's segments name), is required`);
+  }
+  if ('floor' in l && !FLOOR_FORMS.includes(l.floor as FloorForm)) {
+    c.fail('CONFIG_FIELD_TYPE', `${at}.floor`, `is ${show(l.floor)}; "cut" (shares under 0.03 dropped, what an absent floor means) or "continuous" (0.03 subtracted from every share, those at or below 0 dropped) is required`);
+  }
+}
+
 /**
  * `meshes.<part>.ribs` (issue #188): an object of chain name → `{ stations }`.
  * Each key must be a chain this mesh's `segments` name (a rib is placed along

package/src/meshdraft.ts

@@ -14,7 +14,7 @@
  * - dust left out: an extra 4-connected island of the art (alpha above `ART_ALPHA`) of at most {@link DUST_MAX_PX} px
  *   and at most {@link DUST_MAX_SHARE} of the part's art is dust, and a `stray` equal to the largest such island leaves
  *   it out. A part with any other extra island holds a real piece, and keeps its lattice ({@link dustOf});
- * - `r`, `segments`, `exponent` and `rule` as the lattice entry states them.
+ * - `r`, `segments`, `exponent`, `rule` and `influences` as the lattice entry states them.
  *
  * The constants are the ones issue #265's stages measured (Stage A passed every bar at c = 37 on three examples; T 2
  * at the trailer's 1108 px figure is Stage A2's point; the dust rule is Stage B's). They are calibrated on three
@@ -200,6 +200,7 @@ export function candidateMesh(lattice: LatticeMeshSpec, rules: Pick<FigureRules,
     segments: lattice.segments,
     ...(lattice.exponent === undefined ? {} : { exponent: lattice.exponent }),
     ...(lattice.rule === undefined ? {} : { rule: lattice.rule }),
+    ...(lattice.influences === undefined ? {} : { influences: lattice.influences }),
   };
 }
 
@@ -692,7 +693,7 @@ export function meshDraftStage(input: MeshDraftInput, rigc: RigcRunner, checkBin
     const denseMeshes = new Map<string, LatticeMeshSpec>();
     for (const part of names) {
       const l = cfg.meshes[part] as LatticeMeshSpec;
-      denseMeshes.set(part, { grid: denseGrid(artPixels(images.get(part) as Raster)), r: l.r, segments: l.segments, ...(l.exponent === undefined ? {} : { exponent: l.exponent }), ...(l.rule === undefined ? {} : { rule: l.rule }) });
+      denseMeshes.set(part, { grid: denseGrid(artPixels(images.get(part) as Raster)), r: l.r, segments: l.segments, ...(l.exponent === undefined ? {} : { exponent: l.exponent }), ...(l.rule === undefined ? {} : { rule: l.rule }), ...(l.influences === undefined ? {} : { influences: l.influences }) });
     }
     const denseRig = buildRig({ ...cfg, meshes: { ...cfg.meshes, ...Object.fromEntries(denseMeshes) } }, parts, images, undefined, input.idleKeys).rig;
     const pngs: Array<[string, Uint8Array]> = readdirSync(join(draftedRig.rigDir, 'images')).sort().map((f) => [f, new Uint8Array(readFileSync(join(draftedRig.rigDir, 'images', f)))]);

package/src/rig.ts

@@ -161,7 +161,7 @@ import { alphaAbove, crop, pad, type Raster } from './raster/index.ts';
 import { pyRound } from './round.ts';
 import { boneHeat, heatInfluences, heatRow, type HeatRow, latticeSilhouette, tracedSilhouette } from './heat.ts';
 import { TURN_BONE, type TurnSpec, turnConstraintName, turnFractions, turnTwin } from './turn.ts';
-import { DEFAULT_LIMITS, DISTANCE_EXPONENT, type Influence, influences, type Segment } from './weights.ts';
+import { DISTANCE_EXPONENT, type FloorForm, type Influence, influences, type InfluenceLimits, type MeshInfluences, meshLimits, type Segment } from './weights.ts';
 
 /** Transparent pixels added round every part image — the reference's `PAD`. */
 export const PAD = 4;
@@ -309,12 +309,47 @@ export function eyeLine(parts: PartsFile, eyeBones: ReadonlyMap<string, Point>):
 
 /**
  * The weights a contour vertex is written with: a vertex no region reaches is
- * rounded as the lattice rounds (each to 5 places, the last `1 − sum(others)`),
- * one a region reaches by {@link roundShares}.
+ * rounded as the lattice rounds ({@link latticeShares}), one a region reaches
+ * by {@link roundShares} — and so is every vertex of a mesh that declares the
+ * continuous floor (issue #284), whose shares, like a region's ramp, reach
+ * below 0.03 and may round to 0.
  */
-export function writtenShares(li: LocalInfluence): Influence[] {
-  if (li.region >= 0) return roundShares(li.influences);
-  const shares = li.influences.map(({ bone, weight }) => ({ bone, weight: pyRound(weight, 5) }));
+export function writtenShares(li: LocalInfluence, floor?: FloorForm): Influence[] {
+  if (li.region >= 0 || floor === 'continuous') return roundShares(li.influences);
+  return latticeShares(li.influences);
+}
+
+/**
+ * The refusal for a mesh some of whose vertices the cut leaves with no bone (issue #284): the first such vertex, with
+ * its capped shares before the floor, and how many more there are.
+ *
+ * When it can happen, by arithmetic: the capped shares of a vertex are normalised, so over k kept bones they sum to 1
+ * and the largest is at least 1/k. The cut keeps a share of at least 0.03 and the continuous floor one above 0.03, so a
+ * vertex keeps no bone only if 1/k ≤ 0.03, that is k ≥ 34 (1/33 = 0.0303… keeps its largest under both forms). At the
+ * default cap of 4 the largest share is at least 0.25, so a mesh that declares nothing never reaches this; only a
+ * declared cap of 34 or more, or `null`, over 34 or more bones whose shares are all at or below the floor does — and a
+ * share that is not a number (raw values summing to 0) lands here too rather than in the file. Rare, so refused by
+ * name rather than left to a crash in the rounding.
+ */
+export function nothingKeptProblem(part: string, floor: FloorForm | undefined, first: { vertex: number; at: Point; capped: readonly Influence[] }, more: number): Problem {
+  const largest = first.capped.length === 0 ? null : Math.max(...first.capped.map((e) => e.weight));
+  const form = floor === 'continuous' ? 'the continuous floor (0.03 subtracted from every share) keeps none at or below 0.03' : 'the cut drops every share below 0.03';
+  return {
+    code: 'RIG_INFLUENCES_KEPT',
+    object: `config.meshes.${part}.influences`,
+    detail: `vertex ${first.vertex} at rig (${first.at[0]}, ${first.at[1]})${more > 0 ? ` and ${more} more` : ''} keeps no bone: its ${first.capped.length} capped share(s) have the largest ${largest === null || !Number.isFinite(largest) ? String(largest) : pyRound(largest, 6)}, and ${form}; a largest share above 0.03 is required, which every vertex has when 33 or fewer bones are kept (the largest of k shares is at least 1/k) — declare maxInfluences 33 or less, or name fewer bones in segments`,
+  };
+}
+
+/**
+ * The lattice's rounding: each weight to 5 places, the last entry written as
+ * `1 − sum(others)`. Safe because under the cut every kept entry is at least
+ * `MIN_WEIGHT`, so the last cannot be taken negative; a mesh that declares the
+ * continuous floor is rounded by {@link roundShares} instead (issue #284, as
+ * Stage E wrote it: `docs/evidence/weight-cap.md`).
+ */
+export function latticeShares(list: readonly Influence[]): Influence[] {
+  const shares = list.map(({ bone, weight }) => ({ bone, weight: pyRound(weight, 5) }));
   let others = 0;
   for (let k = 0; k < shares.length - 1; k++) others += shares[k].weight;
   shares[shares.length - 1].weight = pyRound(1 - others, 5);
@@ -613,6 +648,8 @@ export interface LatticeMeshReport {
   grid: number;
   /** The distance rule's exponent the mesh declared (issue #161); absent when it declared none and ran at 2. */
   exponent?: number;
+  /** The cap and floor form the mesh declared, as declared (issue #284); absent when it declared none and ran at 4 and the cut. */
+  influences?: MeshInfluences;
   /** Only under `rule: "heat"` (issue #161): the rule and the solve it ran. Absent otherwise, so a distance mesh writes the row it always wrote. */
   heat?: HeatRow;
 }
@@ -636,6 +673,8 @@ export interface ContourMeshReport {
   mode: 'contour';
   /** The distance rule's exponent the mesh declared (issue #161); absent when it declared none and ran at 2. */
   exponent?: number;
+  /** As the lattice row's (issue #284). */
+  influences?: MeshInfluences;
   /** Only when the mesh declared ribs (issue #188): what it declared and what was placed. Absent otherwise, so a mesh without ribs writes the row it always wrote. */
   ribs?: RibsRow;
   /** `maxEdge` only when the mesh declared it (issue #265), so a mesh without it writes the row it always wrote. */
@@ -1321,8 +1360,10 @@ export function buildRig(
     segs: Segment[],
     rule: WeightRule,
     ribSpec: { segments: ReadonlyArray<string | readonly [string, Point, Point]>; ribs?: RibsSpec },
+    declared: MeshInfluences | undefined,
     out: Problem[],
   ): { attachment: MeshAttachment; report: ContourMeshReport } | null => {
+    const limits = meshLimits(declared);
     const ox = p.x - PAD;
     const oy = p.y - PAD;
     const w = img.width;
@@ -1354,10 +1395,12 @@ export function buildRig(
     let infl = 0;
     let maxInfl = 0;
     let overlapped = false;
+    let emptied: { vertex: number; at: Point; capped: Influence[] } | null = null;
+    let emptiedMore = 0;
     cm.vertices.forEach(([vx, vy], vi) => {
       const wx = vx + ox;
       const wy = vy + oy;
-      const li = localInfluences([wx, wy], segs, r, regions, DEFAULT_LIMITS, exponent ?? DISTANCE_EXPONENT, heat === null ? undefined : heatInfluences(heat, [vx, vy], DEFAULT_LIMITS));
+      const li = localInfluences([wx, wy], segs, r, regions, limits, exponent ?? DISTANCE_EXPONENT, heat === null ? undefined : heatInfluences(heat, [vx, vy], limits));
       if ('first' in li) {
         if (!overlapped) {
           out.push({
@@ -1369,11 +1412,17 @@ export function buildRig(
         overlapped = true;
         return;
       }
+      if (li.influences.length === 0) {
+        // issue #284: a declared cut that keeps no bone (nothingKeptProblem says when that can be); a region's bone would be kept.
+        if (emptied === null) emptied = { vertex: vi, at: [wx, wy], capped: heat === null ? influences([wx, wy], segs, r, { maxInfluences: limits.maxInfluences, minWeight: 0 }, exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx, vy], { maxInfluences: limits.maxInfluences, minWeight: 0 }) };
+        else emptiedMore++;
+        return;
+      }
       if (li.region >= 0) {
         reached[li.region]++;
         if (li.g >= 1) whole[li.region]++;
       }
-      const shares = writtenShares(li);
+      const shares = writtenShares(li, limits.floor);
       const ent: WeightEntry[] = shares.map(({ bone, weight }) => {
         const [x, y] = toBoneLocal(world.get(bone) as BoneTransform, spineX(wx), spineY(wy));
         return { bone, x: places(x), y: places(y), weight };
@@ -1383,6 +1432,10 @@ export function buildRig(
       maxInfl = Math.max(maxInfl, ent.length);
     });
     if (overlapped) return null;
+    if (emptied !== null) {
+      out.push(nothingKeptProblem(p.name, limits.floor, emptied, emptiedMore));
+      return null;
+    }
     const uvs: number[] = [];
     for (const [x, y] of cm.vertices) uvs.push(pyRound(x / w, 6), pyRound(y / h, 6));
     const bones = new Set(segs.map((s) => s.bone));
@@ -1401,6 +1454,7 @@ export function buildRig(
         art_coverage: pyRound(rep.coveredArtPixels / (rep.artPixels + rep.strayPixels), 5),
         mode: 'contour',
         ...(exponent === undefined ? {} : { exponent }),
+        ...(declared === undefined ? {} : { influences: declared }),
         ...(ribSpec.ribs === undefined ? {} : { ribs: ribsRow(ribSpec.ribs, cm.ribs ?? []) }),
         params: { tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, ...(spec.maxEdge === undefined ? {} : { maxEdge: spec.maxEdge }), budget: spec.budget ?? null, stray: spec.stray ?? null },
         contour: rep,
@@ -1684,7 +1738,7 @@ export function buildRig(
       continue;
     }
     if ('contour' in mesh) {
-      const row = contourAttachment(p, img, file, mesh.contour, mesh.r, mesh.exponent, segs, mesh.rule ?? 'distance', mesh, problems);
+      const row = contourAttachment(p, img, file, mesh.contour, mesh.r, mesh.exponent, segs, mesh.rule ?? 'distance', mesh, mesh.influences, problems);
       if (row === null) continue;
       skin[p.name] = { [p.name]: row.attachment };
       slots.push({ name: p.name, bone: segs[0].bone, attachment: p.name });
@@ -1711,20 +1765,32 @@ export function buildRig(
     const weights: WeightEntry[][] = [];
     let infl = 0;
     let maxInfl = 0;
-    for (const [vx0, vy0] of lm.vertices) {
+    // issue #284: the mesh's declared cap and floor form, or DEFAULT_LIMITS itself when it declares none.
+    const limits: InfluenceLimits = meshLimits(mesh.influences);
+    let emptied: { vertex: number; at: Point; capped: Influence[] } | null = null;
+    let emptiedMore = 0;
+    for (const [vi, [vx0, vy0]] of lm.vertices.entries()) {
       const wx = vx0 + ox;
       const wy = vy0 + oy;
-      const ent: WeightEntry[] = (heat === null ? influences([wx, wy], segs, mesh.r, undefined, mesh.exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx0, vy0], DEFAULT_LIMITS)).map(({ bone, weight }) => {
+      const shares = heat === null ? influences([wx, wy], segs, mesh.r, limits, mesh.exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx0, vy0], limits);
+      if (shares.length === 0) {
+        // issue #284: a declared cut that keeps no bone (nothingKeptProblem says when that can be).
+        if (emptied === null) emptied = { vertex: vi, at: [wx, wy], capped: heat === null ? influences([wx, wy], segs, mesh.r, { maxInfluences: limits.maxInfluences, minWeight: 0 }, mesh.exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx0, vy0], { maxInfluences: limits.maxInfluences, minWeight: 0 }) };
+        else emptiedMore++;
+        continue;
+      }
+      const ent: WeightEntry[] = (limits.floor === 'continuous' ? roundShares(shares) : latticeShares(shares)).map(({ bone, weight }) => {
         const [x, y] = toBoneLocal(world.get(bone) as BoneTransform, spineX(wx), spineY(wy));
-        return { bone, x: places(x), y: places(y), weight: pyRound(weight, 5) };
+        return { bone, x: places(x), y: places(y), weight };
       });
-      let others = 0;
-      for (let k = 0; k < ent.length - 1; k++) others += ent[k].weight;
-      ent[ent.length - 1].weight = pyRound(1 - others, 5);
       weights.push(ent);
       infl += ent.length;
       maxInfl = Math.max(maxInfl, ent.length);
     }
+    if (emptied !== null) {
+      problems.push(nothingKeptProblem(p.name, limits.floor, emptied, emptiedMore));
+      continue;
+    }
     const uvs: number[] = [];
     for (const [x, y] of lm.vertices) uvs.push(pyRound(x / w, 6), pyRound(y / h, 6));
     skin[p.name] = { [p.name]: { type: 'mesh', image: file, width: w, height: h, uvs, triangles: lm.triangles, hull: lm.hull, weights } };
@@ -1740,6 +1806,7 @@ export function buildRig(
       art_coverage: pyRound(artCoverage(lm, art), 5),
       grid: mesh.grid,
       ...(mesh.exponent === undefined ? {} : { exponent: mesh.exponent }),
+      ...(mesh.influences === undefined ? {} : { influences: mesh.influences }),
       ...(heat === null ? {} : { heat: heatRow(heat) }),
     });
   }

package/src/weights.ts

@@ -18,6 +18,13 @@
  * rounding. Ties in the sort keep the order the bones first appeared among the
  * segments (Python's `sorted` is stable, and so is `Array.prototype.sort`).
  *
+ * The cap and the floor's form are the author's per mesh in the lattice and
+ * contour modes (issue #284, `meshes.<part>.influences`): a declared
+ * `maxInfluences` (a whole number, or `null`: no cap) replaces the 4, and
+ * `floor: "continuous"` replaces the drop at 0.03 by the continuous floor
+ * ({@link FloorForm}). Absent, both are the constants above, and every byte is
+ * the one written before the field existed.
+ *
  * Distances are the reference's arithmetic, operation for operation — the
  * projection `t = clip(((p - a) . ab) / |ab|^2, 0, 1)` and `sqrt(dx^2 + dy^2)`,
  * not `Math.hypot`, whose last bit differs — because a weight rounded at the
@@ -31,12 +38,36 @@
  */
 import type { Point } from './config.ts';
 
-/** At most this many bones pull one vertex — Spine's usual budget and the reference's `[:4]`. */
+/**
+ * At most this many bones pull one vertex where a mesh declares no cap: the reference implementation's `[:4]`,
+ * carried over as a port constant, and nothing more. The format sets no limit — spine-core 4.3.13 reads a weighted
+ * vertex as a bone count followed by that many bindings, with no bound on the count (`SkeletonJson.js`,
+ * `SkeletonBinary.js`, and `computeWorldVertices` in `attachments/Attachment.js`) — and rig-c 2.40.0 neither refuses
+ * nor warns above four: its one assertion on a mesh's weights, `A20_MESH_WEIGHTS_COHERENT`, checks that they are
+ * coherent (every vertex bound, every weight finite and non-negative, each vertex summing to 1), not how many there
+ * are. Read and cited in `docs/evidence/weight-cap.md` (issue #284, Stage E). A mesh may declare its own cap
+ * (`meshes.<part>.influences.maxInfluences`).
+ */
 export const MAX_INFLUENCES = 4;
 
-/** A normalised weight under this is dropped before the final normalisation — the reference's `>= 0.03`. */
+/**
+ * A normalised weight under this is dropped before the final normalisation — the reference's `>= 0.03`. Under the
+ * continuous floor ({@link FloorForm}) it is subtracted from every kept share instead.
+ */
 export const MIN_WEIGHT = 0.03;
 
+/**
+ * The floor's form (issue #284): `"cut"` — the reference's, and what an absent form means: the capped shares,
+ * normalised, any under the floor dropped, the rest normalised again — or `"continuous"`: the capped shares,
+ * normalised, the floor subtracted from every one, those at or below zero dropped, the rest normalised again. Under
+ * the continuous floor a share reaches zero exactly where the cut would drop it, so a bone fades out of a vertex
+ * instead of leaving it in one step; this is Stage A's "continuous floor" (`tools/tear_survey.ts`), the form Stage E
+ * swept at every cap (`docs/evidence/weight-cap.md`).
+ */
+export type FloorForm = 'cut' | 'continuous';
+
+export const FLOOR_FORMS: readonly FloorForm[] = ['cut', 'continuous'];
+
 /**
  * The exponent of the distance rule where a mesh declares none: `1/(d + r)²`,
  * the reference's rule. At this value the weight is computed as
@@ -76,20 +107,42 @@ export interface Influence {
 
 /**
  * The cap and the floor `influences()` applies. The lattice and the contour
- * mode always run at {@link DEFAULT_LIMITS} (the reference's `[:4]` and
- * `>= 0.03`); the automatic mode (`src/automesh.ts`, issue #126) passes the
- * author's numbers instead, because rig-c's reduction is handed explicit
- * influence limits on every weighted call and the 0.03 floor is not one the
- * author wrote (P19). The arithmetic is the same either way, so with the
- * defaults every byte the two older modes write is unchanged.
+ * mode run at {@link DEFAULT_LIMITS} (the reference's `[:4]` and `>= 0.03`)
+ * unless the mesh declares `influences` (issue #284; {@link meshLimits}); the
+ * automatic mode (`src/automesh.ts`, issue #126) passes the author's numbers
+ * instead, because rig-c's reduction is handed explicit influence limits on
+ * every weighted call and the 0.03 floor is not one the author wrote (P19).
+ * The arithmetic is the same either way, so with the defaults every byte the
+ * two older modes write is unchanged.
  */
 export interface InfluenceLimits {
   maxInfluences: number;
   minWeight: number;
+  /** The floor's form; absent is `"cut"`, the arithmetic as it always was. */
+  floor?: FloorForm;
 }
 
 export const DEFAULT_LIMITS: InfluenceLimits = { maxInfluences: MAX_INFLUENCES, minWeight: MIN_WEIGHT };
 
+/** `meshes.<part>.influences` in the lattice and contour modes (issue #284): either field may be absent. */
+export interface MeshInfluences {
+  /** A whole number, 1 or more, or `null`, no cap — every bone the mesh's segments name is kept (the config's spelling of a bound declared absent, as `maxOvershoot` and `weightJump`). Absent: {@link MAX_INFLUENCES}. */
+  maxInfluences?: number | null;
+  /** Absent: `"cut"`. */
+  floor?: FloorForm;
+}
+
+/**
+ * The limits a lattice or contour mesh runs at: {@link DEFAULT_LIMITS} itself when it declares no `influences`, so
+ * nothing about such a mesh changes; otherwise its declared cap (`null` is a count no vertex reaches) and floor form,
+ * with the floor's value {@link MIN_WEIGHT} either way — the declaration chooses the form of the cut, not where it falls.
+ */
+export function meshLimits(declared: MeshInfluences | undefined): InfluenceLimits {
+  if (declared === undefined) return DEFAULT_LIMITS;
+  const cap = declared.maxInfluences;
+  return { maxInfluences: cap === undefined ? MAX_INFLUENCES : cap === null ? Number.MAX_SAFE_INTEGER : cap, minWeight: MIN_WEIGHT, floor: declared.floor ?? 'cut' };
+}
+
 /**
  * The influences on one vertex at `p` (rig pixels), before rounding, under
  * `w = 1/(d + r)^exponent`. The rig stage passes every mesh's exponent
@@ -110,14 +163,19 @@ export function influences(p: Point, segments: readonly Segment[], r: number, li
 
 /**
  * The cap and the floor, on raw per-bone values in first-appearance order: sorted (stable), the top
- * `maxInfluences` normalised, those under `minWeight` dropped, the rest normalised again. The distance rule
- * above and bone heat (`src/heat.ts`, issue #161) both end here, so the two rules share one cap and one floor.
+ * `maxInfluences` normalised, then the floor in its form ({@link FloorForm}) — under `"cut"` those under `minWeight`
+ * dropped, under `"continuous"` `minWeight` subtracted from each and those at or below zero dropped — and the rest
+ * normalised again. The distance rule above and bone heat (`src/heat.ts`, issue #161) both end here, so the two
+ * rules share one cap and one floor.
  */
 export function capAndFloor(raw: ReadonlyArray<readonly [string, number]>, limits: InfluenceLimits): Influence[] {
   const top = [...raw].sort((x, y) => y[1] - x[1]).slice(0, limits.maxInfluences);
   let s = 0;
   for (const [, v] of top) s += v;
-  const kept = top.map(([bone, v]) => ({ bone, weight: v / s })).filter((e) => e.weight >= limits.minWeight);
+  const kept =
+    limits.floor === 'continuous'
+      ? top.map(([bone, v]) => ({ bone, weight: v / s - limits.minWeight })).filter((e) => e.weight > 0)
+      : top.map(([bone, v]) => ({ bone, weight: v / s })).filter((e) => e.weight >= limits.minWeight);
   let s2 = 0;
   for (const e of kept) s2 += e.weight;
   return kept.map((e) => ({ bone: e.bone, weight: e.weight / s2 }));