P06 · Reproduce a real-image segmentation baseline
=================================================
This is the first runnable component of the perception implementation studio.
Python 3.11+; standard library only; CPU; no account, pip install or network call.
The supplied solution is practice. Independent implementation review and a
fresh-source evaluation are still pending. Running it does not award mastery.

1. TRY — unzip this package into a new directory and open a terminal there:
   python3 test-perception-baseline.py
   python3 perception-baseline.py --updates 100 --out color-100.json
   python3 perception-baseline.py --replay color-100.json --out replay.json
   Windows users can use 'py' in place of 'python3'. Outputs must use new names.
   The default data path is next to the script. --data accepts another location
   for the SAME hash-checked subset; it does not accept arbitrary datasets.

2. PREDICT — before running a comparison, write down your prediction:
   Will adding absolute position improve pet IoU on every development image?
   Could predicting background everywhere achieve respectable pixel accuracy?
   Inspect the eight PNG images and attribution before interpreting the scores.

3. EXPERIMENT — change one thing, retaining both result files:
   python3 perception-baseline.py --mode color-position --updates 100 --out position-100.json
   Compare 'images' entries for english_setter_1, samoyed_39, Egyptian_Mau_62.
   Report each image, not just a pooled pixel accuracy. An image supplies many
   correlated pixels, not thousands of independent animals. Repeated tuning on
   these three images is development. Never relabel a rerun as a new test.
   --rate is above 0 and at most 1; --updates is 1–1000; --threshold is between
   0 and 1. Higher update counts take longer. Ctrl+C stops the local process;
   no result file is written before training/evaluation finishes. An interrupted
   file write may leave a partial JSON file; choose a new name when rerunning.

4. UNDERSTAND — inspect features(), objective(), train(), score():
   Each pixel becomes RGB values in [-1,1], optionally x/y position in [-1,1],
   and a constant 1 for bias. Six stored weights multiply those six features.
   In color mode two position features and weights stay zero (four active weights).
   A sigmoid turns their sum into a probability. This is a per-pixel logistic
   classifier, not a convolutional network or a detector of whole objects.
   Features use fixed physical ranges: no development-derived normalization.

   For a pixel with probability .7 and target 1 (pet), the derivative with
   respect to its score is .7 - 1 = -.3. Multiply that by each feature, average
   over classified training pixels, then subtract rate times that gradient from
   every weight simultaneously. The constant-feature gradient updates the bias.
   Binary cross-entropy is the loss; the code evaluates it in a stable form.
   The public test checks all six gradients using small finite differences.

   Example: two true pet pixels, two true background pixels, one ignored pixel;
   predictions pet/background/pet/background/pet. Accuracy is 2/4 = 50%.
   Intersection is one correctly predicted pet; union is three pixels marked
   pet by truth or prediction. Pet IoU is 1/3. The fifth pixel is excluded from
   both metrics. An empty pet union is undefined (JSON null), not 100% correct.

5. APPLY — build evidence, then extend the implementation:
   a. Write a data card: source/license, resizing, image counts, split unit,
      excluded annotations, sampling limits and intended/unintended uses.
   b. Draw RGB/position -> weighted sum -> probability -> threshold -> mask.
   c. Compare the trained model with both always-background and always-pet.
      Select a failure image; inspect its predictedMask row by row using that
      image's width in subset.json. Describe foreground/background mistakes.
   d. Implement a spatial feature or a small convolutional segmentation model
      in a separate file. Keep original source images grouped across splits.
      Write known-value and gradient tests before comparing training curves.
      Separate supplied-code execution from code you wrote. Retain source and
      model snapshots, environment, settings, and a reproducible command.
   e. Before evaluating on NEW licensed source images, record a frozen model,
      threshold, preprocessing, metrics and acceptance criteria. Audit exact
      hashes AND visually inspect near duplicates/source relations. Keep new
      evaluation sources out of feature design and tuning. Record exposure.
      A reviewer must check this independent extension and evaluation; the
      supplied script intentionally cannot certify them from a report file.

   For a decision brief, explain whether each image's error is acceptable,
   whose data are missing, and what evidence would change your decision.
   For guided exploration, explain one changed prediction with pixel evidence.
   Neither report length nor successful supplied execution proves proficiency.

6. CONTINUE — return to the browser perception project for saved experiments,
   real-image annotations, failure galleries and three objective transfer cases:
   /learn/projects/perception/
   The localization lesson explains semantic/instance segmentation:
   /learn/locate-and-segment-objects/
   The convolution lesson and implementation prerequisites are in the catalog.
   This ZIP does not read or modify browser progress or project completion.

DATA AND EVIDENCE BOUNDARIES
Five official trainval source images train the model. Three official test
source images have already been exposed in LearnAI and are development here.
They are held out of TRAINING, but not an untouched test of selected models.
The byte hash pins the supplied asset. audit() rejects repeated source IDs or
identical source JPEG hashes. It does not identify different crops/near duplicates.
Trimap 1=pet, 2=background, 3=unclassified. Label 3 never trains or scores.
Images are at most 48 pixels on their longest side. Resizing loses details.
These eight convenience images do not support breed or deployment claims.

See ATTRIBUTION.md, subset.json, and source/README.txt for authors, original
URLs, source-image hashes, transforms, current CC-BY-SA-4.0 statement and the
retained older archive notice. Dataset adaptations retain CC-BY-SA-4.0.
Model artifacts contain weights and source hash; replay recomputes scores and
ignores imported metrics. Weights/update counts do not authenticate a training
history. All tests in this package are public development checks.


CONVOLUTIONAL COMPARISON — supplied spatial model
Run from the same extracted package:
  python3 test-perception-convolution.py
  python3 perception-convolution.py --updates 10 --out conv-10.json
  python3 perception-convolution.py --replay conv-10.json --out conv-replay.json

The 59-parameter model uses two learned 3x3 RGB filters (54 weights and two
biases), tanh, and a shared logistic head (two weights and one bias). Every pixel
receives an output. At the border, padding is zero in normalized RGB space:
mid-gray, not black. Inspect patch() to see row-major offsets and RGB ordering.
Labels marked unclassified still contribute RGB context to neighboring pixels,
but their own outputs never contribute to supervised loss or scored metrics.

Before running, predict which mistakes neighboring color might repair and which
require a larger context. Compare the same source images and baselines with the
pixel model. Inspect per-image IoU, ignored counts, masks and training losses.
Equal update counts are not equal compute: each convolution update performs
more arithmetic. Training is bounded to 100 full-batch CPU updates; start at 10.

Five public checks cover known patch geometry, all 59 finite-difference
gradients, simultaneous updates, training/development isolation, ignored-target
versus RGB-context semantics, replay and bounds. This is another supplied
implementation, not code independently written by the learner. For independent
practice, implement an extension (for example an additional channel), document
its parameter/operation counts, add an independently specified numerical case,
and explain a failure it does and does not repair. Fresh-source evaluation and
independent review are still outstanding. Reusing the public development images
cannot turn this supplied run into an untouched evaluation.


FREEZE AND TRACK LOCAL EVALUATION
P06-EVALUATION.txt explains the new perception-evaluation.py commands, batch
format, frozen per-image gate and persistent local exposure directory. Start
with the explicitly synthetic perception-evaluation-example.json to exercise
first/repeat behavior. Optional original-file replay is available through --source-manifest after
installing Pillow 12.3.0; see P06-SOURCE-PREPARATION.txt. Licensing and
independent real-image evaluation still require review. Preserve the whole ledger across candidates and retries.
