crackle-check / README.md
SharpMeow's picture
One page scroll bar and American English
faa2ae9 verified
|
Raw History Blame Contribute Delete
5.07 kB
---
title: Crackle Check
emoji: 🔍
colorFrom: yellow
colorTo: gray
sdk: gradio
sdk_version: 6.28.0
python_version: "3.12"
app_file: app.py
pinned: false
license: apache-2.0
suggested_hardware: zero-a10g
startup_duration_timeout: 1h
short_description: Is there crackle here? Upload a layer stack to check
tags:
- vesuvius-challenge
- herculaneum
- ink-detection
- zerogpu
---
# Crackle Check
Is there ink (crackle) in this patch of a Herculaneum scroll? Give it a small region of a segment as a **stack of
surface layers**, or press **Example**. An openly licensed ink model reads the layers in your order and again
reversed as the control, and answers **Yes**, **Maybe** or **No signal found**, with the signal shown in amber on a
before and after slider.
![PHerc0841 w00, a public example: the middle CT layer, the kept ink signal in amber, the model score in your layer order and the same with the layers reversed (the control), on one scale](https://huggingface.co/spaces/SharpMeow/crackle-check/resolve/main/assets/w00-composite.webp)
*PHerc0841 w00, public example, read by Reader V3 (the default): Yes, 18.2 times the control. Left to right: CT, kept signal, your
order, control (layers reversed). Model output, not a reading. Data: Vesuvius Challenge open data, CC BY-NC 4.0.*
After each check the page shows the answer on its scale, the overlay on a slider, both maps on one scale (amber is
above T, the level only 1 % of the control passes), and where the two orders' scores fall. The **What is crackle?**
tab shows an inked spot and plain papyrus at five depths, and a drawing of the layer stack and its control.
The w00 and ag896 examples answer from maps saved from a ZeroGPU run of the same models and crop (checked by
SHA-256), so they need no GPU quota; your own layers and From a segment always run live.
## For everyone
- **Example**: public, labeled PHerc0841 crops from the Vesuvius Challenge open data, one click, no upload.
- **Your layers**: a ZIP of layer images (`00.tif`, `01.tif`, ...) or a multi-page TIFF, 17 to 65 layers of one
region, about 320 to 1024 px across at about 9 um.
- **From a segment**: only have a screenshot of a released segment? Give the segment (`SCROLL/segments/SEGMENT`)
and the spot (x, y in one of its surface volumes' pixels), and the Space reads that region's real layers from the
open data itself. API: `/check_segment`, `/list_volumes`.
- **What is crackle?**: a short guide to segments, layers, how to make the upload and how to read the answer.
A single image or screenshot uploaded as a picture is refused with the reason: the models read 17 layers at once,
and on public labeled crops they scored at chance from one layer. Two small models trained on single layers also
failed their preregistered tests (tile AUC 0.57, and 0.48 on two unseen scrolls, against a bar of 0.80).
## For researchers
- Default model: Reader V3, the released reader with the highest mean AUC on the public PHerc0841 crops in our
preregistered ranking (0.890; Reader v2 0.862, d9v2 0.861; 21 Oct 2026, Model output; level with Reader v2 under
the ranking's paired rule, and its author benchmarked on PHerc0841).
- Models: [d9v2](https://github.com/TAUIL-Abd-Elilah/pherc0826-first-letters-search) (MIT, a fine-tune of the
Vesuvius Challenge's [`ink_9um`](https://huggingface.co/scrollprize/ink_9um)), [Reader
V3](https://huggingface.co/domenicor046/reader-v3) (MIT, Domenico Russo), or both averaged, each pinned by SHA-256.
d9v2 runs on Ink Lens's engine ([Scrolls](https://github.com/ChaseHendrick/Scrolls/tree/main/spaces/ink-lens)),
Reader V3 on the team's koine inference, reproduced patch for patch.
- The rule: T is the 99th percentile of the reversed map on papyrus; Yes when at least 3 times as many papyrus pixels
pass T in your order as the control's 1 %, Maybe from 1.5 times. Every number is in the result.
- Downloads: float maps (forward and reversed) and the kept map as `.npz`, the overlay PNG, and a four-panel PNG
(CT, overlay, your order, control).
- API and MCP: `/check`, `/check_example`, `/list_readers`; every endpoint is an MCP tool.
- VC3D: `vc3d-plugin.json` and `crackle_vc3d.py` check a region of the active segment from VC3D's Plugins menu and
show the result in its Ink Detection panel.
```python
from gradio_client import Client, handle_file
c = Client("SharpMeow/crackle-check") # add token=... for your own ZeroGPU quota
md, result, overlay, maps = c.predict(handle_file("layers.zip"), None, False, "readerv3", api_name="/check")
result["answer"] # Yes | Maybe | No signal found | Too small | Could not judge
```
## Limits
- Tested on a few public PHerc0841 crops only; other scrolls are untested.
- Many scrolls show little or no crackle, and ink can be there without it; No signal found is not proof of no ink.
- Built for scans of about 8 to 10 um per pixel (give the pixel size otherwise).
- Everything shown is model output, not a reading. The Space keeps no upload.
Code: Apache 2.0. Scan data: Vesuvius Challenge open data, CC BY-NC 4.0.