P06 · Check prepared pixels against original image files
========================================================
The training and unverified-evaluation commands use Python's standard library.
This optional decoding/preparation step additionally needs Pillow==12.3.0.
Use a separate virtual environment to reproduce the supplied resizing recipe:
  python3 -m venv .venv
  source .venv/bin/activate
  python -m pip install -r perception-image-requirements.txt
On Windows activate .venv\Scripts\activate instead. No network is used by the
preparation or evaluation tools once this dependency is installed.

START WITH A KNOWN SOURCE (NOT A NEW TEST)
  python test-perception-prepare.py
  python perception-prepare.py prepare --manifest perception-source-example.json --out known-prepared.json
  python perception-prepare.py verify --manifest perception-source-example.json --batch known-prepared.json --out known-replay.json

The example manifest references the bundled boxer training photograph and its
original trimap. Preparation replays that source successfully. Evaluation with
any supplied frozen protocol must reject it as known training/development data.
This distinction is deliberate: correct preparation does not mean a fresh test.

PREPARE SEPARATE, LICENSED SOURCES FOR YOUR STUDY
Copy the manifest structure and supply your own original image/trimap pairs.
Retain source/license evidence; the tool cannot certify ownership/permissions.
All paths are relative to the manifest's directory. Absolute paths, parent
traversal and symlinks escaping that directory are rejected. Input files are
read only; outputs require new filenames. Do not place unrelated private files
in a package you intend to share.

Required header fields: version p06-source-manifest-v1, attribution, license,
source, and sourceGroupingReview. Each records entry has id, sourceGroup,
image and trimap. id and sourceGroup must match: supply one full image per
source, and explain related images/derivatives in the grouping review.
Use 1–16 pairs. Duplicate source IDs or original-image byte hashes are rejected.

Images: one-frame JPEG or PNG, RGB or grayscale, at most 4 MB compressed and
four million decoded pixels each. Images with nontrivial EXIF orientation are
rejected; resolve orientation of image AND annotation together explicitly.
Trimaps: same original dimensions, PNG/JPEG decoding supported, L or P mode,
integer labels 1=pet, 2=background, 3=unclassified. Prefer lossless PNG for masks;
JPEG can corrupt label IDs and will then be rejected. All source labels are
validated before resizing so an invalid label cannot disappear by downsampling.
Alpha/palette/CMYK source images are rejected instead of silently converting
ambiguous colors. The RGB image and annotation must already correspond; same
size does not establish semantic annotation correctness.

The recipe converts to RGB, preserves aspect ratio with longest side 48 and
rounded dimensions, resizes RGB with BOX and trimap with NEAREST, and records
actual original-image and original-trimap SHA-256 hashes. No EXIF transform or
color-management correction is silently applied. Small images are enlarged by
the same fixed recipe; enlargement cannot create new information. Resizing can
remove details. Keep the originals for inspection.

  python perception-prepare.py prepare --manifest sources.json --out prepared.json
  python perception-prepare.py verify --manifest sources.json --batch prepared.json --out source-replay.json
  python perception-evaluation.py evaluate --protocol frozen.json --batch prepared.json --source-manifest sources.json --ledger evaluation-history --out evaluation.json

The last command replays preparation itself, rather than trusting a separately
supplied verification report. Original bytes, dimensions, labels, transforms,
metadata and all prepared pixels must match before exposure/scoring begins.
A changed original, changed annotation or edited prepared array fails the check.
Without --source-manifest, evaluation remains explicitly unverified at source.

A correct replay verifies a relationship between local files and prepared data.
It does NOT establish original authorship, licensing, label correctness, lack
of near duplicates, untouched evaluation, or model quality. Those require
independent source/data review. The included fixtures and known-source replay
are software checks, not new real-image evaluation or learner pilots.