# forge-realistic-animal

Standalone converter on gex44: `/opt/forge-realistic-animal/`, exposed through
`/usr/local/bin/forge-realistic-animal`. No Factory, Engine or game integration.

```sh
forge-realistic-animal \
  --in /opt/creature-lib-20261017/glb/enemy-wolf.glb \
  --animal "grey wolf" --id enemy-wolf-realistic-v3 \
  --out /opt/creature-lib-20261017/pipeline/a-new-run --seed 47232
```

Output directory must be new. Every GLB is immutable. Exit 1 is a failed stage;
exit 2 is a failed numerical check. Both retain logs and a verdict. No automatic
visual approval. This is a bounded Quaternius quadruped converter, not a universal
animal repair service.

## Source-first gates

1. Render the donor rest pose and read its six clip roles and skeleton.
2. Generate a **left-facing** reference with the tail held behind/up, separated
   from both hind legs, and all four feet staggered and apart. Maximum **three
   image requests**, with rejected pictures and measurements retained.
3. Segment the white-background silhouette at 512 px. Require four disconnected
   lower-leg regions below 74% of silhouette height, three gaps of at least
   max(3 px, 1.2% height), a distal tail region and a tail/hind-leg gap of at least
   max(5 px, 2.5% height). Reject cropped or non-white backgrounds. A supplied
   `--ref` is checked too. Failed references cannot submit a paid 3D job.
4. Generate the mesh. Remove tiny disconnected islands, small thin disconnected
   shards and enclosed duplicate shells. A head detail is retained only within
   35% height of Head and 2.5% height of the body surface. A remaining large
   detached non-head island fails. Repeat the fragment check after tail binding.
5. Fit the body direction and each connected lower-foot region independently.
   This matters because a gap-safe reference is deliberately staggered, unlike
   the donor rest pose. Do not split a paw at the world centre plane.
6. Bind the free tail to its chain. For downward rest tails, find the narrow shaft,
   transport its cross-sections onto the donor curve, bound radial outliers and
   smooth small tuft spikes. Keep UVs. **Fused-web cutting and capping are disabled.**
7. Correct existing foot contacts, preserve all clip names/durations and check the
   exported GLB in Three.js. Render rear, belly, side, clay and motion evidence.

These are conservative geometric heuristics, not semantic anatomy recognition.
A 2D gap cannot prove hidden 3D separation. Connected thin surfaces and ugly
weighting still require visual rejection. Underbody folds, feet, eyes and tail
shape are not guaranteed by a numerical pass.

## Review and release

Inspect `final-rear.png`, `final-belly.png`, `final-side.png`,
`final-bellyClay.png`, `final-rearClay.png`, `final-tail-clips.png` and
`final-tail-close.png`, plus the head and full six-clip strip. Any tail/leg sheet
is **BAD**, even if the numerical gates pass.

```sh
forge-realistic-animal --in /path/to/source.glb --animal "grey wolf" \
  --id enemy-wolf-realistic-v3 --out /path/to/run \
  --review OK --review-note "Describe the actual inspected evidence and limitations."
```

Only GOOD/OK plus every numerical check writes `<id>.glb` and
`catalog_entry.json`. Changed model or render hashes prevent release. Released
runs cannot be rechecked or overwritten. `--recheck` only re-renders unreleased
runs. The release copier can add NEW files to an existing directory:

```sh
python3 /opt/forge-realistic-animal/deliver.py --run /path/to/reviewed-run \
  --out /opt/creature-lib-20261017/pipeline/releases --label a-new-label
```

It refuses existing files and writes a separate catalog list and manifest.
The catalog uses the exact input rig's adjacent source catalog and verifies the
source GLB hash. CC0 rigs plus our mesh produce `CC0-1.0`; credit names Quaternius.
Unknown rig rights fail. Descriptions include appearance, measured size, movement,
attack and death; `good_for` contains places; `tint` is empty.

## Reuse, checks and limits

`--ref prior/reference.png --mesh prior/raw.glb` reuses paid work in a new run.
`--repair existing.glb` skips generation, but does not repair fused anatomy.
Neither mode overwrites a GLB. The run records its mode and stage tool hashes.

Checks: 6,000-20,000 triangles, <=1.5 MB, same skeleton and clip durations, height
within 5%, valid weights, zero tail/leg cross-weight, no new boundary edges,
no invalid/zero-area triangles, sampled floor crossing <=2 cm, sole error <=2.5 cm,
stance slip <=4 cm, four feet and positive measured walk/run speeds.

```sh
python3 -m unittest discover -s tools/realistic -p 'test_*.py' -v
# On gex44, using its Blender binary:
blender -b --python-exit-code 1 --python fragment_fixtures_blender.py
```

Dependencies: Blender 5.2, Python requests/numpy/Pillow, Node, Playwright,
Chromium and Three.js. Image/3D services are loopback `8093`/`8087`. Browser
previews are disposable loopback-only servers, closed in `finally` blocks.
Software WebGL is not a performance benchmark. No slope, collision, mouth-opening,
live-game or arbitrary-rig claim. Round 2 proves wolf and bull at game distance;
horse remains untested in this round. See `W-REALISTIC-ROUND2-REPORT.md`.