Skip to content
Python

docs: v4 preset, precomputed windows and the data_win224/288 corpora.

mohamdeve125a1e84277
diff --git a/CLAUDE.md b/CLAUDE.md
index 59d7dee..21e711b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -388,7 +388,9 @@ context crops (2.0x box, 448 px, `build_split.py --context`) that only
`--preset v3` can read. Each root has its own pair index. The builder refuses a
context build without `--output-dir`, and the v3 dataset refuses any root that
contains a standard split. Generation 9 is the first to train on `data_ctx`; see
-STATUS.md. When `prepost` has no free node, `datasets_pipeline/jeanzay/21_build_gpu.slurm`
+STATUS.md. A third kind, `data_win224` / `data_win288` (`build_split.py
+--windows 4`, one tile of four windows per person), is the only corpus
+`--preset v4` reads, and the image size must match the folder. When `prepost` has no free node, `datasets_pipeline/jeanzay/21_build_gpu.slurm`
builds on the 2 h GPU dev queue instead.
**You cannot reach Jean Zay.** No SSH, no Slurm. Print commands for the user and
diff --git a/CONTEXT.md b/CONTEXT.md
index e11e79e..dac2244 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -42,6 +42,13 @@ The input pipeline that samples each training crop from a context crop over a wi
A stored training crop covering twice the person's tight box at high resolution, from which the network's input window is sampled.
_Avoid_: big crop, raw crop, original (originals are the full source frames)
+**v4 preset**:
+v3's framings without v3's texture: each training crop is one of four precomputed windows, on the baseline loss weights.
+
+**Precomputed window**:
+A training crop cut from the full-resolution photo with a single resize, exactly as the runtime cuts its crop; window 0 frames the person like a perfect detector box, the others loose, off-centre or truncated.
+_Avoid_: tile (the tile is the file holding a person's four windows side by side)
+
### Evaluation
**Published protocol**:
diff --git a/instanthmr_distill_train/README.md b/instanthmr_distill_train/README.md
index 9251cf8..f9ffe17 100644
--- a/instanthmr_distill_train/README.md
+++ b/instanthmr_distill_train/README.md
@@ -647,6 +647,39 @@ exactly; reprojection chain vs labels 2e-4 px; CLIFF vs the recovered window
0.000 px; no read past an inside-photo stored edge; standard or mixed roots
refused (also through `PairIndex`).
+## `--preset v4` — v3's framings, cut like the runtime crop (added 2026-10-21)
+
+**Why.** v3 models learned the texture of their own crop pipeline: a 448 px
+context crop, then a second warp. On the same 997 3DPW-val people, g9_b4_224
+(epoch 314) scores 49.3 mm J14 PA on crops cut straight from the frame (what
+`val3dpw` and the phone do) against 43.6 mm on crops built v3's way; g8h scores
+40.0 / 39.4, i.e. it does not care. Lanczos made it worse, not better.
+
+**What.** `build_split.py --windows 4 --window-sizes 224,288 --no-hands
+--output-dir .../data_win{size}/sam3d_gt_<split>` stores, per person, one tile
+of four windows side by side (K*S x S px), each cut from the full-resolution
+photo with one `INTER_LINEAR` resize. Window 0 is the 1.2x box with the
+runtime's own floor / ceil rounding; windows 1-3 are v3 framings (side
+log-uniform in 0.6-2.0x the tight box, centre shift up to +/-15% of the side,
+black only where the window leaves the photo). Boxes are in `win_boxes` and
+are seeded by the person's name, so both sizes and every resume agree.
+
+The dataset (`crop_windows`) draws one window per sample (window 0 when not
+augmenting), uses its box as `bbox_square`, and builds CLIFF from the window
+(its centre, side / 1.2) -- what a detector box framing the person that way
+gives at runtime. Then the ordinary baseline geometry (rotation, flip, mild
+zoom / shift) and v2's occlusion and JPEG, with `cliff_follows_aug` and
+`mask_oob_2d`. **Loss weights are the baseline ones** (no v2 item 3).
+`--image-size` must equal the corpus's window size; anything else is refused.
+
+Verified by `tools/verify_windows.py` on 64 AIC people: default and `--context`
+builds byte-identical to HEAD; every window pixel-equal to
+`InstantHMR._preprocess` for the matching detector box (PNG), CLIFF equal to
+1e-7, labels 6e-5 px; JPEG q95 tiles 37.6-38.6 dB (224) / 39.1-40.2 dB (288)
+against the runtime crop, i.e. JPEG loss only; reprojection chain 1.6e-4 px;
+baseline / v2 samples bit-identical with the flag off. Storage ~83 KB (224) +
+~121 KB (288) per person, ~0.9 TB for the 4.2 M-person corpus.
+
## `--image-size` — the network input side (added 2026-09-25)
Default 224, i.e. unchanged. Must be a multiple of 32, because the decoder's