Parting v1 model file and card

README.md

@@ -0,0 +1,102 @@
+---
+license: cc-by-nc-4.0
+library_name: scikit-learn
+tags:
+- vesuvius-challenge
+- herculaneum-papyri
+- x-ray-ct
+- sheet-separation
+---
+
+# Parting v1: a contact judge for touching papyrus layers
+
+## What it is
+
+Where two papyrus layers in a CT scan of a Herculaneum scroll touch, a tracer can hop from one layer to the next.
+Parting takes a point `a` on one layer, with its sheet normal, and a candidate point, and scores how likely the
+candidate is to lie on `a`'s layer; a higher score means the same layer. This file is its classifier: a soft vote
+(mean probability) of scikit-learn's `HistGradientBoostingClassifier` (600 iterations, 31 leaves) and a 64-unit MLP,
+over 669 features of the two points. The features come from the Vesuvius Challenge's base dinovol encoder
+(`scrollprize/dinovol_ps8_9.6um_101626`, `teacher_305k.pt`) at both points and along the line between them, CT
+profiles along each point's normal and along that line, and base dinovol's own token cosine.
+
+The code that makes the features, scores them and reruns the published test is `scripts/parting/` in
+[ChaseHendrick/Scrolls](https://github.com/ChaseHendrick/Scrolls) (Apache-2.0), with its page
+`docs/tools/parting.md`.
+
+Parting reads model features of the scan; it does not read ink or text. Its scores are model output, not a reading.
+
+## The file
+
+| | |
+| --- | --- |
+| File | `parting-v1.joblib` |
+| Size | 4,110,013 bytes |
+| sha256 | `f0684ab2ec5725ad9050e08bcdf73df22983960ba906d222cb9c8068a0fdc601` |
+| Format | a joblib pickle of a dict: `model` (the fitted `VotingClassifier`), `choice`, `features` (968), `columns` (a boolean mask with 669 true: the columns the model reads, in the order `scripts/parting/partmodel.py` makes them), `groups` and one more checkpoint hash. The last two record the feature layout of the run the model was fit on, which also held feature groups of another encoder; this model reads none of them |
+| Needs | scikit-learn 1.9.1 and joblib (other scikit-learn versions may refuse or change the pickle) |
+| Safety | loading a pickle runs code. Check the sha256 first; `parting.py score` refuses any other file unless given `--trust-model` |
+
+It holds no site list, site ids, coordinates or training rows: only the fitted estimators (tree splits, bin edges,
+scaler means and variances, MLP weights and their training curves).
+
+## Use it
+
+```bash
+git clone https://github.com/ChaseHendrick/Scrolls && cd Scrolls
+pip install numpy scipy scikit-learn==1.9.1 joblib torch timm einops huggingface_hub
+python3 -c "from huggingface_hub import hf_hub_download as d; print(d('SharpMeow/parting-v1', 'parting-v1.joblib'))"
+python3 scripts/parting/parting.py score --run RUN --model PATH_PRINTED_ABOVE --sites SITES.json --verdict --out READOUT.json
+```
+
+`RUN` is a feature run made by `parting.py features` on your own contact sites (`parting.py sites`); the tool page
+lists every command.
+
+## Training data
+
+Contact sites built from the published hand-traced windings of PHerc0139 and PHerc0172 (Vesuvius Challenge open
+data, CC BY-NC 4.0); touching sites only. Neither scroll is on the eligible lists of the 2027 Grand Prize or the
+First Letters prize on [scrollprize.org/prizes](https://scrollprize.org/prizes) (read 30 October 2026; Sourced fact).
+
+## Evaluation (Model output)
+
+One test, fixed before any CT value of the object was read (frozen 29 October 2026 about 20:50 UTC, read once about
+21:10 UTC), on PHercParis1Fr34 (Frag3 in the open data), a fragment of a scroll Parting never trained on, against
+base dinovol's raw token cosine on the same sites
+([record](https://github.com/ChaseHendrick/Scrolls/blob/main/docs/logs/2026-10-29-parting-fragment-contact.md)):
+
+| | Value |
+| --- | --- |
+| Parting, touching AUC (2.5 % bound) | 0.8952 (0.8452) |
+| Base dinovol token cosine, touching AUC | 0.8392 |
+| Gain (2.5 % bound) | +0.0560 (+0.0368) |
+| Touching sites, layer pairs | 150, 5 |
+| Shuffled-label control, mean of 1,000 | 0.500 |
+| Pipeline check, base dinovol on 75 apart sites | 0.944 |
+| Verdict (bar: gain at least +0.05, bound above 0) | PASS |
+
+The same file, rule and bar missed on two other fragments: PHerc1667Cr1Fr3 (Frag5), gain +0.045 (bound +0.020), and
+PHercParis2Fr143 (Frag2), gain +0.010, where base dinovol alone scored 0.965. One pass in three fragments tried.
+
+Rerun it from public data: `python3 scripts/parting/parting.py frag3 --model parting-v1.joblib --out OUT`
+(add `--device cuda` on a GPU).
+
+## Limits
+
+- Fused layers (under 3 voxels apart) are not solved: 0.633 against 0.611 for base dinovol on 38 such sites.
+- One pass in three fragments; five layer pairs is the floor the rule allows, so the bound is coarse.
+- Built for 7.5 to 10 um voxels; Frag3 was a 3.24 um scan box-averaged to 7.91 um, not a native scan.
+- Trained on two scrolls; scores on sites of PHerc0139 or PHerc0172 are not a test.
+- The gain can only show where base dinovol leaves room for it.
+
+## License
+
+CC BY-NC 4.0 for the weights, like the scan data they were trained on; the code is Apache-2.0. Base dinovol, which makes the features at run time, states no
+license on its Hugging Face page (checked 30 October 2026); it is not part of this file and is never copied, only
+downloaded from its own host by the code.
+
+## Credits
+
+Scans and layer segments: Vesuvius Challenge open data (CC BY-NC 4.0). Base dinovol: the Vesuvius Challenge. The
+dinovol backbone code: villa (MIT), in the copy vendored by jimmylomro/hercUNet (MIT). Training windings: the
+published hand-traced windings of PHerc0139 and PHerc0172.

parting-v1.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f0684ab2ec5725ad9050e08bcdf73df22983960ba906d222cb9c8068a0fdc601
+size 4110013