# IIW character plate manifest and PNG export plan

Date: 2026-05-03

Purpose: use the clean IIW character plates as the identity layer for Wan2.2 keyframe/image training, while keeping episode masters as the motion/cinematic layer.

## Why PNG

For character plates, derived training assets should be PNG, not JPEG.

Reasons:

- line art and flat colour fills are lossless
- no block artifacts or ringing around outlines
- better preservation of hair silhouettes, facial features, suit colours, and prop edges
- avoids compounding compression artifacts on already-compressed media

Existing JPEG exports are still useful as quick references or fallbacks, but new derivatives from PSD/PSB should be PNG.

## Manifest builder

Tool:

```bash
python tools/build_iiw_character_plate_manifest.py
```

Outputs:

- `materials/training-data/iiw_character_plates_manifest.json`
- `docs/internal/iiw-character-plate-inventory.csv`

Current manifest:

- Total usable image/design files: 1,959
- Source root: `iiw-totallyspies/02_Elements/DESIGN/01_CH`
- Skips system/cache files such as `.DS_Store`, `Thumbs.db`, and Apple resource forks.

Character/entity counts:

| Character/entity | Plates |
| --- | ---: |
| Alex | 226 |
| Clover | 236 |
| Sam | 208 |
| Zerlina | 46 |
| Toby | 58 |
| Jerry | 34 |
| Mandy | 38 |
| Glitterstar | 39 |
| Cyberchac | 18 |
| WOOHP agents | 65 |
| Spies group | 17 |
| Lineup | 72 |
| Animals | 118 |
| Guests | 294 |
| Extras | 354 |
| Workers | 51 |
| Monsters | 85 |

Asset-type counts:

| Asset type | Count |
| --- | ---: |
| character_design_asset | 919 |
| outfit_sheet | 632 |
| turnaround_sheet | 266 |
| lineup_sheet | 92 |
| detail_reference | 27 |
| head_expression_sheet | 23 |

## Pilot PNG export

Tool:

```bash
python tools/export_iiw_character_plate_pngs.py \
  --characters Alex Clover Sam \
  --limit-per-character 8 \
  --force
```

Output:

- `materials/training-data/iiw-character-plates-pilot/png_2048/`
- 24 PNG derivatives
- 8 per main trio character
- max side: 2048 px
- total size: ~11 MB
- derivative manifest: `materials/training-data/iiw-character-plates-pilot/png_2048/derived_manifest.json`

The exporter now supports `auto`, `ffmpeg`, `imagemagick`, and `psd-tools` conversion modes. For PSD/PSB, `auto` tries ImageMagick first, then `psd-tools`, then `ffmpeg`. Original IIW files are untouched. The Nix helper `exportIiwCharacterPlatePngs` packages `ffmpeg`, ImageMagick, and `psd-tools` for reproducible PSD/PSB support.

## Pilot selection

The pilot intentionally focuses on identity anchors:

- heads / closeups where available
- core turnarounds
- casual outfit turnarounds
- special outfit turnarounds
- spy/old spy suit references

This is not the final training set. It is a small identity-layer sanity check before bulk conversion.

## How to use these plates in training

Use them as **identity anchors**, not as ordinary episode frames.

Recommended role:

- main-trio identity balancing
- face/hair/suit consistency
- promptable outfit variants
- evaluation references
- retrieval references during generation

Avoid over-weighting them in the main video/image dataset. Too much plate material can teach the model to output:

- turnarounds
- reference sheets
- flat presentation layouts
- white-background poses
- text/label artifacts

## Secondary PNG export

Command:

```bash
nix shell nixpkgs#imagemagick nixpkgs#python313Packages.psd-tools --command \
python tools/export_iiw_character_plate_pngs.py \
  --characters Zerlina Toby Jerry Mandy Glitterstar Cyberchac "WOOHP agents" \
  --limit-per-character 8 \
  --output-dir materials/training-data/iiw-character-plates-secondary/png_2048 \
  --force
```

Output:

- `materials/training-data/iiw-character-plates-secondary/png_2048/`
- 56 successful PNG derivatives
- derivative manifest: `materials/training-data/iiw-character-plates-secondary/png_2048/derived_manifest.json`

Successful counts:

| Character/entity | PNGs |
| --- | ---: |
| Zerlina | 8 |
| Toby | 8 |
| Jerry | 8 |
| Mandy | 8 |
| Glitterstar | 8 |
| Cyberchac | 8 |
| WOOHP agents | 8 |

PSD support findings:

- The original ffmpeg-only path failed on four multi-channel PSDs with `Decoding error: Not yet implemented in FFmpeg`.
- Nix package `imagemagick` (`magick`) successfully converted all four failed PSDs directly to 2048px PNGs.
- Nix package `python313Packages.psd-tools` (`psd-tools export`) also successfully decoded the same PSDs, and is kept as a fallback.
- The regenerated secondary manifest records the converter per derivative via `conversion_tool`.

Recovered ffmpeg-failed sources:

- `TS_700_CH_Zerlina-Turn_Colortest4.psd`
- `TS_703_CH_Jerry-outfit-Golfsuit_Color.psd`
- `TS_700_CH_Glitter-Boba-Suit-Turn_Color.psd`
- `TS_CH_MP_CYBERCHAC_TURN_Colordef2.psd`

## VLM review status

The first VLM path using redirected PNG bytes through `ollama run ... < image.png` was unreliable in this environment:

- `qwen3-vl:235b-cloud` returned intermittent cloud/server errors on contact sheets.
- `gemma4:31b-cloud` sometimes interpreted redirected PNG bytes as raw/corrupt prompt text.
- `qwen2.5vl:7b` local fallback did not complete within useful timeouts.

The successful path is the Ollama HTTP API with base64 image payloads, still using the configured Ollama vision model.

Tool:

```bash
python tools/review_iiw_character_identity_with_ollama.py
```

Outputs:

- `materials/training-data/iiw-character-identity/review/ollama_vlm_identity_plate_review.json`
- `materials/training-data/iiw-character-identity/review/ollama_vlm_identity_plate_review.csv`
- `materials/training-data/iiw-character-identity/review/train_identity_manifest.vlm_reviewed.json`
- `materials/training-data/iiw-character-identity/review/usable_identity_manifest.vlm_reviewed.json`
- `materials/training-data/iiw-character-identity/review/contact_sheets_decision/*.png`
- `materials/training-data/iiw-character-identity/review/contact_sheets_decision/decision_contact_sheet_mapping.json`

Review model requested: `qwen3-vl:235b-cloud`.

VLM review result across the 80 identity candidates:

| Decision | Count | Use |
| --- | ---: | --- |
| `TRAIN` | 22 | direct identity-anchor candidate |
| `EVAL_ONLY` | 54 | low-weight reference/eval only |
| `EXCLUDE` | 4 | removed from usable reviewed manifest |

By character/entity:

| Character/entity | TRAIN | EVAL_ONLY | EXCLUDE |
| --- | ---: | ---: | ---: |
| Alex | 2 | 6 | 0 |
| Clover | 2 | 5 | 1 |
| Sam | 2 | 5 | 1 |
| Zerlina | 1 | 7 | 0 |
| Toby | 2 | 6 | 0 |
| Jerry | 2 | 5 | 1 |
| Mandy | 3 | 4 | 1 |
| Glitterstar | 2 | 6 | 0 |
| Cyberchac | 4 | 4 | 0 |
| WOOHP agents | 2 | 6 | 0 |

Excluded by the VLM pass:

- `clover_TS_700_CH_Clover-Turn-OLD_Backpack-Open_wip_Color.png` — blank/near-blank.
- `sam_TS_705_CH_Sam-turn-casual_Color.png` — too sparse/non-informative.
- `jerry_TS_713_CH_Jerry-Camping-Outfit_Color.png` — mixed character focus.
- `mandy_TS_CH_MP_MANDY_SCHOOL_SUIT1_Color.png` — mixed character focus.

The VLM result is useful for first-pass filtering, but a human spot-check is still recommended before final training approval.

## Combined identity-anchor dataset

Tool:

```bash
python tools/build_iiw_character_identity_dataset.py
```

Outputs:

- `materials/training-data/iiw-character-identity/manifest.json`
- `materials/training-data/iiw-character-identity/identity_metadata.jsonl`
- `materials/training-data/iiw-character-identity/contact_sheets/*.png`
- `materials/training-data/iiw-character-identity/contact_sheets/contact_sheet_mapping.json`

Reviewed outputs:

- `materials/training-data/iiw-character-identity/review/train_identity_manifest.vlm_reviewed.json` — 22 TRAIN-only items.
- `materials/training-data/iiw-character-identity/review/usable_identity_manifest.vlm_reviewed.json` — 76 TRAIN + EVAL_ONLY items, with EVAL_ONLY retained at 0.25x original weight and EXCLUDE rows removed.
- `materials/training-data/iiw-character-identity/review/contact_sheets_decision/*.png` — human spot-check sheets with green/orange/red decision overlays.

Current combined identity set:

- 80 PNG identity-anchor items
- 24 main trio items
- 56 secondary/supporting items

Weights encoded in the manifest:

| Character/entity | Weight |
| --- | ---: |
| Alex | 1.00 |
| Clover | 1.00 |
| Sam | 1.00 |
| Zerlina | 0.55 |
| Toby | 0.45 |
| Jerry | 0.40 |
| Mandy | 0.40 |
| Glitterstar | 0.35 |
| Cyberchac | 0.35 |
| WOOHP agents | 0.30 |

## Recommended next steps

1. Human spot-check the four `EXCLUDE` rows and a sample of `EVAL_ONLY` rows.
2. Use `train_identity_manifest.vlm_reviewed.json` for strict identity-anchor experiments.
3. Use `usable_identity_manifest.vlm_reviewed.json` only when the training recipe supports low-weight reference/eval rows.
4. Add approved character plate captions to the Wan2.2 keyframe/image training manifest.
5. Use these plates with controlled sampling weights against episode frames.
6. Build a retrieval index so generation can pull the right clean plate for each requested character/outfit.

## Important training rule

Do not mix chibi material into the main S7 character identity set. Chibi should be a separate adapter if needed.