Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,188 @@
+---
+license: mit
+pipeline_tag: image-segmentation
+tags:
+  - vesuvius
+  - herculaneum
+  - fibers
+  - ink-detection
+  - computed-tomography
+  - 3d-segmentation
+  - self-distillation
+  - self-supervised
+  - volumetric-imaging
+---
+
+# PHerc. Paris 4 — 4-class fiber/ink segmentation, self-distilled (step 29000)
+
+Segments **background / vertical fiber / horizontal-angular fiber / ink** — 4
+classes, in 3D, directly in micro-CT of **PHerc. Paris 4** — trained with **no
+fixed ground truth** via self-distillation from two frozen teacher UNets. This
+is villa's [`scripts/fiber_5class`](https://github.com/ScrollPrize/villa/tree/main/scripts/fiber_5class)
+pipeline (PR [#985](https://github.com/ScrollPrize/villa/pull/985)), and this
+checkpoint is confirmed (via direct inspection of its embedded training config,
+which matches its W&B run exactly) to be the real, finished model that
+pipeline produced.
+
+**This model's own training pipeline does not use DINO at all** — it is pure
+two-teacher self-distillation (see below). DINO only appears earlier/elsewhere
+in this broader fiber-modeling effort, in a separate checkpoint that may feed
+this run's fiber teacher input — see **Related models**.
+
+![debug figure](images/p4_4class_36pykwky_debug_figure_step29899.png)
+
+*Training-time debug visualization from this run at step 29899 (image slice,
+teacher probability maps, watershed instances, student prediction). Logged to
+W&B, not an independent evaluation.*
+
+## Model details
+
+| | |
+|---|---|
+| Architecture | `vesuvius` `NetworkFromConfig` 3D UNet (`shared_encoder`/`shared_decoder`/`task_heads`) — verified directly from the checkpoint: 544 encoder tensors, 60 decoder tensors, single head |
+| Output | **4 channels**, softmax, head named `task_heads.labels` — verified shape `(4, 32, 1, 1, 1)` |
+| Classes | `0` background · `1` vertical fiber · `2` horizontal/angular fiber · `3` ink |
+| Input | 1-channel CT, 256³ patches |
+| This checkpoint | step **29000** of a 30000-step schedule · W&B run [`p4_4class_ddp8_20260526`](https://wandb.ai/vesuvius-challenge/paris4-full-features/runs/36pykwky) (`36pykwky`, project `paris4-full-features`, state **finished**) |
+| Weights | `model` (raw) and `ema` (**EMA — recommended for inference**, decay 0.9995) |
+| Optimisation | SGD + Nesterov (lr 0.005, momentum 0.99, weight_decay 3e-5), cosine LR, 2000-step warmup, bf16, CE + multiclass soft Dice (0.1 label smoothing each, Dice over foreground classes only), batch size 2 × 8 GPUs (`ddp8`) |
+| Trained on | PHerc. Paris 4, 2.4 µm scan (`s3://vesuvius-challenge-open-data/PHercParis4/volumes/20260411134726-2.400um-0.2m-78keV-masked.zarr/`) |
+
+We verified this checkpoint directly (`torch.load(..., weights_only=False)`):
+its embedded `config.wandb_run_name` is `p4_4class_ddp8_20260526`, its
+`config.out_dir` is `/ephemeral/fiber_5class_ckpts/p4_4class_ddp8_20260526` —
+both matching the W&B run's own recorded config exactly, and `step=29000`
+matches the file's provenance exactly. `save_every=1000` with
+`num_iterations=30000` means step 29000 is mathematically the **last**
+checkpoint this run could have saved (the loop exits at step 30000 before
+another save triggers) — this is the final checkpoint of a finished run, not
+an arbitrary snapshot.
+
+This run was reached after two earlier attempts under the same name failed
+(`5ga68dxv`) or crashed (`q8jmzbiv`), and after an even earlier, broader
+experiment line tagged `5class`/`fiber-ink-papyrus` (`out_channels=5`, adding a
+"papyrus" class) was simplified down to the 4-class scheme published here.
+
+## Training procedure: two-teacher self-distillation (verified against source)
+
+Read directly from `label_generator.py` (`FiveClassLabelGenerator`) and
+`train.py` in PR #985 — this is a from-source description, not an inference
+from config field names:
+
+1. `fiber_prob = sigmoid(fiber_teacher(image))`, `ink_prob = sigmoid(ink_teacher(image))` — two independent frozen teacher UNets, FG channel only.
+2. `fiber_mask = fiber_prob > fiber_thr` (0.5).
+3. GPU watershed-from-minima (`cuws`) on the distance transform of `fiber_mask` (`ws_image_mode="distance"`, `ws_h_merge=14000`) → per-instance fiber segmentation.
+4. **Per-instance PCA** on each instance's ZYX voxel coordinates: `|principal_axis · ẑ| > pca_cos_threshold` (0.819 = cos 35°) → class **1** (vertical), else class **2** (horizontal/angular). Instances below `ws_min_voxels` (400) default to class 2 rather than being dropped.
+5. **Ink overrides fiber:** `label[ink_prob > ink_thr] = 3` (`ink_thr=0.1`) — applied after the fiber/orientation assignment, so ink always wins where the ink teacher is confident.
+6. **Dark-voxel guard (final step):** `label[raw < dark_voxel_thr] = 0` (`dark_voxel_thr=90`) — forces very dark/air voxels to background regardless of any earlier assignment.
+
+Loss = cross-entropy (label smoothing 0.1) + multiclass soft Dice (smoothing
+0.1, foreground classes only). A fresh pseudo-label is generated from the two
+frozen teachers **every step** — there is no fixed/static label set at any
+point in training.
+
+The two teacher checkpoints for this run were configured as
+`/ephemeral/fiber_5class_inputs/fiber_teacher.pth` and `ink_teacher.pth` —
+generic on-disk names that don't self-identify their origin. Per the identical
+`scripts/fiber_5class/train.py` module docstring, the fiber teacher is
+documented as "ihoo3tpl ckpt", i.e. very likely
+[`scrollprize/fiber_dinoguided_2class_step010000`](https://huggingface.co/scrollprize/fiber_dinoguided_2class_step010000)
+(not proven byte-identical — it was copied/renamed on the training box). The
+ink teacher is a separate checkpoint we never had; it no longer exists on the
+original training instance and was not found anywhere else we checked, so we
+are treating it **as unrecoverable** and are not able to publish it.
+
+## Metrics
+
+Final logged values at step 29999 (run marked **finished**; checkpoint
+published here is step 29000, the last one actually saved):
+
+| metric | value |
+|---|---|
+| `loss` (ce + dice) | 1.0055 |
+| `loss_ce` | 0.4513 |
+| `loss_dice` | 0.5542 |
+| `metrics/dice_0_bg` | 0.961 |
+| `metrics/dice_1_vert_fiber` | 0.673 |
+| `metrics/dice_2_horiz_fiber` | 0.705 |
+| `metrics/dice_3_ink` | 0.791 |
+| `metrics/dice_fg_mean` | 0.723 |
+| `pseudo/frac_bg` / `frac_vert` / `frac_horiz` / `frac_ink` | 0.845 / 0.026 / 0.080 / 0.049 |
+| `pseudo/n_instances_mean` | 27.5 |
+| `pseudo/n_vert_mean` | 9 |
+
+**Important:** the per-class Dice above is **student-vs-its-own-pseudo-label
+self-consistency**, recomputed each `val_every` steps by re-forwarding the
+student on a clean (non-augmented) training crop and comparing to that crop's
+pseudo-label — confirmed directly from `train.py`'s logging code. It is **not**
+accuracy against independent, human-verified ground truth (none exists for
+this pipeline). Treat these numbers as a training-health signal, not a
+benchmark score.
+
+![debug mask](images/p4_4class_36pykwky_debug_mask_step29899.png)
+
+*Categorical mask visualization (pseudo-label vs. student prediction) from the
+same step, with the fixed class palette used throughout this pipeline.*
+
+## Relationship to other fiber-effort models — please read before conflating pipelines
+
+This is the only one of the four related repos published so far whose own
+training loop is DINO-free. The others are separate, earlier, or upstream
+components of the same broader effort:
+
+- **[`scrollprize/fiber_dinoguided_2class_step010000`](https://huggingface.co/scrollprize/fiber_dinoguided_2class_step010000)** — 2-class (background/fiber) DINO-embedding-guided self-training checkpoint, very likely (not proven byte-identical) the `fiber_teacher` input consumed by this run. Trains completely differently (Otsu + DINO-similarity dynamic pseudo-labels, no watershed, no PCA, no ink).
+- **[`scrollprize/dinovol_v2_ps8_supcon3class_step362500`](https://huggingface.co/scrollprize/dinovol_v2_ps8_supcon3class_step362500)** and **[`scrollprize/fiber_selftrain_teacher_epoch30`](https://huggingface.co/scrollprize/fiber_selftrain_teacher_epoch30)** — further upstream still (inputs to producing this run's likely fiber-teacher checkpoint, not direct inputs to this run itself).
+- **[`scrollprize/fiber_hz_vt`](https://huggingface.co/scrollprize/fiber_hz_vt)** — an independent, supervised, real-annotation-trained 2-class horizontal/vertical model (villa PR [#825](https://github.com/ScrollPrize/villa/pull/825)). Different pipeline, different training data (WebKnossos skeleton traces vs. self-distillation), not directly comparable.
+
+## Files
+
+| File | Size | Role |
+|---|---|---|
+| `p4_4class_ddp8_20260526_step029000.pth` | ~2.1 GB | `model` (raw) + `ema.model_state` (recommended for inference) + `optimizer` + embedded `config`. |
+| `images/p4_4class_36pykwky_debug_figure_step29899.png` | — | Training-time debug figure (illustrative only), from this run's W&B logs. |
+| `images/p4_4class_36pykwky_debug_mask_step29899.png` | — | Training-time categorical mask visualization (illustrative only), from this run's W&B logs. |
+
+## Usage
+
+```python
+import torch
+from huggingface_hub import hf_hub_download
+
+path = hf_hub_download(
+    "scrollprize/fiber_ink_4class_selfdistill",
+    "p4_4class_ddp8_20260526_step029000.pth",
+)
+ckpt = torch.load(path, map_location="cpu", weights_only=False)
+state = ckpt["ema"]["model_state"]   # recommended over ckpt["model"]
+# Build with vesuvius' NetworkFromConfig (target "labels", out_channels=4,
+# in_channels=1, patch_size 256^3) then load_state_dict(state).
+```
+The `vesuvius` package and the full training pipeline are in
+<https://github.com/ScrollPrize/villa> (`scripts/fiber_5class/`).
+
+## Links
+
+- **Code:** <https://github.com/ScrollPrize/villa> — PR [#985](https://github.com/ScrollPrize/villa/pull/985) (`scripts/fiber_5class`, this model's exact training code) · PR [#825](https://github.com/ScrollPrize/villa/pull/825) (related cross-frame affine infra, separate pipeline)
+- **W&B run:** <https://wandb.ai/vesuvius-challenge/paris4-full-features/runs/36pykwky>
+- **Data:** <https://scrollprize.org/data_browser>
+- **Vesuvius Challenge:** <https://scrollprize.org>
+
+## Caveats
+
+- Metrics are self-consistency (student vs. its own pseudo-label), not
+  held-out validation against independent ground truth — there is none in
+  this pipeline.
+- The ink teacher checkpoint used to train this model is not published here
+  and is believed unrecoverable (no longer present on the original training
+  instance; not found elsewhere in our search).
+- The fiber teacher checkpoint used to train this model is very likely
+  [`scrollprize/fiber_dinoguided_2class_step010000`](https://huggingface.co/scrollprize/fiber_dinoguided_2class_step010000)
+  based on matching documentation in the training source, but this was not
+  proven byte-identical (it was renamed to a generic filename on the training
+  box before this run consumed it).
+- Trained on a single scroll (PHerc. Paris 4); generalization to other scrolls
+  is untested by us.
+
+## License
+
+MIT.