Refine Pet Animation

Refine Pet Animation

Use $imagegen for replacement visuals and the shared deterministic toolkit at ../../scripts for extraction, preview, row replacement, and validation.

Before acting, read:

• ../../references/animation-rows.md
• ../../references/codex-pet-contract.md
• ../../references/qa-rubric.md

1. Diagnose before regenerating

Inspect pet.json, the atlas, the current contact sheet or animation preview, and all available source photos.

Map the request to the smallest valid scope:

Separate timing problems from drawing problems. The Codex app owns the durations in animation-rows.md; adding more atlas cells does not raise the runtime frame rate. Improve perceived smoothness through even pose spacing, stable registration, clear anticipation and recovery, and a seamless first-to-last transition.

2. Lock approved identity

Create a compact repair brief from the current pet and photos:

• traits that must remain unchanged
• target row and exact frame count
• starting and ending pose
• action beats per frame
• stable body anchor and baseline
• specific defect being corrected
• properties from the current row that already pass

Back up spritesheet.webp and pet.json before replacement. Do not modify unrelated rows.

3. Generate one replacement row

Use $imagegen with the source photos, canonical reference, current contact sheet, and target-row guide. Request one complete coherent strip on the run's chroma background.

Require:

• exact frame count
• the same individual pet
• complete separated poses
• stable scale and baseline
• natural anatomy and weight transfer
• no crop, overlap, scenery, shadow, labels, or detached effects
• a final pose that returns naturally to the first

If the same defect occurs twice, change the pose design or motion plan instead of repeatedly rewording the same prompt.

4. Extract and preview before merging

Place the selected strip at repair/decoded/<state>.png, then run:

python3 ../../scripts/extract_strip_frames.py \
  --decoded-dir /absolute/path/to/repair/decoded \
  --output-dir /absolute/path/to/repair/frames \
  --states "<state>" \
  --method auto \
  --chroma-key "<source chroma key>"

python3 ../../scripts/inspect_frames.py \
  --frames-root /absolute/path/to/repair/frames \
  --json-out /absolute/path/to/repair/review.json \
  --states "<state>" \
  --require-components

python3 ../../scripts/render_animation_previews.py \
  --frames-root /absolute/path/to/repair/frames \
  --output-dir /absolute/path/to/repair/previews \
  --states "<state>"

Review the timing-accurate GIF before touching the installed atlas. Compare it with the original at normal pet size. Reject snapping, scale pops, baseline movement, reversed cadence, duplicated poses, unnatural limb motion, or identity drift.

5. Replace and validate

For rows 0–8, replace the whole row:

python3 ../../scripts/replace_atlas_row.py \
  --atlas /absolute/path/to/original/spritesheet.webp \
  --state "<state>" \
  --frames-dir /absolute/path/to/repair/frames/<state> \
  --output /absolute/path/to/repair/spritesheet.png \
  --webp-output /absolute/path/to/repair/spritesheet.webp

Then run:

python3 ../../scripts/despill_atlas_rows.py \
  /absolute/path/to/repair/spritesheet.png \
  --output /absolute/path/to/repair/spritesheet.png \
  --webp-output /absolute/path/to/repair/spritesheet.webp \
  --chroma-key "<source chroma key>" \
  --rows "<row number>" \
  --json-out /absolute/path/to/repair/chroma-despill.json

python3 ../../scripts/validate_atlas.py \
  /absolute/path/to/repair/spritesheet.webp \
  --json-out /absolute/path/to/repair/validation.json \
  --chroma-key "<source chroma key>" \
  --require-v2

python3 ../../scripts/make_contact_sheet.py \
  /absolute/path/to/repair/spritesheet.webp \
  --output /absolute/path/to/repair/contact-sheet.png

python3 ../../scripts/verify_atlas_row_change.py \
  --before /absolute/path/to/original/spritesheet.webp \
  --after /absolute/path/to/repair/spritesheet.webp \
  --allowed-rows "<row number>" \
  --json-out /absolute/path/to/repair/change-scope.json

Confirm the changed row passes and change-scope.json reports no changes outside the allowed row. Install both pet.json and spritesheet.webp only after validation.

Look-direction repairs

Rows 9 and 10 are coherent eight-pose families. Regenerate the complete containing row, preserve the opposite row as continuity evidence, and use the extended-atlas assembly plus direction QA tools from create-codex-pet.

Never patch one final look cell. Re-run cardinal semantics, normal-size direction review, continuity measurement, full atlas validation, and the final contact sheet.

Completion criteria

• The intended action is obvious at normal pet size.
• The motion uses the exact contract frame count and timing.
• Anatomy, markings, scale, and baseline match the approved pet.
• The loop has no visible first-to-last snap.
• Unchanged rows are preserved.
• The v2 atlas and package validate.