Scroll Lens 1.0.0

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE

@@ -0,0 +1,28 @@
+Scroll Lens
+Copyright 2026 Chase Hendrick and Scrolls contributors
+
+The Scroll Lens code (app.py, lens.py and the tools/ scripts) is licensed under the Apache License, Version 2.0.
+See LICENSE.
+
+Scroll Lens copies no third-party code. When it starts, it downloads the following at pinned versions and uses them
+under their own licenses, which still apply:
+
+- dinovol, https://github.com/ScrollPrize/dinovol at commit a72fda2b1e02389a8711b3dc6a26215237f35eca:
+  MIT License, Copyright (c) 2024 Vesuvius Challenge. Parts of it are derived from DINOv2 (Apache License 2.0,
+  Meta Platforms, Inc. and affiliates) and DINOv3 (DINOv3 License Agreement, Meta Platforms, Inc. and affiliates);
+  see that repository's THIRD_PARTY_NOTICES.md and LICENSES/.
+- villa's vesuvius package, https://github.com/ScrollPrize/villa at commit
+  b29f310957c7b29e7d332f9876e0e487819cfaa3: MIT License, Copyright (c) Vesuvius Challenge.
+- Model weights from the Hugging Face Hub, each MIT licensed by the Vesuvius Challenge (scrollprize):
+  scrollprize/dinovol_v2_ps8_with_paris4_352500, scrollprize/ink_3d_dino_guided (including its
+  avg_ref_embedding.npy) and scrollprize/surface_recto_3dunet. The three models are described in Angelotti et al.
+  2026, https://arxiv.org/abs/2606.29085.
+
+Scan data: Scroll Lens reads CT scans from the Vesuvius Challenge open data, licensed CC BY-NC 4.0
+(https://creativecommons.org/licenses/by-nc/4.0/). Giorgio Angelotti, Stephen Parsons, Sean Johnson, Elian Rafael
+Dal Prà, Johannes Rudolph, Paul Tafforeau, Alessandro Mirone, Paul Henderson, Hendrik Schilling, Forrest McDonald,
+David Josey, Youssef Nader, C. Seth Parker, W. Brent Seales. Vesuvius Challenge: CT Scans of Herculaneum Papyri.
+Vesuvius Challenge. https://scrollprize.org/data
+
+The gallery cubes in gallery/ are model outputs computed from that data, so they are derived data under
+CC BY-NC 4.0 as well. They hold no scan voxels: the page reads the scan again from the open-data bucket.

README.md

@@ -1,13 +1,127 @@
 ---
 title: Scroll Lens
-emoji: 🔥
-colorFrom: pink
-colorTo: indigo
+emoji: 🔎
+colorFrom: yellow
+colorTo: gray
 sdk: gradio
-sdk_version: 6.30.0
-python_version: '3.12'
+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: See scroll CT through 3D DINO, ink and surface models
+models:
+- scrollprize/dinovol_v2_ps8_with_paris4_352500
+- scrollprize/ink_3d_dino_guided
+- scrollprize/surface_recto_3dunet
+tags:
+- vesuvius-challenge
+- herculaneum
+- ct
+- 3d
+- dino
+- self-supervised
+- zerogpu
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Scroll Lens
+
+Look inside a carbonized Herculaneum scroll with the Vesuvius Challenge's newest 3D models, and click to search.
+
+Scroll Lens reads a small cube (128³ or 256³ voxels, 0.3 or 0.6 mm a side) of a public X-ray CT scan straight from the
+[Vesuvius Challenge open data](https://scrollprize.org/data) and runs three models on it, all released by the
+Vesuvius Challenge team with their PHerc. Paris 4 work ([Angelotti et al. 2026](https://arxiv.org/abs/2606.29085)):
+
+| Layer | Model | What it shows |
+| --- | --- | --- |
+| 3D DINO embeddings | [`scrollprize/dinovol_v2_ps8_with_paris4_352500`](https://huggingface.co/scrollprize/dinovol_v2_ps8_with_paris4_352500) | A self-supervised 3D ViT: 864 numbers for every 8 × 8 × 8 voxel patch. Alike patches get alike numbers. Shown as *DINO colours* (the three main directions as red, green, blue) and used by click search. |
+| 3D ink | [`scrollprize/ink_3d_dino_guided`](https://huggingface.co/scrollprize/ink_3d_dino_guided) | Ink voxels marked directly in the scan, with no flattened surface. |
+| Recto surface | [`scrollprize/surface_recto_3dunet`](https://huggingface.co/scrollprize/surface_recto_3dunet) | The written side of each papyrus sheet. |
+
+**Click to search.** Click a patch with *More like this* and every patch whose embedding is close to it lights up;
+*Not this* subtracts a patch. This is the organisers' own recipe: their ink reference (shown in amber) is the mean
+embedding of 256 expert clicks on ink. Your concept follows you to other cubes and scans, and downloads as
+`concept.npy`, so you can click ink in one scroll and look for its like in another.
+
+**Everything shown is model output, not a reading.** A cube is smaller than one letter.
+
+## Using it
+
+1. **Gallery** (no GPU): pick a ready-made cube. The page opens on the first one.
+2. **Your own point**: pick a scan, type a point (level-0 voxels, z y x) or press *Surprise me*, then *Run the
+   models*. A 256³ cube asks ZeroGPU for about half a minute. When your daily ZeroGPU time is used up, or no GPU is
+   free, the models run on the Space's CPU on the middle 128³ of the cube instead (slower, about a minute).
+3. **Look**: move the z, y and x sliders; tick the layers. White dotted lines show where the other views cut.
+4. **Search**: choose a click mode and click a view. *Top % shown* sets how many of the most similar patches light up.
+5. **3D view**: ink and surface as shells, similar patches as points, rotatable.
+6. **Save files**: the model outputs (`.npz`), a receipt (`.json`) and, after clicks, `concept.npy` and `clicks.json`.
+
+Links: `?v=PHerc0139&z=…&y=…&x=…&size=256` opens the page on a point (it runs only when you press the button);
+`?cube=ID` opens a gallery cube.
+
+## The scans
+
+Only these twelve scans, all at 2.2 to 2.4 µm, the scale the models were made for. None is on the First Letters or
+Grand Prize eligible lists. PHerc. Paris 4's title is an open prize, so Scroll Lens itself only ever picks the eight
+Paris 4 points the organisers listed for training the 3D ink model; you can type any point.
+
+| Id | Scroll | 3D DINO | 3D ink | Recto surface |
+| --- | --- | --- | --- | --- |
+| PHercParis4 | PHerc. Paris 4 | trained on this scan | made for this scroll | not trained on it |
+| PHerc0139 | PHerc. 139 | trained on this scan | its teacher was | trained on it |
+| PHerc1667 | PHerc. 1667 (Scroll 4) | **never saw it** | its teacher was | trained on it |
+| PHerc0500P2 | PHerc. 500P2 | trained on this scan | its teacher was | trained on it |
+| PHerc0343P | PHerc. 343P | trained on this scan | not trained on it | trained on it |
+| PHerc0814 | PHerc. 814 | trained on this scan | its teacher was | not trained on it |
+| PHerc0009B | PHerc. 9B | trained on this scan | its teacher was | not trained on it |
+| PHercMAN5 | PHerc. MAN 5 | trained on this scan | its teacher was | not trained on it |
+| PHerc1299 | PHerc. 1299 | trained on this scan | not trained on it | not trained on it |
+| PHerc0332 | PHerc. 332 | trained on this scan | not trained on it | not trained on it |
+| PHerc1451 | PHerc. 1451 | trained on this scan | not trained on it | not trained on it |
+| PHercMANB | PHerc. MAN B | trained on this scan | not trained on it | trained on it (MAN Bp) |
+
+"Its teacher was": the 3D ink model was distilled from a stage-1 teacher trained on that scroll's ink labels. From
+the model cards and the checkpoints' own training configs, read 16 October 2026. The page shows this per cube.
+
+## Checks
+
+- Each cube shows how well the organisers' ink reference picks out the patches the 3D ink model marks as ink (AUC),
+  beside a control that must fail: the same ink mask moved by half the cube, which should sit near 0.5. Your own
+  concept gets the same pair. This is agreement between two models, not ground truth.
+- The 3D DINO code is the organisers' own (dinovol, at a pinned commit) and reproduces their napari inspector's patch
+  embeddings to a cosine of 0.9999 on a Paris 4 cube.
+- Weights are downloaded at pinned revisions and refused unless their SHA-256 matches; the model code is downloaded
+  at pinned commits. The receipt records all of it, plus the device, timings and the cube's place in the scan.
+
+## For scripts and agents
+
+The `look` endpoint returns the same `.npz` for any listed point:
+
+```python
+from gradio_client import Client
+c = Client("SharpMeow/scroll-lens", token="hf_...")   # your token: GPU time counts against your quota
+path = c.predict("PHerc1667", 15108, 10100, 5532,     # scan, z, y, x
+                 256, "dino,ink,surface",            # cube side, models
+                 False, False, False,                # mirror averaging, compact, allow the CPU fallback
+                 api_name="/look")
+```
+
+Read it with `lens.load_npz(path)` from this Space's `lens.py`: `grid` is (Z/8, Y/8, X/8, 864) float16 unit
+embeddings (or `grid_reduced` and `grid_basis` when compact), `ink` and `surface` are (Z, Y, X) uint8 probabilities
+times 255, and `receipt` is the JSON receipt. The scan itself is not included; read it from the bucket with
+`lens.read_cube(volume, receipt["cube_origin_zyx"], receipt["cube_size"])`.
+
+`lens.py` also runs on any computer: `python3 lens.py look PHerc0139 47316 9452 12796 --size 256` (CUDA if present).
+
+## Credits and licences
+
+Code: Apache 2.0 (see `LICENSE` and `NOTICE`), by Chase Hendrick. Models and their code: MIT, by the Vesuvius
+Challenge (dinovol includes parts under the DINOv2 Apache 2.0 licence and the DINOv3 License Agreement). Scan data:
+CC BY-NC 4.0, Giorgio Angelotti, Stephen Parsons, Sean Johnson, Elian Rafael Dal Prà, Johannes Rudolph, Paul
+Tafforeau, Alessandro Mirone, Paul Henderson, Hendrik Schilling, Forrest McDonald, David Josey, Youssef Nader,
+C. Seth Parker, W. Brent Seales, *Vesuvius Challenge: CT Scans of Herculaneum Papyri*. Gallery cubes are model output
+derived from that data (CC BY-NC 4.0) and hold no scan voxels.
+
+Source and tests: [github.com/ChaseHendrick/Scrolls](https://github.com/ChaseHendrick/Scrolls), `spaces/scroll-lens/`.

app.py

@@ -0,0 +1,745 @@
+"""Scroll Lens: look inside a Herculaneum scroll scan with the Vesuvius Challenge's 3D models.
+
+The web page. Everything that is not the page (reading the scans, the models, clicks and scores) is in lens.py.
+On a ZeroGPU Space the GPU is attached only to `gpu_run`; when the visitor's GPU quota is used up, or no GPU is free,
+the same models run on the Space's CPU on a smaller cube instead. Gallery cubes need no GPU at all.
+
+  python3 app.py            serve the page (on a Space, or on any computer: it then runs on CUDA if present, else CPU)
+"""
+
+import functools
+import json
+import os
+import sys
+import tempfile
+import threading
+import time
+from pathlib import Path
+
+try:
+    import spaces  # first, before torch: on a ZeroGPU Space it attaches the GPU to spaces.GPU functions
+except ImportError:
+    spaces = None
+
+HERE = Path(__file__).resolve().parent
+if str(HERE) not in sys.path:
+    sys.path.insert(0, str(HERE))
+import lens  # noqa: E402
+from lens import LensError  # noqa: E402
+
+ON_ZERO_GPU = bool(spaces) and os.environ.get("SPACES_ZERO_GPU", "").lower() in ("1", "true")
+OUT = Path(tempfile.gettempdir()) / "scroll-lens-out"
+CPU_SIZE = 128                      # the cube side the CPU fallback runs
+STATE_TTL_S = 30 * 60               # a visitor's cube is dropped from memory after this long without use
+ENGINE = None
+ENGINE_ERROR = None
+READY = threading.Event()
+REFERENCE = None                    # the organisers' reference ink embedding, loaded before the models
+GALLERY = []
+
+OVERLAYS = ("Ink (3D ink model)", "Recto surface", "Your clicks", "Organisers' ink reference", "DINO colours")
+CLICK_MODES = ("More like this", "Not this", "Move the slices here")
+VIEW_NAMES = ("Top view (z)", "Front view (y)", "Side view (x)")
+COLOURS = {"ink": (235, 64, 52), "surface": (64, 200, 96), "clicks": (40, 220, 235), "reference": (250, 180, 30)}
+MARKS = {"pos": (255, 255, 255), "neg": (255, 70, 200)}   # crosses where you clicked: More like this, Not this
+
+
+def log(message):
+    lens.log(message)
+
+
+# ---------------------------------------------------------------- start-up
+
+def _load_engine():
+    """Load the models in the background, so the page and the gallery work while they download."""
+    global ENGINE, ENGINE_ERROR
+    try:
+        ENGINE = lens.Engine()
+        log(f"models ready in {ENGINE.startup_s} s")
+    except Exception as exc:  # noqa: BLE001  (shown to visitors who try to run a model)
+        ENGINE_ERROR = f"{type(exc).__name__}: {exc}"
+        log(f"models failed to load: {ENGINE_ERROR}")
+    finally:
+        READY.set()
+
+
+def startup():
+    global REFERENCE, GALLERY
+    import numpy as np
+    REFERENCE = lens.unit(np.load(lens.ensure_weights(names=("ink_reference",))["ink_reference"],
+                                  allow_pickle=False).astype(np.float32))
+    GALLERY = lens.gallery()
+    log(f"{len(GALLERY)} gallery cubes; ZeroGPU {'on' if ON_ZERO_GPU else 'off'}")
+    threading.Thread(target=_load_engine, name="load-models", daemon=True).start()
+
+
+def engine(wait_s=5.0):
+    if not READY.wait(wait_s):
+        raise LensError("the models are still loading (about a minute after the Space wakes up); try again shortly. "
+                        "The gallery works meanwhile.")
+    if ENGINE is None:
+        raise LensError(f"the models failed to load: {ENGINE_ERROR}")
+    return ENGINE
+
+
+# ---------------------------------------------------------------- the one GPU call
+
+def _gpu_duration(cube, layers, tta):
+    return lens.gpu_seconds(int(cube.shape[0]), layers, tta)
+
+
+def _on_gpu(fn):
+    return spaces.GPU(duration=_gpu_duration)(fn) if ON_ZERO_GPU else fn
+
+
+@_on_gpu
+def gpu_run(cube, layers, tta):
+    """The chosen models on one cube, on the GPU ZeroGPU attaches for this call."""
+    return ENGINE.run(cube, layers, device="cuda", tta=tta)
+
+
+def _is_gpu_refusal(exc):
+    text = f"{type(exc).__name__} {exc} {getattr(exc, 'title', '')}".lower()
+    return any(k in text for k in ("quota", "zerogpu", "no gpu", "gpu task aborted", "gpu is not available"))
+
+
+def run_models(cube, layers, tta, allow_cpu=True):
+    """Run on the GPU when there is one; on ZeroGPU fall back to the CPU when the GPU is refused. Returns the result
+    and a note for the visitor (empty when it ran as asked)."""
+    import torch
+    eng = engine()
+    if ON_ZERO_GPU:
+        try:
+            return gpu_run(cube, tuple(layers), bool(tta)), ""
+        except Exception as exc:  # noqa: BLE001
+            if not (allow_cpu and _is_gpu_refusal(exc)):
+                raise
+            log(f"GPU refused ({exc}); running on the CPU")
+            note = (f"Ran on the Space's CPU, because ZeroGPU said: {str(exc).strip()[:240]} "
+                    "Your GPU minutes come back each day; signing in to Hugging Face gives more.")
+            return eng.run(_centre(cube, CPU_SIZE), layers, device="cpu", tta=False), note
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    if device == "cpu" and cube.shape[0] > CPU_SIZE:
+        return (eng.run(_centre(cube, CPU_SIZE), layers, device="cpu", tta=False),
+                f"No GPU here, so the models ran on the CPU on the middle {CPU_SIZE}³ voxels.")
+    return eng.run(cube, layers, device=device, tta=tta), ""
+
+
+def _centre(cube, size):
+    if cube.shape[0] <= size:
+        return cube
+    o = (cube.shape[0] - size) // 2
+    return cube[o:o + size, o:o + size, o:o + size]
+
+
+# ---------------------------------------------------------------- one cube in memory
+
+def new_view(vid, origin, size, point, cube, result, source, note=""):
+    """Everything the page needs about the cube on screen. Arrays only; it lives in the visitor's session."""
+    import numpy as np
+    if cube.shape[0] != size:                      # the CPU fallback ran a smaller cube at the centre
+        o = (size - cube.shape[0]) // 2
+        origin = tuple(int(v + o) for v in origin)
+        size = int(cube.shape[0])
+    nz = cube[cube > 0]
+    lo, hi = (np.percentile(nz, (0.5, 99.5)) if nz.size else (0, 255))
+    view = {"volume": vid, "origin": tuple(int(v) for v in origin), "size": int(size),
+            "point": tuple(int(v) for v in point), "cube": cube, "lo": float(lo), "hi": float(max(hi, lo + 1)),
+            "source": source, "note": note, "result": result, "pca": None, "ref_sim": None,
+            "foreground": lens.foreground(cube)}
+    if "grid" in result or "grid_reduced" in result:
+        view["grid"] = lens.grid_of(result).astype(np.float16)
+        view["ref_sim"] = lens.similarity(view["grid"].astype(np.float32), REFERENCE)
+    view["slices"] = [int(min(max(p - o, 0), size - 1)) for p, o in zip(point, view["origin"])]
+    view["receipt"] = lens.receipt(vid, view["origin"], size, point, result,
+                                   ENGINE.describe() if ENGINE else None,
+                                   {"source": source, "foreground": round(view["foreground"], 4)})
+    if "ink" in result and view.get("ref_sim") is not None:
+        view["receipt"]["agreement_with_ink_model"] = lens.agreement(view["ref_sim"], result["ink"])
+    return view
+
+
+def empty_state():
+    return {"view": None, "pos": [], "neg": []}
+
+
+def click_concept(state):
+    """The visitor's concept: unit mean of the positive clicks' embeddings, and of the negative ones (or None)."""
+    import numpy as np
+    pos = [c["vec"] for c in state["pos"]]
+    neg = [c["vec"] for c in state["neg"]]
+    p = lens.unit(np.mean(pos, 0)) if pos else None
+    n = lens.unit(np.mean(neg, 0)) if neg else None
+    return p, n
+
+
+def click_sim(state):
+    view = state["view"]
+    p, n = click_concept(state)
+    if view is None or p is None or "grid" not in view:
+        return None
+    import numpy as np
+    return lens.similarity(view["grid"].astype(np.float32), p, n)
+
+
+# ---------------------------------------------------------------- drawing
+
+def _take(a, axis, i):
+    return a[i] if axis == 0 else (a[:, i] if axis == 1 else a[:, :, i])
+
+
+def _top_alpha(sim2d, sim3d, top_pct):
+    """Opacity of each pixel of a similarity slice: 0 below the cube's top `top_pct` percent, rising to 1 at its best."""
+    import numpy as np
+    thr = float(np.percentile(sim3d, 100 - top_pct))
+    best = float(sim3d.max())
+    return np.clip((sim2d - thr) / max(best - thr, 1e-6), 0, 1) * (sim2d >= thr)
+
+
+def draw_slice(state, axis, overlays, top_pct, opacity):
+    """One slice through the cube as an RGB image, scaled up so a 128 or 256 cube shows at 512 px."""
+    import numpy as np
+    view = state["view"]
+    if view is None:
+        return None
+    size, cube, idx = view["size"], view["cube"], view["slices"][axis]
+    ct = _take(cube, axis, idx).astype(np.float32)
+    g = np.clip((ct - view["lo"]) / (view["hi"] - view["lo"]), 0, 1)
+    rgb = np.repeat(g[..., None], 3, axis=2)
+    res = view["result"]
+    tok_i = idx // lens.PATCH
+
+    def up(t2):
+        return np.repeat(np.repeat(t2, lens.PATCH, 0), lens.PATCH, 1)
+
+    def blend(colour, alpha):
+        a = (np.asarray(alpha, np.float32) * opacity)[..., None]
+        rgb[:] = rgb * (1 - a) + (np.asarray(colour, np.float32) / 255.0) * a
+
+    if "DINO colours" in overlays and "grid" in view:
+        if view["pca"] is None:
+            view["pca"] = lens.pca_colours(view["grid"].astype(np.float32))
+        pc = up(_take(view["pca"], axis, tok_i)).astype(np.float32) / 255.0
+        rgb[:] = rgb * (1 - 0.6 * opacity) + pc * (0.6 * opacity)
+    if "Recto surface" in overlays and "surface" in res:
+        blend(COLOURS["surface"], _take(res["surface"], axis, idx) / 255.0)
+    if "Ink (3D ink model)" in overlays and "ink" in res:
+        blend(COLOURS["ink"], _take(res["ink"], axis, idx) / 255.0)
+    if "Organisers' ink reference" in overlays and view.get("ref_sim") is not None:
+        s3 = view["ref_sim"]
+        blend(COLOURS["reference"], up(_top_alpha(_take(s3, axis, tok_i), s3, top_pct)))
+    if "Your clicks" in overlays:
+        s3 = click_sim(state)
+        if s3 is not None:
+            blend(COLOURS["clicks"], up(_top_alpha(_take(s3, axis, tok_i), s3, top_pct)))
+    img = (np.clip(rgb, 0, 1) * 255).astype(np.uint8)
+    # where the other two slices cut this one: thin guide lines
+    others = [a for a in range(3) if a != axis]
+    r, c = view["slices"][others[0]], view["slices"][others[1]]
+    f = scale_of(size)
+    img = np.repeat(np.repeat(img, f, 0), f, 1)
+    guide = np.array([255, 255, 255], np.uint8)
+    img[r * f + f // 2, :: 3] = guide
+    img[:: 3, c * f + f // 2] = guide
+    # the clicks made in this cube that lie in this slice
+    for kind, colour in (("pos", MARKS["pos"]), ("neg", MARKS["neg"])):
+        for ck in state[kind]:
+            if ck.get("cube") != cube_key(view):
+                continue
+            v = ck["voxel"]
+            if v[axis] // lens.PATCH != tok_i:
+                continue
+            rr, cc = v[others[0]] * f, v[others[1]] * f
+            _mark(img, rr + f // 2, cc + f // 2, colour, 5 * f // 2 + 3)
+    return img
+
+
+def _mark(img, r, c, colour, half):
+    """A cross two pixels thick, drawn in place."""
+    h, w = img.shape[:2]
+    for d in range(-half, half + 1):
+        for t in (0, 1):
+            for (y, x) in ((r + d, c + t), (r + t, c + d)):
+                if 0 <= y < h and 0 <= x < w:
+                    img[y, x] = colour
+
+
+def scale_of(size):
+    return max(1, 512 // int(size))
+
+
+def cube_key(view):
+    return f"{view['volume']}:{','.join(map(str, view['origin']))}:{view['size']}"
+
+
+def numbers(state, top_pct):
+    """The text beside the images: what this cube is, what ran, and the checks."""
+    import numpy as np
+    view = state["view"]
+    if view is None:
+        return ("Pick a ready-made cube from the gallery, or a point in a scan, then press **Run the models**. "
+                "Click the images to find similar places.")
+    v = lens.volume(view["volume"])
+    r = view["receipt"]
+    um = v["voxel_um"] * view["size"]
+    lines = [f"**{v['scroll']}**, cube of {view['size']}³ voxels ({um / 1000:.2f} mm a side) at "
+             f"z {view['origin'][0]}, y {view['origin'][1]}, x {view['origin'][2]}. "
+             f"{view['foreground']:.0%} of it lies inside the scan's scroll mask."]
+    src = {"gallery": "Gallery cube: computed earlier, no GPU used now.", "gpu": "Ran now on the GPU.",
+           "cpu": "Ran now on the CPU.", "file": "Loaded from your file."}[view["source"]]
+    secs = ", ".join(f"{k} {s:.1f} s" for k, s in r.get("seconds", {}).items())
+    lines.append(f"{src} {('Times: ' + secs + '.') if secs else ''} {view['note']}".strip())
+    lines.append("**What each model saw of this scroll in training.** " + " ".join(
+        f"{lens.LAYER_TITLES[k]}: {v['role'][k]}" for k in lens.LAYERS))
+    ag = r.get("agreement_with_ink_model")
+    if ag and ag["auc"] is not None:
+        lines.append(f"**Check.** The organisers' ink reference picks out the patches the 3D ink model marks as ink "
+                     f"with AUC {ag['auc']:.2f}; the control (ink mask moved half a cube) gives "
+                     f"{ag['auc_control_shifted']:.2f} and should sit near 0.5. Ink covers "
+                     f"{ag['ink_patch_fraction']:.1%} of patches. Agreement between two models, not ground truth.")
+    if view.get("ref_sim") is not None:
+        lines.append(f"Patches at or above the organisers' threshold (cosine {lens.TAU}) to their reference: "
+                     f"{float((view['ref_sim'] >= lens.TAU).mean()):.1%}.")
+    s = click_sim(state)
+    if s is not None:
+        extra = ""
+        if "ink" in view["result"]:
+            a = lens.agreement(s, view["result"]["ink"])
+            if a["auc"] is not None:
+                extra = (f" Against the 3D ink model your concept scores AUC {a['auc']:.2f} "
+                         f"(control {a['auc_control_shifted']:.2f}).")
+        lines.append(f"**Your concept:** {len(state['pos'])} positive and {len(state['neg'])} negative clicks"
+                     f" from {len({c['cube'] for c in state['pos'] + state['neg']})} cube(s). Showing its top "
+                     f"{top_pct:g}% of patches.{extra}")
+    lines.append("_Model output, not a reading. A cube is smaller than one letter._")
+    return "\n\n".join(lines)
+
+
+def figure_3d(state, overlays, top_pct):
+    """Ink and surface as see-through shells and the similar patches as points, in a rotatable 3D plot."""
+    import numpy as np
+    import plotly.graph_objects as go
+    view = state["view"]
+    fig = go.Figure()
+    if view is None:
+        return fig
+    from skimage.measure import marching_cubes
+    res, size = view["result"], view["size"]
+    step = 2 if size <= 128 else 4
+    for key, name, colour, show in (("surface", "Recto surface", COLOURS["surface"], "Recto surface" in overlays),
+                                    ("ink", "Ink", COLOURS["ink"], "Ink (3D ink model)" in overlays)):
+        if not show or key not in res or res[key].max() < 128:
+            continue
+        verts, faces, _, _ = marching_cubes(res[key].astype(np.float32), level=127.5, step_size=step)
+        fig.add_trace(go.Mesh3d(x=verts[:, 2], y=verts[:, 1], z=verts[:, 0], i=faces[:, 0], j=faces[:, 1],
+                                k=faces[:, 2], color=f"rgb{colour}", opacity=0.35 if key == "surface" else 0.8,
+                                name=name, showlegend=True, hoverinfo="skip"))
+    for key, name, colour in (("clicks", "Your clicks", COLOURS["clicks"]),
+                              ("reference", "Organisers' ink reference", COLOURS["reference"])):
+        if (key == "clicks" and "Your clicks" not in overlays) or \
+                (key == "reference" and "Organisers' ink reference" not in overlays):
+            continue
+        s3 = click_sim(state) if key == "clicks" else view.get("ref_sim")
+        if s3 is None:
+            continue
+        thr = np.percentile(s3, 100 - top_pct)
+        pts = np.argwhere(s3 >= thr) * lens.PATCH + lens.PATCH / 2
+        fig.add_trace(go.Scatter3d(x=pts[:, 2], y=pts[:, 1], z=pts[:, 0], mode="markers", name=name,
+                                   marker=dict(size=2.5, color=f"rgb{colour}", opacity=0.7), hoverinfo="skip"))
+    ax = dict(range=[0, size], showbackground=False, gridcolor="#3a4654", zerolinecolor="#3a4654",
+              color="#c9d4de")
+    fig.update_layout(scene=dict(xaxis=dict(ax, title="x"), yaxis=dict(ax, title="y"), zaxis=dict(ax, title="z"),
+                                 aspectmode="cube", bgcolor="#11161c"),
+                      paper_bgcolor="#11161c", font=dict(color="#c9d4de"), height=460,
+                      margin=dict(l=0, r=0, t=10, b=0), legend=dict(orientation="h", y=0.02))
+    return fig
+
+
+# ---------------------------------------------------------------- loading cubes
+
+def load_point(vid, z, y, x, size, layers, tta):
+    import numpy as np
+    size = lens.check_size(size)
+    layers = lens.check_layers([{"3D DINO embeddings": "dino", "3D ink model": "ink",
+                                 "Recto surface model": "surface"}.get(k, k) for k in layers])
+    point = (int(z), int(y), int(x))
+    origin = lens.cube_origin(vid, point, size)
+    cube = lens.read_cube(vid, origin, size)
+    lens.check_cube(cube)
+    result, note = run_models(cube, layers, tta)
+    src = "gpu" if result.get("device", "").startswith("cuda") else "cpu"
+    ran = _centre(cube, ran_size(result))      # the CPU fallback runs the middle of the cube
+    return new_view(vid, origin, size, point, np.ascontiguousarray(ran), result, src, note)
+
+
+def ran_size(result):
+    """The side of the cube a result covers, from whichever layers it holds."""
+    for k in ("ink", "surface"):
+        if k in result:
+            return int(result[k].shape[0])
+    return int(lens.grid_of(result).shape[0] * lens.PATCH)
+
+
+def load_gallery(cube_id):
+    for it in GALLERY:
+        if it["id"] == cube_id:
+            meta, arrays = lens.load_npz(HERE / "gallery" / it["file"])
+            origin, size = tuple(meta["cube_origin_zyx"]), int(meta["cube_size"])
+            cube = lens.read_cube(meta["volume"], origin, size)
+            result = dict(arrays, seconds=meta.get("seconds", {}), device=meta.get("device"),
+                          device_name=meta.get("device_name"), tta=meta.get("tta", False))
+            view = new_view(meta["volume"], origin, size, tuple(meta["point_zyx"]), cube, result, "gallery",
+                            it.get("note", ""))
+            view["receipt"]["gallery_id"] = cube_id
+            return view
+    raise LensError(f"no gallery cube {cube_id!r}")
+
+
+def surprise(vid, seed=None):
+    import numpy as np
+    rng = np.random.default_rng(seed)
+    if vid == "PHercParis4":
+        return lens.PARIS4_TRAINING_POINTS[int(rng.integers(0, len(lens.PARIS4_TRAINING_POINTS)))]
+    return lens.random_point(vid, rng)
+
+
+# ---------------------------------------------------------------- files to take away
+
+def save_files(state):
+    import numpy as np
+    view = state["view"]
+    if view is None:
+        raise LensError("nothing to save yet")
+    OUT.mkdir(parents=True, exist_ok=True)
+    d = Path(tempfile.mkdtemp(dir=OUT))
+    name = f"scroll-lens-{view['volume']}-{'-'.join(map(str, view['origin']))}-{view['size']}"
+    files = [lens.save_npz(d / f"{name}.npz", view["receipt"], view["result"])]
+    rec = d / f"{name}.json"
+    rec.write_text(json.dumps(view["receipt"], indent=1) + "\n")
+    files.append(rec)
+    p, n = click_concept(state)
+    if p is not None:
+        np.save(d / "concept.npy", p.astype(np.float32))
+        files.append(d / "concept.npy")
+        clicks = {"tool": "Scroll Lens", "version": lens.VERSION, "embedding": lens.MODELS["dino"]["repo"],
+                  "positive": [{k: c[k] for k in ("volume", "cube", "voxel_zyx")} for c in state["pos"]],
+                  "negative": [{k: c[k] for k in ("volume", "cube", "voxel_zyx")} for c in state["neg"]],
+                  "note": "concept.npy is the unit-length mean of the positive clicks' 864-number dinovol embeddings"}
+        (d / "clicks.json").write_text(json.dumps(clicks, indent=1) + "\n")
+        files.append(d / "clicks.json")
+    return [str(f) for f in files]
+
+
+def api_look(vid, z, y, x, size, layers, tta, compact, allow_cpu):
+    """For scripts and agents: run the models on one cube and return its .npz (see lens.save_npz)."""
+    import numpy as np
+    size = lens.check_size(size)
+    layers = lens.check_layers([s.strip() for s in str(layers).split(",") if s.strip()])
+    point = (int(z), int(y), int(x))
+    origin = lens.cube_origin(vid, point, size)
+    cube = lens.read_cube(vid, origin, size)
+    lens.check_cube(cube)
+    result, note = run_models(cube, layers, bool(tta), allow_cpu=bool(allow_cpu))
+    n = ran_size(result)
+    if n != size:
+        origin = tuple(int(o + (size - n) // 2) for o in origin)
+    meta = lens.receipt(vid, origin, n, point, result, ENGINE.describe(), {"source": "api", "note_run": note,
+                                                                          "foreground": lens.foreground(cube)})
+    if "grid" in result and "ink" in result:
+        meta["agreement_with_ink_model"] = lens.agreement(
+            lens.similarity(np.asarray(result["grid"], np.float32), REFERENCE), result["ink"])
+    OUT.mkdir(parents=True, exist_ok=True)
+    d = Path(tempfile.mkdtemp(dir=OUT))
+    return str(lens.save_npz(d / f"{vid}-{'-'.join(map(str, origin))}-{n}.npz", meta, result, compact=bool(compact)))
+
+
+# ---------------------------------------------------------------- the page
+
+INTRO = """\
+**Scroll Lens** shows what three of the Vesuvius Challenge's newest 3D models see inside a carbonized Herculaneum scroll.
+It reads a small cube of a public X-ray CT scan straight from the open-data bucket and runs, on that cube:
+
+- **3D DINO embeddings** ([dinovol](https://huggingface.co/scrollprize/dinovol_v2_ps8_with_paris4_352500)): a
+  self-supervised model that turns every 8 × 8 × 8 voxel patch into 864 numbers. Patches the model finds alike get
+  alike numbers. *DINO colours* paints the three main directions as red, green and blue.
+- **3D ink model** ([ink_3d_dino_guided](https://huggingface.co/scrollprize/ink_3d_dino_guided)): marks ink voxels
+  directly in the scan, with no flattened surface.
+- **Recto surface model** ([surface_recto_3dunet](https://huggingface.co/scrollprize/surface_recto_3dunet)): marks
+  the written side of each papyrus sheet.
+
+**Click to search.** With *More like this*, a click takes the embedding of the patch you clicked; every patch with a
+similar embedding lights up in cyan. *Not this* subtracts a patch you do not want. This is how the organisers built
+their ink reference (*Organisers' ink reference*, in amber): experts clicked ink 256 times and averaged the
+embeddings. Your concept follows you to other cubes and scans, so you can click ink in one scroll and look for its
+like in another, and you can download it as `concept.npy`.
+
+All three models come from the PHerc. Paris 4 work of the Vesuvius Challenge team
+([Angelotti et al. 2026](https://arxiv.org/abs/2606.29085)). Scroll Lens reads only the twelve 2.2 to 2.4 µm scans
+those models were made for, none of them eligible for the First Letters or Grand Prize. **Everything shown is model
+output, not a reading:** a cube is at most 0.6 mm across, smaller than one letter.
+"""
+
+HOW_TO = """\
+1. **Gallery** (no GPU needed): pick a ready-made cube and it loads at once.
+2. **Your own point**: pick a scan, type a point in voxels (z, y, x) or press **Surprise me**, then **Run the models**.
+   A 256³ cube is the models' own working size and uses about half a minute of GPU time; 128³ about a quarter.
+   When your daily ZeroGPU time runs out, Scroll Lens runs a 128³ cube on the CPU instead (slower, about a minute).
+3. **Look**: drag the three sliders to move through the cube; tick the layers to show. The white dotted lines are
+   where the other two views cut this one.
+4. **Search**: choose a click mode, then click a view. Raise or lower *Top % shown* to see more or fewer matches.
+5. **Take it away**: **Save files** gives the model outputs (.npz), the receipt (.json) and, after clicks, your
+   `concept.npy`. A link with `?v=SCAN&z=…&y=…&x=…` opens the page on a point; `?cube=ID` on a gallery cube.
+
+Scripts can call the `look` endpoint (`gradio_client`, see the README) to get the same .npz for any listed point.
+"""
+
+CSS = """
+#sl-views img { image-rendering: pixelated; cursor: crosshair; }
+.sl-head { display:flex; gap:14px; align-items:baseline; flex-wrap:wrap; margin: 4px 0 2px; }
+.sl-head h1 { margin:0; font-size: 1.6rem; letter-spacing: .01em; }
+.sl-head span { color: var(--body-text-color-subdued); }
+.sl-legend { display:flex; flex-wrap:wrap; gap:10px 16px; font-size:.86rem; margin: 2px 0 4px; }
+.sl-legend i { display:inline-block; width:11px; height:11px; border-radius:2px; margin-right:5px; vertical-align:-1px; }
+@media (max-width: 720px) { #sl-viewer { order: -1; } }   /* phones: the images first, the controls below */
+footer.sl-credit { text-align:center; color: var(--body-text-color-subdued); font-size:.85rem; margin-top: 8px; }
+"""
+
+LEGEND = ('<div class="sl-legend">' + "".join(
+    f'<span><i style="background:rgb{c}"></i>{t}</span>' for t, c in (
+        ("Ink, 3D ink model", COLOURS["ink"]), ("Recto surface", COLOURS["surface"]),
+        ("Like your clicks", COLOURS["clicks"]), ("Like the organisers' ink reference", COLOURS["reference"]),
+        ("Your clicks: white +, Not this: magenta +", MARKS["neg"]))) + "</div>")
+
+
+def theme():
+    import gradio as gr
+    return gr.themes.Base(primary_hue="amber", neutral_hue="slate", radius_size="sm",
+                          font=("system-ui", "sans-serif"), font_mono=("ui-monospace", "monospace"))
+
+
+def build_demo():
+    import gradio as gr
+
+    vol_choices = [(f"{v['scroll']} ({vid})", vid) for vid, v in lens.VOLUMES.items()]
+    gal_choices = [(it["title"], it["id"]) for it in GALLERY]
+    layer_names = [lens.LAYER_TITLES[k] for k in lens.LAYERS]
+
+    def volume_text(vid):
+        v = lens.volume(vid)
+        z, y, x = v["shape"]
+        return (f"{v['note']} Scan: {v['voxel_um']} µm voxels, {z:,} × {y:,} × {x:,} (z, y, x). "
+                f"[Open data]({lens.BUCKET}/{vid}/volumes/{v['scan']}/)").strip()
+
+    def show(state, overlays, top_pct, opacity):
+        return ([draw_slice(state, a, overlays, top_pct, opacity) for a in range(3)]
+                + [numbers(state, top_pct)])
+
+    def slider_updates(state):
+        view = state["view"]
+        if view is None:
+            return [gr.update()] * 3
+        return [gr.update(maximum=view["size"] - 1, value=view["slices"][a]) for a in range(3)]
+
+    def guard(fn):
+        @functools.wraps(fn)          # keeps fn's signature, so gradio still passes SelectData and Request
+        def wrapped(*args, **kwargs):
+            try:
+                return fn(*args, **kwargs)
+            except LensError as exc:
+                raise gr.Error(str(exc)) from None
+        return wrapped
+
+    @guard
+    def on_run(vid, z, y, x, size, layers, tta, state, overlays, top_pct, opacity):
+        state = dict(state)
+        state["view"] = load_point(vid, z, y, x, size, layers, tta)
+        return [state] + slider_updates(state) + show(state, overlays, top_pct, opacity)
+
+    @guard
+    def on_gallery(cube_id, state, overlays, top_pct, opacity):
+        if not cube_id:
+            raise LensError("pick a gallery cube")
+        state = dict(state)
+        state["view"] = load_gallery(cube_id)
+        p = state["view"]["point"]
+        return ([state] + slider_updates(state) + show(state, overlays, top_pct, opacity)
+                + [state["view"]["volume"], p[0], p[1], p[2]])
+
+    @guard
+    def on_surprise(vid):
+        z, y, x = surprise(vid)
+        return z, y, x
+
+    @guard
+    def on_slices(sz, sy, sx, state, overlays, top_pct, opacity):
+        if state["view"] is not None:
+            state["view"]["slices"] = [int(sz), int(sy), int(sx)]
+        return show(state, overlays, top_pct, opacity)
+
+    def on_select(axis):
+        @guard
+        def handler(mode, state, overlays, top_pct, opacity, evt: gr.SelectData):
+            view = state["view"]
+            if view is None or evt.index is None:
+                return [state] + slider_updates(state) + show(state, overlays, top_pct, opacity) + [overlays]
+            f = scale_of(view["size"])
+            col, row = int(evt.index[0]) // f, int(evt.index[1]) // f
+            others = [a for a in range(3) if a != axis]
+            vox = [0, 0, 0]
+            vox[axis] = view["slices"][axis]
+            vox[others[0]], vox[others[1]] = row, col
+            vox = [int(min(max(v, 0), view["size"] - 1)) for v in vox]
+            if mode == CLICK_MODES[2]:
+                view["slices"] = vox
+                return [state] + slider_updates(state) + show(state, overlays, top_pct, opacity) + [overlays]
+            if "grid" not in view:
+                raise LensError("this cube has no DINO embeddings; run it with the 3D DINO model to search by "
+                                "clicking")
+            tok = lens.token_of(vox, view["size"])
+            vec = view["grid"][tok].astype("float32")
+            kind = "pos" if mode == CLICK_MODES[0] else "neg"
+            state[kind] = state[kind] + [{"volume": view["volume"], "cube": cube_key(view), "voxel": vox,
+                                          "voxel_zyx": [int(v + o) for v, o in zip(vox, view["origin"])],
+                                          "vec": vec}]
+            if "Your clicks" not in overlays:
+                overlays = list(overlays) + ["Your clicks"]
+            return [state] + slider_updates(state) + show(state, overlays, top_pct, opacity) + [overlays]
+        return handler
+
+    @guard
+    def on_clear(state, overlays, top_pct, opacity):
+        state = dict(state, pos=[], neg=[])
+        return [state] + show(state, overlays, top_pct, opacity)
+
+    @guard
+    def on_concept(path, state, overlays, top_pct, opacity):
+        if not path:
+            return [state] + show(state, overlays, top_pct, opacity) + [overlays]
+        vec = lens.load_concept(path)
+        state = dict(state, pos=[{"volume": "file", "cube": "file", "voxel": [-1, -1, -1], "voxel_zyx": None,
+                                  "vec": vec}], neg=[])
+        if "Your clicks" not in overlays:
+            overlays = list(overlays) + ["Your clicks"]
+        return [state] + show(state, overlays, top_pct, opacity) + [overlays]
+
+    @guard
+    def on_save(state):
+        return save_files(state), (state["view"] or {}).get("receipt")
+
+    def on_load(state, overlays, top_pct, opacity, request: gr.Request):
+        q = dict(request.query_params) if request else {}
+        fields = [gr.update()] * 4
+        try:
+            if q.get("v") in lens.VOLUMES:
+                fields = [q["v"]] + [int(q[k]) if str(q.get(k, "")).isdigit() else gr.update() for k in "zyx"]
+            cube_id = q.get("cube") or ((not q.get("v")) and GALLERY and GALLERY[0]["id"])
+            if cube_id:
+                state = dict(state)
+                state["view"] = load_gallery(cube_id)
+                if not q.get("v"):
+                    p = state["view"]["point"]
+                    fields = [state["view"]["volume"], p[0], p[1], p[2]]
+        except (LensError, ValueError, OSError) as exc:
+            log(f"link not loaded: {exc}")
+        size = gr.update(value=int(q["size"])) if q.get("size") in ("128", "256") else gr.update()
+        return ([state] + slider_updates(state) + show(state, overlays, top_pct, opacity) + fields + [size]
+                + [gr.update(value=state["view"] and state["view"].get("receipt", {}).get("gallery_id"))])
+
+    with gr.Blocks(title="Scroll Lens", delete_cache=(1800, 3600)) as demo:
+        state = gr.State(empty_state(), time_to_live=STATE_TTL_S)
+        gr.HTML('<div class="sl-head"><h1>Scroll Lens</h1><span>Look inside a Herculaneum scroll with the '
+                'Vesuvius Challenge’s 3D models: embeddings, ink and surfaces, and click to search.</span></div>')
+        with gr.Row(equal_height=False):
+            with gr.Column(scale=1, min_width=300, elem_id="sl-controls"):
+                with gr.Tab("Gallery"):
+                    gpick = gr.Dropdown(gal_choices, value=gal_choices[0][1] if gal_choices else None,
+                                        label="Ready-made cube (no GPU needed)", filterable=False)
+                    gbtn = gr.Button("Load cube", variant="primary")
+                    if not gal_choices:
+                        gr.Markdown("The gallery is empty on this copy. Pick a point instead.")
+                with gr.Tab("Your own point"):
+                    vid = gr.Dropdown(vol_choices, value="PHercParis4", label="Scan", filterable=False)
+                    vinfo = gr.Markdown(volume_text("PHercParis4"))
+                    with gr.Row():
+                        z = gr.Number(37628, label="z", precision=0, minimum=0)
+                        y = gr.Number(8793, label="y", precision=0, minimum=0)
+                        x = gr.Number(22167, label="x", precision=0, minimum=0)
+                    size = gr.Radio([128, 256], value=256, label="Cube side, voxels")
+                    layers = gr.CheckboxGroup(layer_names, value=layer_names, label="Models to run")
+                    tta = gr.Checkbox(False, label="Average eight mirrorings for ink and surface (slower, smoother)")
+                    with gr.Row():
+                        sbtn = gr.Button("Surprise me")
+                        rbtn = gr.Button("Run the models", variant="primary")
+                with gr.Accordion("Show and search", open=True):
+                    overlays = gr.CheckboxGroup(list(OVERLAYS), value=["Ink (3D ink model)", "Your clicks",
+                                                                       "Organisers' ink reference"],
+                                                label="Layers to show")
+                    mode = gr.Radio(list(CLICK_MODES), value=CLICK_MODES[0], label="Clicking a view does")
+                    top_pct = gr.Slider(1, 40, value=8, step=1, label="Top % of similar patches shown")
+                    opacity = gr.Slider(0, 1, value=0.7, step=0.05, label="Layer opacity")
+                    with gr.Row():
+                        clear = gr.Button("Clear clicks", size="sm")
+                    concept_up = gr.File(label="Load a concept.npy (864 numbers)", file_types=[".npy"],
+                                         type="filepath", height=90)
+                with gr.Accordion("How to use it", open=False):
+                    gr.Markdown(HOW_TO)
+            with gr.Column(scale=3, min_width=320, elem_id="sl-viewer"):
+                gr.HTML(LEGEND)
+                with gr.Row(elem_id="sl-views"):
+                    imgs = [gr.Image(label=VIEW_NAMES[a], interactive=False, buttons=["fullscreen"], type="numpy",
+                                     min_width=220)
+                            for a in range(3)]
+                with gr.Row():
+                    sliders = [gr.Slider(0, 255, value=128, step=1, label=n.split(" (")[1].rstrip(")") + " slice")
+                               for n in VIEW_NAMES]
+                info = gr.Markdown(numbers(empty_state(), 8))
+                with gr.Accordion("3D view", open=False):
+                    plot = gr.Plot(label="Ink and surface shells, similar patches as points")
+                    pbtn = gr.Button("Draw in 3D", size="sm")
+                with gr.Accordion("Save files", open=False):
+                    save = gr.Button("Save files", size="sm")
+                    files = gr.File(label="Model outputs, receipt and your concept", file_count="multiple")
+                    receipt = gr.JSON(label="Receipt")
+                with gr.Accordion("About", open=False):
+                    gr.Markdown(INTRO)
+        gr.HTML('<footer class="sl-credit">Built by Chase Hendrick · models and data by the Vesuvius Challenge · '
+                f'Scroll Lens {lens.VERSION}</footer>')
+
+        # hidden: the API endpoint for scripts and agents
+        with gr.Row(visible=False):
+            a_vid, a_layers = gr.Textbox(), gr.Textbox(value="dino,ink,surface")
+            a_z, a_y, a_x, a_size = gr.Number(precision=0), gr.Number(precision=0), gr.Number(precision=0), \
+                gr.Number(256, precision=0)
+            a_tta, a_compact, a_cpu = gr.Checkbox(False), gr.Checkbox(False), gr.Checkbox(False)
+            a_out, a_btn = gr.File(), gr.Button()
+
+        view_inputs = [overlays, top_pct, opacity]
+        shown = imgs + [info]
+        vid.change(volume_text, vid, vinfo, api_visibility="private")
+        rbtn.click(on_run, [vid, z, y, x, size, layers, tta, state] + view_inputs, [state] + sliders + shown,
+                   concurrency_id="models", concurrency_limit=2, api_visibility="private")
+        gbtn.click(on_gallery, [gpick, state] + view_inputs, [state] + sliders + shown + [vid, z, y, x],
+                   api_visibility="private")
+        sbtn.click(on_surprise, vid, [z, y, x], api_visibility="private")
+        for s in sliders:
+            s.release(on_slices, sliders + [state] + view_inputs, shown, api_visibility="private", show_progress="hidden")
+        for c in view_inputs:
+            c.change(on_slices, sliders + [state] + view_inputs, shown, api_visibility="private", show_progress="hidden")
+        for a in range(3):
+            imgs[a].select(on_select(a), [mode, state] + view_inputs, [state] + sliders + shown + [overlays],
+                           api_visibility="private", show_progress="hidden")
+        clear.click(on_clear, [state] + view_inputs, [state] + shown, api_visibility="private")
+        concept_up.change(on_concept, [concept_up, state] + view_inputs, [state] + shown + [overlays],
+                          api_visibility="private")
+        pbtn.click(lambda s, o, t: figure_3d(s, o, t), [state, overlays, top_pct], plot, api_visibility="private")
+        save.click(on_save, state, [files, receipt], api_visibility="private")
+        a_btn.click(guard(api_look), [a_vid, a_z, a_y, a_x, a_size, a_layers, a_tta, a_compact, a_cpu], a_out,
+                    api_name="look", concurrency_id="models", concurrency_limit=2)
+        demo.load(on_load, [state] + view_inputs, [state] + sliders + shown + [vid, z, y, x, size, gpick],
+                  api_visibility="private")
+    return demo
+
+
+if __name__ == "__main__":
+    startup()
+    build_demo().queue(max_size=24).launch(theme=theme(), css=CSS, footer_links=["api", "gradio"])

lens.py

@@ -0,0 +1,932 @@
+"""Scroll Lens core: everything except the web page.
+
+A visitor picks a point inside one of the released 2.4 um scans listed in VOLUMES. Scroll Lens reads the cube of
+the scan around that point from the Vesuvius Challenge open-data bucket and runs three models the Vesuvius
+Challenge released with the PHerc. Paris 4 paper (Angelotti et al. 2026, arXiv:2606.29085) on it:
+
+- dinovol, a 3D DINO model that turns every 8 x 8 x 8 voxel patch into an 864-number embedding;
+- ink_3d_dino_guided, a 3D U-Net that marks ink voxels directly in the scan (made for PHerc. Paris 4);
+- surface_recto_3dunet, a 3D U-Net that marks the written (recto) surface of each papyrus sheet.
+
+Clicks then light up every patch whose embedding is close to the clicked ones: the expert-click method the
+organisers used to build the reference ink embedding behind ink_3d_dino_guided. Everything here is model output,
+not a reading; a cube is 0.6 mm across, smaller than one letter.
+
+No gradio here, and torch is imported only inside the model code, so the tests run with numpy alone.
+
+  python3 lens.py volumes                       the scans this Space may read
+  python3 lens.py look PHercParis4 Z Y X [--size 128] [--layers dino,ink,surface] [--out DIR]
+  python3 lens.py files                         the files of the Space, with their SHA-256
+  python3 lens.py stage DEST                    copy them into DEST (absent or empty), laid out as the Space runs
+"""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import hashlib
+import io
+import json
+import math
+import os
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+VERSION = "1.0.0"
+BUCKET = "https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com"
+CHUNK = 128                 # every listed scan is stored as uncompressed uint8 chunks of 128^3 voxels
+SIZES = (128, 256)          # cube sides in voxels; 256 is the models' training patch, 128 fits a CPU
+PATCH = 8                   # dinovol embeds each 8^3 voxel patch
+EMBED_DIM = 864
+MIN_FOREGROUND = 0.05       # a cube with less papyrus than this (the scans are masked to 0 outside it) is refused
+REDUCED_DIM = 128           # gallery cubes keep this many components of each embedding (see reduce_grid)
+TAU = 0.5                   # the threshold the organisers used on cosine similarity to their ink reference
+MAX_CONCEPT_BYTES = 4 << 20
+USER_AGENT = f"scroll-lens/{VERSION}"
+
+
+class LensError(Exception):
+    """A refusal with a message meant for the visitor."""
+
+
+# ---------------------------------------------------------------- the scans this Space may read
+#
+# Only these volumes, all about 2.4 um scans at full resolution (level 0), the scale dinovol was trained on. None of
+# them is on the First Letters or Grand Prize eligible lists (kit/data/prizes-2026-10-11.json). Anything else is
+# refused before a byte is fetched. "role" says what each model saw of the scroll, from the model cards and the
+# checkpoints' own training configs (read 16 October 2026).
+
+INK_TEACHER = ("Not trained on this scroll, but its teacher model (stage 1) was trained on this scroll's "
+               "ink labels.")
+VOLUMES = {
+    "PHercParis4": dict(
+        scroll="PHerc. Paris 4", scan="20260411134726-2.400um-0.2m-78keV-masked.zarr", voxel_um=2.400,
+        shape=(75784, 32693, 32693),
+        role=dict(dino="Trained on this scan.", ink="Trained on this scroll: the model was made for it.",
+                  surface="Not in its training list."),
+        note="Scroll 1 of the Vesuvius Challenge. Unwrapped and read in Angelotti et al. 2026, where ink is "
+             "visible in the scan itself. Its title is still an open prize."),
+    "PHerc0139": dict(
+        scroll="PHerc. 139", scan="20260102150214-2.399um-0.2m-78keV-masked.zarr", voxel_um=2.399,
+        shape=(76953, 26511, 26511),
+        role=dict(dino="Trained on this scan.", ink=INK_TEACHER, surface="Trained on this scroll."),
+        note="The scroll Unroll shows in 3D, with 37 traced windings and published ink detection."),
+    "PHerc1667": dict(
+        scroll="PHerc. 1667 (Scroll 4)", scan="20251217075048-2.399um-0.2m-78keV-masked.zarr", voxel_um=2.399,
+        shape=(37076, 15229, 15229),
+        role=dict(dino="Not in its training list.", ink=INK_TEACHER, surface="Trained on this scroll."),
+        note="The one scan here that dinovol never saw in training."),
+    "PHerc0500P2": dict(
+        scroll="PHerc. 500P2", scan="20250526151718-2.215um-0.4m-111keV-masked.zarr", voxel_um=2.215,
+        shape=(28096, 18209, 18209),
+        role=dict(dino="Trained on this scan.", ink=INK_TEACHER, surface="Trained on this scroll."),
+        note="Seen in training by all three models."),
+    "PHerc0343P": dict(
+        scroll="PHerc. 343P", scan="20260304131111-2.215um-0.4m-111keV-masked.zarr", voxel_um=2.215,
+        shape=(20714, 13155, 13155),
+        role=dict(dino="Trained on this scan.", ink="Not in its training list.",
+                  surface="Trained on this scroll."),
+        note="The First Letters prize for PHerc. 343 was awarded on 8 October 2026."),
+    "PHerc0814": dict(
+        scroll="PHerc. 814", scan="20260309142202-2.399um-0.2m-78keV-masked.zarr", voxel_um=2.399,
+        shape=(74568, 23891, 23891),
+        role=dict(dino="Trained on this scan.", ink=INK_TEACHER, surface="Not in its training list."),
+        note=""),
+    "PHerc0009B": dict(
+        scroll="PHerc. 9B", scan="20250820154339-2.401um-0.3m-77keV-masked.zarr", voxel_um=2.401,
+        shape=(29112, 28259, 28259),
+        role=dict(dino="Trained on this scan.", ink=INK_TEACHER, surface="Not in its training list."),
+        note=""),
+    "PHercMAN5": dict(
+        scroll="PHerc. MAN 5", scan="20260311104824-2.399um-0.2m-78keV-masked.zarr", voxel_um=2.399,
+        shape=(31640, 17495, 17495),
+        role=dict(dino="Trained on this scan.", ink=INK_TEACHER, surface="Not in its training list."),
+        note=""),
+    "PHerc1299": dict(
+        scroll="PHerc. 1299", scan="20260309130042-2.399um-0.2m-78keV-masked.zarr", voxel_um=2.399,
+        shape=(49233, 20579, 20579),
+        role=dict(dino="Trained on this scan.", ink="Not in its training list.",
+                  surface="Not in its training list."),
+        note=""),
+    "PHerc0332": dict(
+        scroll="PHerc. 332", scan="20251211183505-2.399um-0.2m-78keV-masked.zarr", voxel_um=2.399,
+        shape=(33592, 15761, 15761),
+        role=dict(dino="Trained on this scan.", ink="Not in its training list.",
+                  surface="Not in its training list."),
+        note=""),
+    "PHerc1451": dict(
+        scroll="PHerc. 1451", scan="20260319101107-2.399um-0.2m-78keV-masked.zarr", voxel_um=2.399,
+        shape=(59944, 20811, 20811),
+        role=dict(dino="Trained on this scan.", ink="Not in its training list.",
+                  surface="Not in its training list."),
+        note=""),
+    "PHercMANB": dict(
+        scroll="PHerc. MAN B", scan="20260323091048-2.399um-0.2m-78keV-masked.zarr", voxel_um=2.399,
+        shape=(72681, 26723, 26723),
+        role=dict(dino="Trained on this scan.", ink="Not in its training list.",
+                  surface="Listed as MAN Bp on the model card: trained on this scroll."),
+        note=""),
+}
+
+# PHerc. Paris 4's title is still an open prize, so Scroll Lens never picks Paris 4 points itself: "Surprise me" and the
+# gallery use only these, the eight Paris 4 points the organisers listed for training in the ink checkpoint's own
+# config (extra_patches.coords_xyz of ckpt_78k_fullsup.pth, sampled with 1024 voxels of jitter), here as z y x.
+PARIS4_TRAINING_POINTS = ((37628, 8793, 22167), (35344, 19651, 19735), (70688, 19605, 10649), (41802, 16221, 12261),
+                          (41652, 10039, 8270), (41652, 8812, 8006), (41652, 10476, 19310), (41778, 17662, 27405))
+
+LAYERS = ("dino", "ink", "surface")
+LAYER_TITLES = {"dino": "3D DINO embeddings", "ink": "3D ink model", "surface": "Recto surface model"}
+
+# ---------------------------------------------------------------- the models and the code they need
+#
+# Weights come from the Hugging Face Hub at a pinned revision and are refused unless their SHA-256 matches.
+# The model code is the organisers' own: dinovol (MIT, with DINOv2 and DINOv3 parts under their licenses) and
+# villa's vesuvius package (MIT), each downloaded at a pinned commit and put on sys.path. Nothing of theirs is
+# copied into this Space.
+
+MODELS = {
+    "dino": dict(repo="scrollprize/dinovol_v2_ps8_with_paris4_352500",
+                 revision="6a8cccbafef191a966da815e22ff5c6eae075aae",
+                 file="dinovol_v2_ps8_paris4_step352500_teacher_backbone.pt", bytes=863606099,
+                 sha256="e041ca870dd2570f8a44d1dd26db1197b3f74121f62023bc774fbc9d40e51a59"),
+    "ink": dict(repo="scrollprize/ink_3d_dino_guided", revision="73a79525466037432191284dfa237baf830c49ec",
+                file="ckpt_78k_fullsup.pth", bytes=1703138075,
+                sha256="5a148c2c1bb730bfa683f2b3e3cdfc2000424003605e42300b527ff90118b303"),
+    "ink_reference": dict(repo="scrollprize/ink_3d_dino_guided",
+                          revision="73a79525466037432191284dfa237baf830c49ec",
+                          file="avg_ref_embedding.npy", bytes=3584,
+                          sha256="61bdf93bc5e3fd956eebdbed52618985d27264b8a9e5cb043087d0f234507a81"),
+    "surface": dict(repo="scrollprize/surface_recto_3dunet", revision="8ce8a4627e5104dda0af2b05aaa49820c0888774",
+                    file="checkpoint_inference_ready.pth", bytes=1138388181,
+                    sha256="dd36b3a89b2f4e21a6cafa14fea459f775f846a6ed036f75fb8e6b65aee3137b"),
+}
+CODE = {
+    "dinovol": dict(repo="https://github.com/ScrollPrize/dinovol.git",
+                    tarball="https://codeload.github.com/ScrollPrize/dinovol/tar.gz/{commit}",
+                    commit="a72fda2b1e02389a8711b3dc6a26215237f35eca", keep="dinovol_2/",
+                    check="dinovol_2/model/model.py"),
+    "villa": dict(repo="https://github.com/ScrollPrize/villa.git",
+                  tarball="https://codeload.github.com/ScrollPrize/villa/tar.gz/{commit}",
+                  commit="b29f310957c7b29e7d332f9876e0e487819cfaa3", keep="vesuvius/src/",
+                  check="vesuvius/src/vesuvius/models/build/build_network_from_config.py"),
+}
+CACHE = Path(os.environ.get("LENS_CACHE") or Path(tempfile.gettempdir()) / "scroll-lens")
+
+
+def log(message):
+    print(f"[lens {time.strftime('%H:%M:%S')}] {message}", flush=True)
+
+
+# ---------------------------------------------------------------- cubes: where and how to read them
+
+def volume(vid):
+    """The listed volume `vid`, or a refusal. Nothing else is ever read."""
+    if vid not in VOLUMES:
+        raise LensError(f"{vid!r} is not one of the scans this Space may read")
+    return VOLUMES[vid]
+
+
+def volume_url(vid, level=0):
+    v = volume(vid)
+    return f"{BUCKET}/{vid}/volumes/{v['scan']}/{int(level)}"
+
+
+def cube_origin(vid, center_zyx, size):
+    """The corner of the cube of side `size` around `center_zyx` (level-0 voxels, z y x), snapped to the scan's
+    128-voxel chunk grid so a 256 cube is exactly 8 stored chunks, and kept inside the scan. The point lies inside
+    the cube, at most 64 voxels from its centre."""
+    size = check_size(size)
+    shape = volume(vid)["shape"]
+    out = []
+    for c, n in zip(center_zyx, shape):
+        c = int(c)
+        if not 0 <= c < n:
+            raise LensError(f"point {list(map(int, center_zyx))} is outside the scan, whose shape is {list(shape)}")
+        o = int(round((c - size / 2) / CHUNK)) * CHUNK
+        o = max(0, min(o, (n - size) // CHUNK * CHUNK))
+        out.append(o)
+    return tuple(out)
+
+
+def check_size(size):
+    size = int(size)
+    if size not in SIZES:
+        raise LensError(f"cube side must be one of {SIZES} voxels, not {size}")
+    return size
+
+
+def chunk_keys(origin, size):
+    """The stored chunks (z, y, x indices) that a cube at `origin` of side `size` covers."""
+    ranges = [range(o // CHUNK, (o + size - 1) // CHUNK + 1) for o in origin]
+    return [(a, b, c) for a in ranges[0] for b in ranges[1] for c in ranges[2]]
+
+
+def _get(url, timeout=60, tries=3):
+    """One object from the open-data bucket, anonymously. None for a missing chunk (all papyrus-free there)."""
+    last = None
+    for attempt in range(tries):
+        try:
+            req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return resp.read()
+        except urllib.error.HTTPError as exc:
+            if exc.code in (403, 404):
+                return None
+            last = exc
+        except (urllib.error.URLError, TimeoutError, ConnectionError) as exc:
+            last = exc
+        time.sleep(1.5 * (attempt + 1))
+    raise LensError(f"could not read the open-data bucket ({last}); try again in a minute")
+
+
+def read_cube(vid, origin, size, fetch=_get, workers=8):
+    """The uint8 cube of side `size` at `origin` (z y x, level 0). Chunks the bucket does not hold read as 0."""
+    import numpy as np
+    size = check_size(size)
+    shape = volume(vid)["shape"]
+    if any(o < 0 or o % CHUNK or o + size > n for o, n in zip(origin, shape)):
+        raise LensError(f"cube at {list(origin)} is not on the chunk grid inside the scan")
+    base = volume_url(vid)
+    keys = chunk_keys(origin, size)
+    out = np.zeros((size, size, size), np.uint8)
+
+    def one(key):
+        raw = fetch(f"{base}/{key[0]}/{key[1]}/{key[2]}")
+        if raw is None:
+            return key, None
+        if len(raw) != CHUNK ** 3:
+            raise LensError(f"chunk {key} has {len(raw)} bytes, not {CHUNK ** 3}: not an uncompressed uint8 chunk")
+        return key, np.frombuffer(raw, np.uint8).reshape(CHUNK, CHUNK, CHUNK)
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as pool:
+        for key, chunk in pool.map(one, keys):
+            if chunk is None:
+                continue
+            sl = tuple(slice(k * CHUNK - o, k * CHUNK - o + CHUNK) for k, o in zip(key, origin))
+            out[sl] = chunk
+    return out
+
+
+def foreground(cube):
+    """Fraction of voxels that are papyrus (the listed scans are masked to 0 outside the scroll)."""
+    return float((cube > 0).mean())
+
+
+def check_cube(cube):
+    frac = foreground(cube)
+    if frac < MIN_FOREGROUND:
+        raise LensError(f"only {frac:.1%} of this cube is papyrus; the scan is masked to 0 outside the scroll. "
+                        "Pick a point on the papyrus, or press Surprise me.")
+    return frac
+
+
+def random_point(vid, rng, fetch=_get, tries=24):
+    """A random point on papyrus: read random level-3 chunks (1/8 resolution) and pick a bright voxel in one."""
+    import numpy as np
+    shape = volume(vid)["shape"]
+    lv = 3
+    f = 2 ** lv
+    small = [math.ceil(n / f) for n in shape]
+    nchunks = [max(1, math.ceil(n / CHUNK)) for n in small]
+    base = volume_url(vid, lv)
+    for _ in range(tries):
+        # stay off the top and bottom tenth of the scroll, where the scan often holds no papyrus
+        cz = int(rng.integers(int(nchunks[0] * 0.1), max(int(nchunks[0] * 0.9), int(nchunks[0] * 0.1) + 1)))
+        cy, cx = (int(rng.integers(0, n)) for n in nchunks[1:])
+        raw = fetch(f"{base}/{cz}/{cy}/{cx}")
+        if raw is None or len(raw) != CHUNK ** 3:
+            continue
+        a = np.frombuffer(raw, np.uint8).reshape(CHUNK, CHUNK, CHUNK)
+        # papyrus is the brighter part of a masked scan; a 16-voxel margin keeps the cube away from the mask edge
+        inner = a[16:-16, 16:-16, 16:-16]
+        idx = np.argwhere(inner > max(1, np.percentile(a[a > 0], 60) if (a > 0).any() else 255))
+        if len(idx) < 50:
+            continue
+        for _ in range(16):
+            p = idx[int(rng.integers(0, len(idx)))] + 16
+            # the 256 cube around the point (16 voxels each way at this level) must lie inside the scroll mask
+            win = a[p[0] - 16:p[0] + 16, p[1] - 16:p[1] + 16, p[2] - 16:p[2] + 16]
+            if (win > 0).mean() < 0.9:
+                continue
+            zyx = [int((c * CHUNK + p[i]) * f + f // 2) for i, c in enumerate((cz, cy, cx))]
+            if all(0 <= v < n for v, n in zip(zyx, shape)):
+                return tuple(zyx)
+    raise LensError("could not find papyrus in this scan after several tries; try again")
+
+
+# ---------------------------------------------------------------- downloads: code and weights
+
+def sha256_file(path, block=1 << 22):
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for part in iter(lambda: fh.read(block), b""):
+            h.update(part)
+    return h.hexdigest()
+
+
+def _fetch_code(name, dest):
+    """One pinned repository's needed subtree: a sparse, blobless git fetch of the commit, else GitHub's tarball."""
+    spec = CODE[name]
+    commit = spec["commit"]
+    tmp = dest.with_name(dest.name + ".part")
+    shutil.rmtree(tmp, ignore_errors=True)
+    tmp.mkdir(parents=True)
+    try:
+        git = ["git", "-C", str(tmp)]
+        for cmd in (["init", "-q"], ["remote", "add", "origin", spec["repo"]],
+                    ["sparse-checkout", "set", spec["keep"].rstrip("/")],
+                    ["fetch", "-q", "--depth", "1", "--filter=blob:none", "origin", commit],
+                    ["checkout", "-q", "FETCH_HEAD"]):
+            subprocess.run(git + cmd, capture_output=True, text=True, check=True, timeout=900)
+        head = subprocess.run(git + ["rev-parse", "HEAD"], capture_output=True, text=True, check=True).stdout.strip()
+        if head != commit:
+            raise RuntimeError(f"git fetched {head}, not {commit}")
+        shutil.rmtree(tmp / ".git", ignore_errors=True)
+    except (OSError, RuntimeError, subprocess.SubprocessError) as exc:
+        log(f"git fetch of {name} failed ({getattr(exc, 'stderr', None) or exc}); trying the tarball")
+        shutil.rmtree(tmp, ignore_errors=True)
+        tmp.mkdir(parents=True)
+        _tarball(spec, tmp)
+    if not (tmp / spec["check"]).is_file():
+        raise RuntimeError(f"{name} at {commit} has no {spec['check']}")
+    (tmp / "COMMIT").write_text(commit + "\n")
+    shutil.rmtree(dest, ignore_errors=True)
+    os.replace(tmp, dest)
+
+
+def _tarball(spec, tmp):
+    """Stream GitHub's tarball of the pinned commit and keep only the needed subtree."""
+    root = tmp.resolve()
+    commit = spec["commit"]
+    kept = 0
+    req = urllib.request.Request(spec["tarball"].format(commit=commit), headers={"User-Agent": USER_AGENT})
+    with urllib.request.urlopen(req, timeout=900) as resp, tarfile.open(fileobj=resp, mode="r|gz") as tf:
+        for m in tf:
+            top, _, rel = m.name.partition("/")
+            if commit[:7] not in top:
+                raise RuntimeError(f"the tarball for {commit} holds {top!r}")
+            if not rel.startswith(spec["keep"]):
+                continue
+            target = (root / rel).resolve()
+            if root not in target.parents or m.issym() or m.islnk():
+                continue
+            if m.isdir():
+                target.mkdir(parents=True, exist_ok=True)
+            elif m.isfile():
+                target.parent.mkdir(parents=True, exist_ok=True)
+                with tf.extractfile(m) as src, open(target, "wb") as out:
+                    shutil.copyfileobj(src, out)
+                kept += 1
+    if not kept:
+        raise RuntimeError(f"the tarball for {commit} held no {spec['keep']} files")
+
+
+def ensure_code(cache=CACHE):
+    """Put dinovol and villa's vesuvius on sys.path at their pinned commits. LENS_DINOVOL and LENS_VILLA_SRC name
+    local checkouts instead (the dinovol repository root, and villa's vesuvius/src)."""
+    info = {}
+    for name, env, sub in (("dinovol", "LENS_DINOVOL", ""), ("villa", "LENS_VILLA_SRC", "vesuvius/src")):
+        if os.environ.get(env):
+            path = Path(os.environ[env]).expanduser().resolve()
+            info[name] = {"source": env, "path": str(path), "pinned": CODE[name]["commit"]}
+        else:
+            dest = Path(cache) / f"{name}-{CODE[name]['commit'][:12]}"
+            if not (dest / "COMMIT").is_file():
+                log(f"fetching {name} {CODE[name]['commit'][:12]}")
+                _fetch_code(name, dest)
+            path = dest / sub if sub else dest
+            info[name] = {"source": "pinned download", "commit": (dest / "COMMIT").read_text().strip()}
+        if str(path) not in sys.path:
+            sys.path.insert(0, str(path))
+    return info
+
+
+def ensure_weights(cache=CACHE, names=tuple(MODELS)):
+    """Each named file from the Hub at its pinned revision, refused unless its SHA-256 matches. LENS_WEIGHTS names
+    a folder holding local copies laid out as REPO_NAME/FILE (their SHA-256 is still checked)."""
+    paths = {}
+    local = os.environ.get("LENS_WEIGHTS")
+    for name in names:
+        spec = MODELS[name]
+        if local:
+            path = Path(local).expanduser() / spec["repo"].split("/")[1] / spec["file"]
+        else:
+            from huggingface_hub import hf_hub_download
+            path = Path(hf_hub_download(spec["repo"], spec["file"], revision=spec["revision"],
+                                        cache_dir=str(Path(cache) / "hub")))
+        digest = sha256_file(path)
+        if digest != spec["sha256"]:
+            raise RuntimeError(f"{spec['repo']}/{spec['file']} has SHA-256 {digest}, not {spec['sha256']}")
+        paths[name] = path
+    return paths
+
+
+# ---------------------------------------------------------------- the models
+
+class Engine:
+    """The three models, on the CPU until a call moves them. Built once per process."""
+
+    def __init__(self, cache=CACHE):
+        import numpy as np
+        t0 = time.time()
+        self.code = ensure_code(cache)
+        self.paths = ensure_weights(cache)
+        self.reference = np.load(self.paths["ink_reference"], allow_pickle=False).astype(np.float32)
+        self.reference /= np.linalg.norm(self.reference)
+        self.dino = self._load_dino(self.paths["dino"])
+        self.ink, self.ink_norm = self._load_ink(self.paths["ink"])
+        self.surface = self._load_surface(self.paths["surface"])
+        self.startup_s = round(time.time() - t0, 1)
+
+    # -- loading
+
+    @staticmethod
+    def _load_dino(path):
+        import torch
+        from dinovol_2.model.model import DinoVitStudentTeacher, _upgrade_weight_norm_state_dict_keys
+        ck = torch.load(path, map_location="cpu", weights_only=False)
+        state = {k.replace("backbone.", "", 1): v for k, v in ck["teacher"].items() if k.startswith("backbone.")}
+        net = DinoVitStudentTeacher._build_backbone(ck["config"]["model"])
+        net.load_state_dict(_upgrade_weight_norm_state_dict_keys(state), strict=True)
+        return net.eval()
+
+    @staticmethod
+    def _load_ink(path):
+        import torch
+        from vesuvius.ink_detection.inference.inference_runtime import TargetModel
+        from vesuvius.ink_detection.models.checkpoint import config_from_checkpoint, load_model_state
+        from vesuvius.ink_detection.models.model import make_model
+        payload = torch.load(path, map_location="cpu", weights_only=False)
+        cfg = config_from_checkpoint(payload)
+        net = make_model(cfg)
+        load_model_state(net, payload["ema_model"])   # the card recommends the EMA weights for inference
+        return TargetModel(net.eval()).eval(), cfg.data.normalization
+
+    @staticmethod
+    def _load_surface(path):
+        import torch
+        from types import SimpleNamespace
+        from vesuvius.models.build.build_network_from_config import NetworkFromConfig
+        ck = torch.load(path, map_location="cpu", weights_only=False)
+        mc = ck["model_config"]
+        mgr = SimpleNamespace(targets=mc["targets"], train_patch_size=tuple(mc["train_patch_size"]),
+                              train_batch_size=mc["train_batch_size"], in_channels=1, autoconfigure=False,
+                              model_config=mc, op_dims=3, spacing=(1.0, 1.0, 1.0), model_name=mc["model_name"])
+        net = NetworkFromConfig(mgr)
+        net.load_state_dict(ck["model"], strict=True)
+        return net.eval()
+
+    def describe(self):
+        return {"models": {k: {kk: v[kk] for kk in ("repo", "revision", "file", "sha256")}
+                           for k, v in MODELS.items()},
+                "code": self.code, "startup_s": self.startup_s}
+
+    # -- running
+
+    def run(self, cube, layers=LAYERS, device="cpu", tta=False):
+        """The chosen layers for one cube. Returns numpy arrays: `grid` (Z/8, Y/8, X/8, 864) float16 unit vectors,
+        `ink` and `surface` (Z, Y, X) uint8 probabilities times 255, and timings."""
+        import numpy as np
+        import torch
+        layers = check_layers(layers)
+        dev = torch.device(device)
+        out = {"device": str(dev), "device_name": _device_name(dev), "seconds": {}, "tta": bool(tta)}
+        for name in layers:
+            t0 = time.time()
+            if name == "dino":
+                out["grid"] = self._dino_grid(cube, dev)
+            elif name == "ink":
+                out["ink"] = self._ink(cube, dev, tta)
+            else:
+                out["surface"] = self._surface(cube, dev, tta)
+            if dev.type == "cuda":
+                torch.cuda.synchronize()
+            out["seconds"][name] = round(time.time() - t0, 3)
+        return out
+
+    def _autocast(self, dev):
+        import contextlib
+        import torch
+        return torch.autocast("cuda", dtype=torch.bfloat16) if dev.type == "cuda" else contextlib.nullcontext()
+
+    def _dino_grid(self, cube, dev):
+        """dinovol's dense patch embeddings, as its own napari inspector computes them: robust normalisation of
+        the whole cube, 128^3 windows overlapping by one patch, edge-tapered averaging, unit length."""
+        import numpy as np
+        import torch
+        import torch.nn.functional as F
+        from dinovol_2.dataset.normalization import get_normalization
+        net = self.dino.to(dev)
+        vol = get_normalization("robust", intensityproperties=None).run(cube.astype(np.float32))
+        n = cube.shape[0] // PATCH
+        win = min(n, 128 // PATCH)
+        starts = _window_starts(n, win, 1)
+        w1 = _taper(win, 1 if win < n else 0)
+        weight = w1[:, None, None] * w1[None, :, None] * w1[None, None, :]
+        acc = np.zeros((n, n, n, EMBED_DIM), np.float32)
+        wsum = np.zeros((n, n, n), np.float32)
+        with torch.inference_mode(), self._autocast(dev):
+            for z in starts:
+                for y in starts:
+                    for x in starts:
+                        tile = vol[z * PATCH:(z + win) * PATCH, y * PATCH:(y + win) * PATCH,
+                                   x * PATCH:(x + win) * PATCH]
+                        t = torch.from_numpy(np.ascontiguousarray(tile))[None, None].to(dev)
+                        tok = net.forward_features(t, masks=None, view_kind="global")["x_norm_patchtokens"][0]
+                        tok = F.normalize(tok.float().reshape(win, win, win, -1), dim=-1).cpu().numpy()
+                        acc[z:z + win, y:y + win, x:x + win] += tok * weight[..., None]
+                        wsum[z:z + win, y:y + win, x:x + win] += weight
+        grid = acc / np.maximum(wsum[..., None], np.finfo(np.float32).eps)
+        grid /= np.maximum(np.linalg.norm(grid, axis=-1, keepdims=True), 1e-12)
+        return grid.astype(np.float16)
+
+    def _ink(self, cube, dev, tta):
+        import numpy as np
+        import torch
+        from vesuvius.ink_detection.data.normalization import normalize_image
+        net = self.ink.to(dev)
+        x = torch.from_numpy(np.ascontiguousarray(normalize_image(cube.astype(np.float32), self.ink_norm)))
+        x = x[None, None].to(dev)
+        with torch.inference_mode(), self._autocast(dev):
+            prob = _mirrored(lambda t: net(t).float().sigmoid(), x, tta)
+        return _to_u8(prob[0, 0])
+
+    def _surface(self, cube, dev, tta):
+        import numpy as np
+        import torch
+        net = self.surface.to(dev)
+        c = cube.astype(np.float32)
+        x = torch.from_numpy((c - c.mean()) / max(float(c.std()), 1e-8))[None, None].to(dev)   # z-score, per cube
+        with torch.inference_mode(), self._autocast(dev):
+            prob = _mirrored(lambda t: torch.softmax(net(t)["surface"].float(), 1)[:, 1:2], x, tta)
+        return _to_u8(prob[0, 0])
+
+
+def _mirrored(fn, x, tta):
+    """fn(x), or with tta the mean of fn over the eight mirrorings of x, each flipped back (villa's mirror TTA)."""
+    if not tta:
+        return fn(x)
+    total = None
+    for axes in ((), (2,), (3,), (4,), (2, 3), (2, 4), (3, 4), (2, 3, 4)):
+        y = fn(x.flip(axes) if axes else x)
+        y = y.flip(axes) if axes else y
+        total = y if total is None else total + y
+    return total / 8.0
+
+
+def _to_u8(prob):
+    import numpy as np
+    return np.clip(np.rint(prob.float().cpu().numpy() * 255.0), 0, 255).astype(np.uint8)
+
+
+def _device_name(dev):
+    if dev.type == "cuda":
+        import torch
+        return torch.cuda.get_device_name(dev)
+    import platform
+    return platform.processor() or platform.machine()
+
+
+def _window_starts(n, win, overlap):
+    if win >= n:
+        return [0]
+    step = win - overlap
+    starts = list(range(0, n - win + 1, step))
+    if starts[-1] != n - win:
+        starts.append(n - win)
+    return starts
+
+
+def _taper(length, overlap):
+    import numpy as np
+    w = np.ones(length, np.float32)
+    if overlap <= 0 or length <= 1:
+        return w
+    r = np.arange(length, dtype=np.float32)
+    return np.minimum(np.minimum(r + 1.0, length - r) / float(overlap + 1), 1.0).astype(np.float32)
+
+
+def check_layers(layers):
+    layers = tuple(dict.fromkeys(layers or ()))
+    bad = [x for x in layers if x not in LAYERS]
+    if bad:
+        raise LensError(f"unknown layer {bad[0]!r}; choose from {', '.join(LAYERS)}")
+    if not layers:
+        raise LensError("choose at least one model to run")
+    return layers
+
+
+def gpu_seconds(size, layers, tta=False):
+    """What one cube asks ZeroGPU for. Generous until measured: the quota counts the time actually used."""
+    size, layers = check_size(size), check_layers(layers)
+    scale = (size / 256) ** 3
+    per = {"dino": 6.0, "ink": 4.0 * (8 if tta else 1), "surface": 4.0 * (8 if tta else 1)}
+    return int(math.ceil(12 + scale * sum(per[x] for x in layers)))
+
+
+# ---------------------------------------------------------------- embeddings: clicks, similarity, colours
+
+def unit(v, axis=-1):
+    import numpy as np
+    v = np.asarray(v, np.float32)
+    return v / np.maximum(np.linalg.norm(v, axis=axis, keepdims=True), 1e-12)
+
+
+def grid_of(result):
+    """The (Z/8, Y/8, X/8, 864) float32 unit embeddings of a result, rebuilt from a reduced gallery cube if needed."""
+    import numpy as np
+    if "grid" in result:
+        return np.asarray(result["grid"], np.float32)
+    if "grid_reduced" in result:
+        g = np.asarray(result["grid_reduced"], np.float32) @ np.asarray(result["grid_basis"], np.float32).T
+        return unit(g)
+    raise LensError("this cube has no DINO embeddings; run it with the 3D DINO layer")
+
+
+def reduce_grid(grid, k=REDUCED_DIM):
+    """Keep the top `k` directions of a cube's embeddings (uncentred SVD, so the common direction stays): 1/7 of the
+    size. Returns (coefficients float16, basis (864, k) float32). grid_of() rebuilds unit vectors from them."""
+    import numpy as np
+    g = np.asarray(grid, np.float32).reshape(-1, EMBED_DIM)
+    _, _, vt = np.linalg.svd(g[:: max(1, len(g) // 20000)], full_matrices=False)
+    basis = vt[:k].T.astype(np.float32)
+    coef = (g @ basis).reshape(*np.shape(grid)[:3], k)
+    return coef.astype(np.float16), basis
+
+
+def token_of(voxel_zyx, size):
+    """The DINO patch (token) index holding a voxel of the cube."""
+    n = size // PATCH
+    return tuple(int(min(max(int(v) // PATCH, 0), n - 1)) for v in voxel_zyx)
+
+
+def concept(grid, tokens):
+    """The organisers' recipe for a reference embedding: the unit-length mean of the clicked patches' embeddings."""
+    import numpy as np
+    if not tokens:
+        return None
+    vecs = np.stack([grid[t] for t in tokens]).astype(np.float32)
+    return unit(vecs.mean(0))
+
+
+def similarity(grid, positive, negative=None):
+    """Per patch: cosine similarity to the positive concept, minus that to the negative one when there is one."""
+    import numpy as np
+    s = np.tensordot(grid, positive, axes=([-1], [0])).astype(np.float32)
+    if negative is not None:
+        s = s - np.tensordot(grid, negative, axes=([-1], [0])).astype(np.float32)
+    return s
+
+
+def pca_colours(grid):
+    """The three main directions of a cube's embeddings as red, green and blue, stretched to the 1st and 99th
+    percentiles: patches the model sees as alike get alike colours. (Z, Y, X, 3) uint8 at patch resolution."""
+    import numpy as np
+    g = np.asarray(grid, np.float32).reshape(-1, grid.shape[-1])
+    g = g - g.mean(0)
+    _, _, vt = np.linalg.svd(g[:: max(1, len(g) // 20000)], full_matrices=False)
+    p = g @ vt[:3].T
+    # fix each component's sign so the colours do not flip between runs of the same cube
+    p *= np.sign(np.sum(p ** 3, axis=0, keepdims=True) + 1e-12)
+    lo, hi = np.percentile(p, 1, axis=0), np.percentile(p, 99, axis=0)
+    p = np.clip((p - lo) / np.maximum(hi - lo, 1e-6), 0, 1)
+    return (p * 255).astype(np.uint8).reshape(*grid.shape[:3], 3)
+
+
+def upsample(tokens, size):
+    """Patch-resolution values (Z/8, Y/8, X/8[, C]) to voxels by repetition."""
+    import numpy as np
+    f = size // tokens.shape[0]
+    a = np.repeat(tokens, f, axis=0)
+    a = np.repeat(a, f, axis=1)
+    return np.repeat(a, f, axis=2)
+
+
+def auc(scores, labels):
+    """Probability that a positive scores above a negative (ties count half). None when a class is empty."""
+    import numpy as np
+    s = np.asarray(scores, np.float64).ravel()
+    y = np.asarray(labels, bool).ravel()
+    n1, n0 = int(y.sum()), int((~y).sum())
+    if not n1 or not n0:
+        return None
+    order = np.argsort(s, kind="mergesort")
+    ranks = np.empty(len(s), np.float64)
+    sorted_s = s[order]
+    # average ranks over ties
+    i = 0
+    while i < len(s):
+        j = i
+        while j + 1 < len(s) and sorted_s[j + 1] == sorted_s[i]:
+            j += 1
+        ranks[order[i:j + 1]] = (i + j) / 2.0 + 1.0
+        i = j + 1
+    return float((ranks[y].sum() - n1 * (n1 + 1) / 2.0) / (n1 * n0))
+
+
+def agreement(sim_tokens, ink_u8, threshold=0.5):
+    """How well a patch similarity map picks out the patches the 3D ink model marks as ink (mean probability over
+    the patch above `threshold`), as an AUC, beside a control that must fail: the same ink mask moved by half the
+    cube along every axis, which breaks the link between place and score. Agreement with a model, not ground
+    truth."""
+    import numpy as np
+    n = sim_tokens.shape[0]
+    f = ink_u8.shape[0] // n
+    ink_tok = ink_u8.reshape(n, f, n, f, n, f).mean(axis=(1, 3, 5)) / 255.0 > threshold
+    shifted = np.roll(ink_tok, (n // 2, n // 2, n // 2), axis=(0, 1, 2))
+    return {"auc": auc(sim_tokens, ink_tok), "auc_control_shifted": auc(sim_tokens, shifted),
+            "ink_patch_fraction": float(ink_tok.mean())}
+
+
+def load_concept(path):
+    """A concept file a visitor uploads: .npy, float, shape (864,) or (K, 864), finite, at most 4 MB, no pickles.
+    Returns the unit-length mean."""
+    import numpy as np
+    p = Path(path)
+    if p.stat().st_size > MAX_CONCEPT_BYTES:
+        raise LensError(f"a concept file is at most {MAX_CONCEPT_BYTES >> 20} MB")
+    try:
+        a = np.load(p, allow_pickle=False)
+    except (ValueError, OSError) as exc:
+        raise LensError(f"not a plain .npy array: {exc}") from None
+    if a.dtype.kind != "f" or a.ndim not in (1, 2) or a.shape[-1] != EMBED_DIM:
+        raise LensError(f"a concept is a float array of shape ({EMBED_DIM},) or (K, {EMBED_DIM}), not {a.dtype} "
+                        f"{a.shape}")
+    a = a.astype(np.float32).reshape(-1, EMBED_DIM)
+    if not np.isfinite(a).all() or not np.linalg.norm(a, axis=1).all():
+        raise LensError("the concept holds non-finite or zero vectors")
+    return unit(unit(a).mean(0))
+
+
+# ---------------------------------------------------------------- saving and the gallery
+
+def receipt(vid, origin, size, center, result, engine_info=None, extra=None):
+    v = volume(vid)
+    r = {"tool": "Scroll Lens", "version": VERSION, "volume": vid, "scroll": v["scroll"],
+         "zarr": f"{BUCKET}/{vid}/volumes/{v['scan']}", "level": 0, "voxel_um": v["voxel_um"],
+         "point_zyx": [int(c) for c in center], "cube_origin_zyx": [int(o) for o in origin], "cube_size": int(size),
+         "layers": [k for k in LAYERS if k in result or (k == "dino" and "grid_reduced" in result)],
+         "device": result.get("device"), "device_name": result.get("device_name"), "tta": result.get("tta", False),
+         "seconds": result.get("seconds", {}), "models_trained_on_this_scroll": v["role"],
+         "note": "Model output, not a reading. A cube is smaller than one letter."}
+    if engine_info:
+        r["engine"] = engine_info
+    if extra:
+        r.update(extra)
+    return r
+
+
+def quantize(prob_u8, levels=16):
+    """uint8 probabilities rounded to `levels` evenly spaced values (0, 17, ..., 255 for 16): a compact gallery cube
+    is about a quarter of the size and no probability moves by more than 8/255."""
+    import numpy as np
+    step = 255 // (levels - 1)
+    return (np.rint(np.asarray(prob_u8, np.float32) / step) * step).clip(0, 255).astype(np.uint8)
+
+
+def save_npz(path, cube_meta, result, compact=False):
+    """A cube's model outputs (not the scan, which anyone can read again from the bucket): embeddings as float16
+    unit vectors, ink and surface as uint8, and the receipt as JSON. `compact` (the gallery) keeps REDUCED_DIM
+    components of the embeddings (see reduce_grid) and 16 levels of each probability (see quantize)."""
+    import numpy as np
+    meta = dict(cube_meta, compact=bool(compact))
+    arrays = {"receipt": np.frombuffer(json.dumps(meta).encode(), np.uint8)}
+    if "grid" in result:
+        if compact:
+            arrays["grid_reduced"], arrays["grid_basis"] = reduce_grid(result["grid"])
+        else:
+            arrays["grid"] = np.asarray(result["grid"], np.float16)
+    elif "grid_reduced" in result:
+        arrays["grid_reduced"], arrays["grid_basis"] = result["grid_reduced"], result["grid_basis"]
+    for k in ("ink", "surface"):
+        if k in result:
+            arrays[k] = quantize(result[k]) if compact else np.asarray(result[k], np.uint8)
+    np.savez_compressed(path, **arrays)
+    return Path(path)
+
+
+def load_npz(path):
+    """A cube saved by save_npz, checked: the shapes agree with the receipt and nothing holds Python objects."""
+    import numpy as np
+    with np.load(path, allow_pickle=False) as z:
+        out = {k: z[k] for k in z.files}
+    meta = json.loads(bytes(out.pop("receipt")).decode())
+    size = check_size(meta["cube_size"])
+    volume(meta["volume"])
+    n = size // PATCH
+    if "grid" in out and out["grid"].shape != (n, n, n, EMBED_DIM):
+        raise LensError(f"{path}: embeddings of shape {out['grid'].shape}, not {(n, n, n, EMBED_DIM)}")
+    if "grid_reduced" in out and (out["grid_reduced"].shape[:3] != (n, n, n)
+                                  or out["grid_basis"].shape != (EMBED_DIM, out["grid_reduced"].shape[3])):
+        raise LensError(f"{path}: reduced embeddings do not match their basis")
+    for k in ("ink", "surface"):
+        if k in out and (out[k].shape != (size,) * 3 or out[k].dtype != np.uint8):
+            raise LensError(f"{path}: {k} is {out[k].dtype} {out[k].shape}, not uint8 {(size,) * 3}")
+    return meta, out
+
+
+def gallery(root=HERE / "gallery"):
+    """The precomputed cubes: gallery/index.json lists them, each with its .npz beside it."""
+    idx = Path(root) / "index.json"
+    if not idx.is_file():
+        return []
+    items = json.loads(idx.read_text()).get("cubes", [])
+    for it in items:
+        volume(it["volume"])
+        for key in ("id", "title", "note", "file", "point_zyx", "size"):
+            if key not in it:
+                raise LensError(f"gallery entry {it.get('id')!r} has no {key}")
+        if "/" in it["file"] or ".." in it["file"] or not it["file"].endswith(".npz"):
+            raise LensError(f"gallery entry {it['id']!r} names a file outside gallery/")
+    return items
+
+
+# ---------------------------------------------------------------- the Space's own files
+
+SPACE_FILES = ("README.md", "app.py", "lens.py", "requirements.txt", "LICENSE", "NOTICE")
+
+
+def space_files(root=HERE):
+    """The code and text of the Space. The gallery is not among them: tools/build_gallery.py uploads it."""
+    files = [root / f for f in SPACE_FILES]
+    missing = [str(p) for p in files if not p.is_file()]
+    if missing:
+        raise RuntimeError(f"missing Space files: {missing}")
+    return files
+
+
+def stage(dest, root=HERE):
+    dest = Path(dest)
+    if dest.exists() and any(dest.iterdir()):
+        raise RuntimeError(f"{dest} is not empty")
+    for p in space_files(root):
+        rel = p.relative_to(root)
+        (dest / rel).parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(p, dest / rel)
+    return dest
+
+
+# ---------------------------------------------------------------- command line
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("volumes", help="the scans this Space may read")
+    lk = sub.add_parser("look", help="run the models on one cube on this machine and save it")
+    lk.add_argument("volume")
+    lk.add_argument("zyx", nargs=3, type=int, help="a point in level-0 voxels, z y x")
+    lk.add_argument("--size", type=int, default=128, choices=SIZES)
+    lk.add_argument("--layers", default="dino,ink,surface")
+    lk.add_argument("--tta", action="store_true", help="average the eight mirrorings (8x the ink and surface time)")
+    lk.add_argument("--device", default=None, help="cpu or cuda (default: cuda when present)")
+    lk.add_argument("--out", default=".", help="folder for CUBE.npz and CUBE.json")
+    sub.add_parser("files", help="the Space's files with their SHA-256")
+    st = sub.add_parser("stage", help="copy the Space's files into an empty folder")
+    st.add_argument("dest")
+    a = ap.parse_args(argv)
+    try:
+        if a.cmd == "volumes":
+            for vid, v in VOLUMES.items():
+                print(f"{vid:12s} {v['scroll']:24s} {v['voxel_um']:.3f} um  {v['scan']}")
+            return 0
+        if a.cmd == "files":
+            for p in space_files():
+                print(f"{sha256_file(p)}  {p.relative_to(HERE)}")
+            return 0
+        if a.cmd == "stage":
+            print(stage(a.dest))
+            return 0
+        import torch
+        device = a.device or ("cuda" if torch.cuda.is_available() else "cpu")
+        layers = check_layers(a.layers.split(","))
+        origin = cube_origin(a.volume, a.zyx, a.size)
+        cube = read_cube(a.volume, origin, a.size)
+        check_cube(cube)
+        eng = Engine()
+        res = eng.run(cube, layers, device=device, tta=a.tta)
+        meta = receipt(a.volume, origin, a.size, a.zyx, res, eng.describe())
+        if "grid" in res and "ink" in res:
+            meta["agreement_with_ink_model"] = agreement(similarity(res["grid"].astype("float32"), eng.reference),
+                                                         res["ink"])
+        out = Path(a.out)
+        out.mkdir(parents=True, exist_ok=True)
+        name = f"{a.volume}-{'-'.join(map(str, origin))}-{a.size}"
+        save_npz(out / f"{name}.npz", meta, res)
+        (out / f"{name}.json").write_text(json.dumps(meta, indent=1) + "\n")
+        print(json.dumps(meta, indent=1))
+        return 0
+    except LensError as exc:
+        print(f"lens: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

requirements.txt

@@ -0,0 +1,17 @@
+# Scroll Lens on a Hugging Face ZeroGPU Space (Gradio 6.28.0 and Python 3.12 come from the README card; `spaces` is
+# preinstalled there). The torch, torchvision, numpy, timm, einops, zarr and numcodecs pins are the ones the
+# AutoPipeline ink Space runs on the same hardware. The models' own code (dinovol and villa's vesuvius package) is
+# downloaded at pinned commits when the Space starts, see lens.CODE.
+torch==2.13.0
+torchvision==0.28.0
+numpy==2.5.2
+timm==1.0.30
+einops==0.8.2
+zarr==3.4.1
+numcodecs==0.16.5
+pynrrd==1.1.3
+pyyaml==6.0.3
+requests==2.34.2
+huggingface_hub>=0.34
+scikit-image==0.26.0
+plotly==7.1.0