Metadata-Version: 2.4
Name: vesuvius-inkcheck
Version: 0.3.0
Summary: Does an ink model see KNOWN ink at this resolution? Cross-resolution validation of Herculaneum ink predictions against a published reference, with search-matched null tests.
Author: Diego Lescano
License-Expression: MIT
Project-URL: Homepage, https://github.com/dlescanogithub/vesuvius-inkcheck
Project-URL: Documentation, https://dlescanogithub.github.io/vesuvius-inkcheck/
Project-URL: Source, https://github.com/dlescanogithub/vesuvius-inkcheck
Project-URL: Issues, https://github.com/dlescanogithub/vesuvius-inkcheck/issues
Project-URL: Changelog, https://github.com/dlescanogithub/vesuvius-inkcheck/blob/main/CHANGELOG.md
Keywords: vesuvius-challenge,herculaneum,papyrus,ink-detection,validation,x-ray-ct,virtual-unwrapping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: pillow>=10
Requires-Dist: tifffile>=2023.1
Requires-Dist: imagecodecs>=2023.1
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: scikit-learn>=1.2; extra == "test"
Requires-Dist: numcodecs>=0.11; extra == "test"
Requires-Dist: jsonschema>=4.18; extra == "test"
Provides-Extra: schema
Requires-Dist: jsonschema>=4.18; extra == "schema"
Provides-Extra: zarr
Requires-Dist: numcodecs>=0.11; extra == "zarr"
Provides-Extra: notebook
Requires-Dist: nbformat>=5; extra == "notebook"
Requires-Dist: nbclient>=0.7; extra == "notebook"
Requires-Dist: ipykernel>=6; extra == "notebook"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
Dynamic: license-file

# vesuvius-inkcheck

**Does an ink-detection model see *known* ink at this resolution?** `inkcheck` compares a predicted ink map of a
Herculaneum papyrus segment against a published reference ink map of the same segment (possibly at a different voxel
size), registers them, and scores band-pass correlation, AUC and stroke recall against **search-matched shift nulls**.
It is the node-A check of the **Ink Recoverability Protocol (IRP)**, a CPU-only, pre-registered decision tree for
Vesuvius Challenge ink maps.

```bash
pip install vesuvius-inkcheck          # import name and command: inkcheck; Python >= 3.10, CPU only
inkcheck quick                         # ~2 min: public map vs traced letters -> PASS; wrong-place control -> FAIL
inkcheck PRED.tif REF.png --pred-um 9.6 --ref-um 19.2 --out out/seg   # verdict + JSON + PNG + ink card
inkcheck report --validate out/seg.card.json                          # validate against the v1 report schema
```

Every run writes an **ink card** (`PREFIX.card.json` + `PREFIX.card.md`): verdict (PASS / WEAK / FAIL, or INVALID
when a negative control passes), metrics, controls, a saturation warning and provenance (model, scan,
pre-registration hash, inkcheck version), following the versioned JSON Schema
[`inkcheck-report-v1.json`](https://github.com/dlescanogithub/vesuvius-inkcheck/blob/main/schemas/inkcheck-report-v1.json).

- `inkcheck.opendata` reads official open-data ink maps and `layers-zarr` surface volumes straight from the public bucket.
- A reusable GitHub Action runs the check on model pull requests.
- Extras: `[zarr]` compressed surface volumes, `[schema]` full JSON Schema validation, `[notebook]`, `[docs]`, `[test]`.

Documentation: https://dlescanogithub.github.io/vesuvius-inkcheck/ ·
Source, protocol, results and caveats: https://github.com/dlescanogithub/vesuvius-inkcheck ·
Changelog: https://github.com/dlescanogithub/vesuvius-inkcheck/blob/main/CHANGELOG.md

Scroll data are not shipped. Vesuvius Challenge data are CC BY-NC 4.0 (see https://scrollprize.org/data); inkcheck
fetches public inputs at run time. Code: MIT.
