SharpMeow commited on
Commit
c368438
·
verified ·
1 Parent(s): cbb6237

Ink Lens 0.1.0

Browse files
Files changed (20) hide show
  1. CONNECT.md +108 -0
  2. LICENSE +201 -0
  3. NOTICE +29 -0
  4. README.md +105 -6
  5. app.py +373 -0
  6. bridge.py +116 -0
  7. connect.html +85 -0
  8. connect.json +64 -0
  9. engine.py +541 -0
  10. gate.py +138 -0
  11. inklens.py +627 -0
  12. kit/__init__.py +7 -0
  13. kit/auc.py +345 -0
  14. kit/fetch.py +126 -0
  15. kit/layers.py +147 -0
  16. kit/verify.py +191 -0
  17. requirements.txt +20 -0
  18. samples.json +55 -0
  19. vc3dout.py +417 -0
  20. volio.py +262 -0
CONNECT.md ADDED
@@ -0,0 +1,108 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Connect your tool: Ink Lens
2
+
3
+ The sample segments Ink Lens reads are open data, and each one reads straight from its URL in your own tool. The page is also an API and an MCP server once it is deployed.
4
+
5
+ Checked 2026-10-24. Generated from `connect.json` by `kit spaceconnect` in [ChaseHendrick/Scrolls](https://github.com/ChaseHendrick/Scrolls).
6
+
7
+ ## Sample layers, PHerc0841 w00 (9.366 um surface volume)
8
+
9
+ `https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr`
10
+
11
+ License: CC BY-NC 4.0 (Vesuvius Challenge open data).
12
+
13
+ ### Python (zarr) (tested 2026-10-24)
14
+
15
+ ```python
16
+ # pip install "zarr>=3" fsspec aiohttp
17
+ import zarr
18
+
19
+ root = zarr.open_group("https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr", mode="r") # OME-Zarr, zarr v2
20
+ a = root["0"] # level 0 is full resolution; level L is 2**L times coarser
21
+ print(a.shape, a.dtype, a.chunks)
22
+ block = a[0:64, 2800:2864, 2900:2964] # (z, y, x); reads only the chunks it touches
23
+ ```
24
+
25
+ ### villa's vesuvius package (tested 2026-10-24)
26
+
27
+ ```python
28
+ # pip install "vesuvius[volume-only]"
29
+ from vesuvius import Volume
30
+
31
+ v = Volume(type="zarr", path="https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr/0") # one pyramid level
32
+ block = v[0:64, 2800:2864, 2900:2964]
33
+ ```
34
+
35
+ ### curl (tested 2026-10-24)
36
+
37
+ ```bash
38
+ curl -s https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr/.zattrs # OME multiscales metadata
39
+ curl -s https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr/0/.zarray # one level: shape, chunks, dtype, codec
40
+ ```
41
+
42
+ ## Its surface (tifxyz)
43
+
44
+ `https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/mesh/20260220213127-on-20250821151531-9.366um.tifxyz`
45
+
46
+ License: CC BY-NC 4.0 (Vesuvius Challenge open data).
47
+
48
+ ### Python (numpy, tifffile) (tested 2026-10-24)
49
+
50
+ ```python
51
+ # pip install numpy tifffile
52
+ import io, json, urllib.request
53
+ import numpy as np, tifffile
54
+
55
+ T = "https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/mesh/20260220213127-on-20250821151531-9.366um.tifxyz"
56
+ meta = json.load(urllib.request.urlopen(T + "/meta.json")) # scale, bbox, format
57
+ get = lambda c: tifffile.imread(io.BytesIO(urllib.request.urlopen(f"{T}/{c}.tif").read()))
58
+ xyz = np.stack([get(c) for c in "xyz"], -1) # xyz[i, j] = (x, y, z) in scan voxels; -1 = no surface
59
+ ```
60
+
61
+ ## Call Ink Lens from code or an agent
62
+
63
+ `https://huggingface.co/spaces/SharpMeow/ink-lens`
64
+
65
+ License: Code Apache 2.0; d9v2 MIT; scans CC BY-NC 4.0. Not deployed yet; these calls work once it is. Model output, not a reading.
66
+
67
+ ### Python /lens_sample (not deployed yet)
68
+
69
+ ```python
70
+ # pip install gradio_client
71
+ from gradio_client import Client
72
+
73
+ client = Client("SharpMeow/ink-lens")
74
+ result = client.predict(sample_id="0841-w00", size=640, reader="d9v2", windows=3, api_name="/lens_sample")
75
+ ```
76
+
77
+ ### Python /list_samples (not deployed yet)
78
+
79
+ ```python
80
+ # pip install gradio_client
81
+ from gradio_client import Client
82
+
83
+ client = Client("SharpMeow/ink-lens")
84
+ result = client.predict(api_name="/list_samples")
85
+ ```
86
+
87
+ ### curl /lens_sample (not deployed yet)
88
+
89
+ ```bash
90
+ URL=https://sharpmeow-ink-lens.hf.space
91
+ EVENT=$(curl -s -X POST $URL/gradio_api/call/lens_sample -H 'Content-Type: application/json' \
92
+ -d '{"data": ["0841-w00", 640, "d9v2", 3]}' | python3 -c 'import json,sys; print(json.load(sys.stdin)["event_id"])')
93
+ curl -sN $URL/gradio_api/call/lens_sample/$EVENT
94
+ ```
95
+
96
+ ### MCP (Claude, Cursor and other agents) (not deployed yet)
97
+
98
+ ```json
99
+ {
100
+ "mcpServers": {
101
+ "ink-lens": {
102
+ "url": "https://sharpmeow-ink-lens.hf.space/gradio_api/mcp/sse"
103
+ }
104
+ }
105
+ }
106
+
107
+ Tool list: https://sharpmeow-ink-lens.hf.space/gradio_api/mcp/schema
108
+ ```
LICENSE ADDED
@@ -0,0 +1,201 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
NOTICE ADDED
@@ -0,0 +1,29 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Ink Lens
2
+ Copyright 2026 Chase Hendrick and Scrolls contributors
3
+
4
+ The Ink Lens code (app.py, engine.py, gate.py, inklens.py, vc3dout.py, volio.py, bridge.py and tools/) is licensed
5
+ under the Apache License, Version 2.0. See LICENSE. The staged Space also carries five modules of the Scrolls kit
6
+ (kit/__init__.py, auc.py, fetch.py, layers.py, verify.py), Apache License 2.0, same copyright.
7
+
8
+ engine.robust_np restates villa's normalize_robust and engine.hann2d villa's floored Hann blend map (both MIT,
9
+ Copyright (c) Vesuvius Challenge) so the batched device version can be checked against them. Ink Lens copies no other
10
+ third-party code. When it starts, it downloads the following at pinned versions and uses them under their own
11
+ licenses, which still apply:
12
+
13
+ - villa's vesuvius package, https://github.com/ScrollPrize/villa at commit
14
+ 8aa507c1215f1fa8758f13d0538f7af9710e02d7: MIT License, Copyright (c) Vesuvius Challenge.
15
+ - d9v2_ft-012000.pth, https://github.com/TAUIL-Abd-Elilah/pherc0826-first-letters-search release v1.0:
16
+ MIT License, Copyright (c) TAUIL-Abd-Elilah. A fine-tune of ink_9um.
17
+ - scrollprize/ink_9um hybrid_3d2d-seed42/step-075000.pth, https://huggingface.co/scrollprize/ink_9um: MIT License,
18
+ Copyright (c) Vesuvius Challenge.
19
+
20
+ The client's letter pins use the Scroll Text Reader (kit/letterread.py, Apache License 2.0) with the letters-v2-ccby
21
+ weights (CC BY 4.0; credits in docs/letter-reader.md of ChaseHendrick/Scrolls).
22
+
23
+ Scan data: Ink Lens reads CT scans from the Vesuvius Challenge open data, licensed CC BY-NC 4.0
24
+ (https://creativecommons.org/licenses/by-nc/4.0/). Giorgio Angelotti, Stephen Parsons, Sean Johnson, Elian Rafael
25
+ Dal Prà, Johannes Rudolph, Paul Tafforeau, Alessandro Mirone, Paul Henderson, Hendrik Schilling, Forrest McDonald,
26
+ David Josey, Youssef Nader, C. Seth Parker, W. Brent Seales. Vesuvius Challenge: CT Scans of Herculaneum Papyri.
27
+ Vesuvius Challenge. https://scrollprize.org/data
28
+
29
+ Maps the Space returns are model outputs computed from that data or from the caller's region; the Space keeps none.
README.md CHANGED
@@ -1,13 +1,112 @@
1
  ---
2
  title: Ink Lens
3
- emoji: 🌖
4
- colorFrom: blue
5
- colorTo: purple
6
  sdk: gradio
7
- sdk_version: 6.30.0
8
- python_version: '3.12'
9
  app_file: app.py
10
  pinned: false
 
 
 
 
 
 
 
 
 
 
 
 
 
11
  ---
12
 
13
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
  title: Ink Lens
3
+ emoji: 🔬
4
+ colorFrom: yellow
5
+ colorTo: gray
6
  sdk: gradio
7
+ sdk_version: 6.28.0
8
+ python_version: "3.12"
9
  app_file: app.py
10
  pinned: false
11
+ license: apache-2.0
12
+ suggested_hardware: zero-a10g
13
+ startup_duration_timeout: 1h
14
+ short_description: Control-checked ink maps of your own region, for VC3D
15
+ models:
16
+ - scrollprize/ink_9um
17
+ tags:
18
+ - vesuvius-challenge
19
+ - herculaneum
20
+ - ink-detection
21
+ - vc3d
22
+ - zerogpu
23
+ - mcp-server
24
  ---
25
 
26
+ # Ink Lens
27
+
28
+ A control-checked ink map of **your own region** of a segment, in one ZeroGPU call, written back into VC3D.
29
+
30
+ You pick a region in VC3D (or give a box). The client renders just that region, and one call to this Space runs an
31
+ openly licensed 9 um ink model over it **three times in depth** (three nearby 17-layer windows, averaged) and **in both
32
+ depth orders**: as stored and reversed, the community's reverse-depth control. The reversed map sets the threshold.
33
+ Only ink stronger than 99 % of what the control produces is kept, and the region gets a status that can fail:
34
+
35
+ | Status | Meaning |
36
+ | --- | --- |
37
+ | `ink` | at least 3 times as many papyrus pixels pass the control's 99th percentile as the control's own 1 % |
38
+ | `weak` | 1.5 to 3 times: look before trusting it |
39
+ | `none` | under 1.5 times: no ink above the control |
40
+ | `too_small` | under 100,000 papyrus pixels (about 3 mm square) |
41
+ | `unreadable` | a map is not finite, constant, or the same as its control |
42
+
43
+ The kept map then goes to the Scroll Text Reader, with the control's own kept map as its control map; when the
44
+ reader's controls pass, its letter candidates become 3D pins on the segment. The client writes VC3D's own files into
45
+ the segment folder: a transparent overlay in the Ink Detection panel (`ink-detections.json`, existing records kept),
46
+ a running mosaic of every region, and a VC3D point collection.
47
+
48
+ **Everything shown is model output, not a reading.** The rule is preregistered in
49
+ [`docs/prereg/2026-10-20-ink-lens-gate.md`](https://github.com/ChaseHendrick/Scrolls/blob/main/docs/prereg/2026-10-20-ink-lens-gate.md).
50
+
51
+ ## Readers
52
+
53
+ | Reader | License | Held out | PHerc0841 crops, raw / reversed AUC (w00, ag896, ag405) |
54
+ | --- | --- | --- | --- |
55
+ | d9v2 (default), [TAUIL-Abd-Elilah](https://github.com/TAUIL-Abd-Elilah/pherc0826-first-letters-search) | MIT | PHerc0841 | 0.899 / 0.586, 0.823 / 0.532, 0.832 / 0.657 |
56
+ | [`ink_9um`](https://huggingface.co/scrollprize/ink_9um) seed 42, Vesuvius Challenge | MIT | PHerc0841 | 0.806 / 0.536, 0.659 / 0.558, 0.784 / 0.642 |
57
+
58
+ Scores: public `docs/results.json` of ChaseHendrick/Scrolls (640 px crops, 64 px inner edge, villa's flat inference;
59
+ windows chosen with the labels, so development numbers). `both` runs the two and averages them (twice the GPU time).
60
+ Checkpoints are downloaded by URL, refused unless their SHA-256 matches, and opened with `weights_only=True`. The
61
+ models are built by villa's own flat ink inference at a pinned commit; the per-patch normalisation runs batched on the
62
+ GPU and matches villa's CPU function exactly in the tests.
63
+
64
+ ## GPU time
65
+
66
+ One call asks ZeroGPU for `ceil(4 + 0.012 x patches)` seconds, at most 40. A 1024 px region (about 1 cm, three or four
67
+ lines) with three windows is 1,350 patches: it asks for 21 s and is expected to use under 10 s. ZeroGPU admits a call
68
+ only while the requested time is left in your quota and bills what is used. When it refuses, a region of up to
69
+ 512 px with one window runs on the Space's CPU; larger regions belong in local mode.
70
+
71
+ ## Using it
72
+
73
+ **From VC3D** (the client, `inklens.py`, from [the source](https://github.com/ChaseHendrick/Scrolls/tree/main/spaces/ink-lens)):
74
+
75
+ ```bash
76
+ pip install numpy tifffile gradio_client huggingface_hub && hf auth login # your token: your own ZeroGPU quota
77
+ python3 inklens.py run --segment SEGDIR --volume /path/to/scan.zarr --box X Y W H # render pixels, scale 1
78
+ python3 inklens.py run --from-vc3d --volume /path/to/scan.zarr --size 1024 # VC3D with --agent-bridge
79
+ python3 inklens.py run ... --local # no account: this machine
80
+ ```
81
+
82
+ Then reopen the segment in VC3D: the map is in the Ink Detection panel as "Ink Lens d9v2 ink yY xX", and the pins are
83
+ a point collection (with `--bridge` they are merged into the open ones; File > Load replaces them all).
84
+
85
+ **On this page**: pick a public sample (PHerc0841 or PHerc0139, not prize-eligible) or upload a region as `.npz`.
86
+
87
+ ## For agents and scripts
88
+
89
+ Every endpoint is an API endpoint and an MCP tool (`/gradio_api/mcp/sse`; give the client your token as
90
+ `Authorization: Bearer hf_...`).
91
+
92
+ | Tool | What it does | GPU |
93
+ | --- | --- | --- |
94
+ | `lens_region` | an `.npz` region (array `volume`, uint8, layers first, about 9.6 um, 21 to 65 layers, 128 to 2048 px) in; result, maps `.npz` (forward, reverse, kept) and a preview out | yes |
95
+ | `lens_sample` | the same on a public sample crop, with the kept ink scored against the published labels | yes |
96
+ | `list_samples` | the samples and the readers, with what each reader saw in training | no |
97
+ | `estimate` | patches and requested GPU seconds for a region | no |
98
+
99
+ ```python
100
+ from gradio_client import Client, handle_file
101
+ c = Client("SharpMeow/ink-lens", token="hf_...")
102
+ result, maps, preview = c.predict(handle_file("region.npz"), "d9v2", 3, api_name="/lens_region")
103
+ ```
104
+
105
+ Nothing you send is kept: an upload is read into memory and deleted, and results go back in the response.
106
+
107
+ ## Credits and licenses
108
+
109
+ Code: Apache 2.0 (`LICENSE`, `NOTICE`), by Chase Hendrick. Readers: d9v2 by TAUIL-Abd-Elilah (MIT), `ink_9um` by the
110
+ Vesuvius Challenge (MIT); model code: villa's vesuvius package (MIT). Scan data: CC BY-NC 4.0, Vesuvius Challenge,
111
+ *CT Scans of Herculaneum Papyri* (https://scrollprize.org/data). Source and tests:
112
+ [github.com/ChaseHendrick/Scrolls](https://github.com/ChaseHendrick/Scrolls), `spaces/ink-lens/`.
app.py ADDED
@@ -0,0 +1,373 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Ink Lens: a control-checked ink map of one region, in one ZeroGPU call, for VC3D.
2
+
3
+ The web page, the API and the MCP server. The model work is engine.py, the threshold gate.py, and the files VC3D reads
4
+ are written by the client (inklens.py) on the user's own machine: the Space keeps nothing. A region arrives as an
5
+ .npz (array "volume", uint8, layers first, about 9.6 um), is read into memory, and goes back as maps and a status.
6
+
7
+ On a ZeroGPU Space the GPU is attached only to gpu_lens, for a duration computed from the region's patch count
8
+ (engine.gpu_seconds). When ZeroGPU refuses (quota, no GPU free) a region of at most CPU_SIDE px with one window runs on
9
+ the Space's CPU instead; anything larger is pointed to local mode.
10
+
11
+ python3 app.py serve the page (on a Space, or on any computer: CUDA if present, else CPU)
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import functools
17
+ import json
18
+ import os
19
+ import sys
20
+ import tempfile
21
+ import threading
22
+ import time
23
+ import zipfile
24
+ from pathlib import Path
25
+
26
+ try:
27
+ import spaces # first, before torch: on a ZeroGPU Space it attaches the GPU to spaces.GPU functions
28
+ except ImportError:
29
+ spaces = None
30
+
31
+ HERE = Path(__file__).resolve().parent
32
+ if str(HERE) not in sys.path:
33
+ sys.path.insert(0, str(HERE))
34
+ import engine # noqa: E402
35
+ import gate # noqa: E402
36
+ import inklens # noqa: E402
37
+ import volio # noqa: E402
38
+
39
+ ON_ZERO_GPU = bool(spaces) and os.environ.get("SPACES_ZERO_GPU", "").lower() in ("1", "true")
40
+ OUT = Path(tempfile.gettempdir()) / "ink-lens-out"
41
+ CPU_SIDE = 512
42
+ MAX_UPLOAD_BYTES = inklens.MAX_UPLOAD_BYTES
43
+ MAX_VOXELS = engine.MAX_SIDE * engine.MAX_SIDE * engine.MAX_LAYERS
44
+ ENGINE, ENGINE_ERROR = None, None
45
+ READY = threading.Event()
46
+ CPU_SLOT = threading.Semaphore(1)
47
+ GPU_REFUSALS = ("ZeroGPU quota exceeded", "ZeroGPU illegal duration", "ZeroGPU pending credits exceeded",
48
+ "ZeroGPU queue timeout", "ZeroGPU client error")
49
+
50
+
51
+ class LensError(ValueError):
52
+ """Shown to the caller as it is."""
53
+
54
+
55
+ def log(message):
56
+ print(f"[ink-lens {time.strftime('%H:%M:%S')}] {message}", flush=True)
57
+
58
+
59
+ # ---------------------------------------------------------------- start-up
60
+
61
+ def _load():
62
+ global ENGINE, ENGINE_ERROR
63
+ try:
64
+ ENGINE = engine.Engine(readers=tuple(engine.READERS))
65
+ log(f"readers ready in {ENGINE.startup_s} s")
66
+ except Exception as exc: # noqa: BLE001
67
+ ENGINE_ERROR = f"{type(exc).__name__}: {exc}"
68
+ log(f"readers failed to load: {ENGINE_ERROR}")
69
+ finally:
70
+ READY.set()
71
+
72
+
73
+ def startup():
74
+ import shutil
75
+ shutil.rmtree(OUT, ignore_errors=True)
76
+ OUT.mkdir(parents=True, exist_ok=True)
77
+ threading.Thread(target=_load, name="load-readers", daemon=True).start()
78
+
79
+
80
+ def eng(wait_s=5.0):
81
+ if not READY.wait(wait_s):
82
+ raise LensError("the readers are still loading (about a minute after the Space wakes up); try again shortly")
83
+ if ENGINE is None:
84
+ raise LensError(f"the readers failed to load: {ENGINE_ERROR}")
85
+ return ENGINE
86
+
87
+
88
+ # ---------------------------------------------------------------- the one GPU call
89
+
90
+ def _duration(volume, reader, windows):
91
+ return engine.gpu_seconds(engine.patches(volume.shape[1], volume.shape[2], windows, reader))
92
+
93
+
94
+ def _on_gpu(fn):
95
+ return spaces.GPU(duration=_duration)(fn) if ON_ZERO_GPU else fn
96
+
97
+
98
+ @_on_gpu
99
+ def gpu_lens(volume, reader, windows):
100
+ """Both depth orders, every window, every chosen reader: one GPU call, so the map never runs without its
101
+ control."""
102
+ return ENGINE.run(volume, reader=reader, windows=windows, device="cuda")
103
+
104
+
105
+ def _is_refusal(exc):
106
+ return (str(getattr(exc, "title", "") or "") in GPU_REFUSALS or "GPU task aborted" in str(exc)
107
+ or "No GPU was available" in str(exc))
108
+
109
+
110
+ def run_engine(volume, reader, windows):
111
+ e = eng()
112
+ import torch
113
+ if ON_ZERO_GPU:
114
+ try:
115
+ return gpu_lens(volume, reader, windows), ""
116
+ except Exception as exc: # noqa: BLE001
117
+ if not _is_refusal(exc):
118
+ raise
119
+ note = f"ZeroGPU refused the call ({str(getattr(exc, 'message', exc))[:160]})"
120
+ elif torch.cuda.is_available():
121
+ return e.run(volume, reader=reader, windows=windows, device="cuda"), ""
122
+ else:
123
+ note = "No GPU here"
124
+ if max(volume.shape[1:]) > CPU_SIDE or windows != 1:
125
+ raise LensError(f"{note}. The CPU fallback takes regions up to {CPU_SIDE} px with one window; run larger "
126
+ "regions in local mode (python3 inklens.py run --local ...), or try again later")
127
+ if not CPU_SLOT.acquire(blocking=False):
128
+ raise LensError(f"{note}, and the Space's CPU is busy with another fallback run; try again in a minute")
129
+ try:
130
+ torch.set_num_threads(max(1, (os.cpu_count() or 2) - 1))
131
+ return e.run(volume, reader=reader, windows=windows, device="cpu"), f"{note}, so it ran on the Space's CPU."
132
+ finally:
133
+ CPU_SLOT.release()
134
+
135
+
136
+ # ---------------------------------------------------------------- inputs
137
+
138
+ def read_npz(path):
139
+ """The 'volume' array of an uploaded .npz, refused before decompression when it is too big or not plain."""
140
+ import numpy as np
141
+ p = Path(path)
142
+ try:
143
+ if p.stat().st_size > MAX_UPLOAD_BYTES:
144
+ raise LensError(f"the upload is {p.stat().st_size / 2 ** 20:.1f} MB; the limit is "
145
+ f"{MAX_UPLOAD_BYTES >> 20} MB")
146
+ if p.suffix.lower() != ".npz":
147
+ raise LensError("upload an .npz with one array named 'volume' (uint8, layers x rows x columns)")
148
+ with zipfile.ZipFile(p) as zf:
149
+ infos = {i.filename: i for i in zf.infolist()}
150
+ if "volume.npy" not in infos:
151
+ raise LensError(f"the .npz holds {sorted(infos)}; it needs volume")
152
+ if infos["volume.npy"].file_size > MAX_VOXELS + 4096:
153
+ raise LensError("the volume is larger than a region may be (2048 x 2048 px, 65 layers)")
154
+ with np.load(p, allow_pickle=False) as z:
155
+ vol = z["volume"]
156
+ except (zipfile.BadZipFile, ValueError, OSError) as exc:
157
+ if isinstance(exc, LensError):
158
+ raise
159
+ raise LensError(f"not a readable .npz: {exc}") from None
160
+ finally:
161
+ try:
162
+ p.unlink()
163
+ except OSError:
164
+ pass
165
+ return volio.to_uint8(vol)
166
+
167
+
168
+ def preview(volume, kept_u8):
169
+ """The region's middle CT layer in gray with kept ink in amber, as an RGB array for the page."""
170
+ import numpy as np
171
+ ct = inklens.ct_middle(volume).astype(np.float32)
172
+ lo, hi = np.percentile(ct, [1, 99]) if ct.size else (0, 1)
173
+ g = np.clip((ct - lo) / max(hi - lo, 1e-6), 0, 1)
174
+ rgb = np.stack([g, g, g], -1)
175
+ a = (kept_u8.astype(np.float32) / 255.0)[..., None] * 0.85
176
+ rgb = rgb * (1 - a) + np.array([1.0, 0.62, 0.1]) * a
177
+ return (rgb * 255).astype(np.uint8)
178
+
179
+
180
+ def lens_volume(volume, reader, windows, sample=None, box=None):
181
+ engine.check_volume(volume, int(windows))
182
+ reader, windows = str(reader), int(windows)
183
+ requested = _duration(volume, reader, windows)
184
+ run, note = run_engine(volume, reader, windows)
185
+ decision, kept, _ = inklens.analyze(run["forward"], run["reverse"], volume)
186
+ result = {"tool": f"Ink Lens {engine.VERSION}", "gate": decision, "readers": run["readers"],
187
+ "windows": windows, "patches": run["patches"], "device": run["device"],
188
+ "device_name": run["device_name"], "seconds": run["seconds"], "gpu_seconds_requested": requested,
189
+ "window_layers": run["window_layers"], "stack_start": run.get("stack_start"),
190
+ "shape": [int(v) for v in volume.shape], "engine": ENGINE.describe(), "note": inklens.NOTE}
191
+ if note:
192
+ result["fallback"] = note
193
+ if len(run["readers"]) > 1:
194
+ result["per_reader"] = {n: gate.decide(m["forward"], m["reverse"], inklens.ct_middle(volume))
195
+ for n, m in run["per_reader"].items()}
196
+ if sample is not None:
197
+ result["sample"] = {"id": sample["id"], "role": sample["role"], "box": list(box)}
198
+ try:
199
+ ink, sup = inklens.labels_for(sample, box, run["forward"].shape)
200
+ from kit import auc
201
+ result["labels"] = {"shares": gate.label_shares(kept, ink, sup),
202
+ "auc_forward": auc.score_array(run["forward"], ink, sup, inner=64)["auc"],
203
+ "auc_reverse": auc.score_array(run["reverse"], ink, sup, inner=64)["auc"]}
204
+ except Exception as exc: # noqa: BLE001 (scoring is a bonus; the map stands without it)
205
+ result["labels"] = {"error": f"{type(exc).__name__}: {str(exc)[:200]}"}
206
+ import numpy as np
207
+ OUT.mkdir(parents=True, exist_ok=True)
208
+ maps = OUT / f"inklens-{int(time.time() * 1000)}.npz"
209
+ np.savez_compressed(maps, forward=run["forward"], reverse=run["reverse"], kept=gate.to_u8(kept))
210
+ return result, str(maps), preview(volume, gate.to_u8(kept))
211
+
212
+
213
+ def summary_md(result):
214
+ g = result["gate"]
215
+ lines = [f"**Status: {g['status']}.** {g['status_text']}.", ""]
216
+ if g.get("excess") is not None:
217
+ lines.append(f"Excess {g['excess']:.2f} (3 or more is ink, 1.5 to 3 weak); threshold T = {g['threshold']:.4f}, "
218
+ f"the 99th percentile of the reversed map on {g['papyrus_px']:,} papyrus pixels.")
219
+ if result.get("labels", {}).get("shares"):
220
+ s = result["labels"]["shares"]
221
+ lines += ["", f"Labels: kept ink covers {s['ink_kept_share']:.1%} of labeled ink pixels and "
222
+ f"{s['background_kept_share']:.1%} of labeled background. Raw AUC {result['labels']['auc_forward']}"
223
+ f", reversed control {result['labels']['auc_reverse']}."]
224
+ lines += ["", f"{result['patches']} patches on {result['device_name']} in {result['seconds']} s "
225
+ f"(asked ZeroGPU for {result['gpu_seconds_requested']} s).", "", "*Model output, not a reading.*"]
226
+ if result.get("fallback"):
227
+ lines.insert(0, f"> {result['fallback']}\n")
228
+ return "\n".join(lines)
229
+
230
+
231
+ # ---------------------------------------------------------------- API and MCP tools
232
+
233
+ def lens_region(volume_npz, reader="d9v2", windows=3):
234
+ """Ink map of your own region with its reverse-depth control and a status that can fail.
235
+
236
+ volume_npz: an .npz with one array 'volume' (uint8, layers x rows x columns, about 9.6 um per pixel, 21 to 65
237
+ layers centered on the papyrus surface, 128 to 2048 px a side). reader: d9v2 (default), ink_9um or both.
238
+ windows: 3 (default; three depth windows averaged) or 1. Returns the result (status ink, weak, none, too_small
239
+ or unreadable; excess; threshold), an .npz of the float maps (forward, reverse) and the kept map (uint8), and a
240
+ preview. Model output, not a reading."""
241
+ if not volume_npz:
242
+ raise LensError("upload an .npz first")
243
+ path = volume_npz if isinstance(volume_npz, str) else volume_npz.get("path")
244
+ return lens_volume(read_npz(path), reader, windows)
245
+
246
+
247
+ def lens_sample(sample_id="0841-w00", size=640, reader="d9v2", windows=3):
248
+ """Ink Lens on a public sample crop (PHerc0841 or PHerc0139, not prize-eligible), read from the open-data
249
+ bucket, with the kept ink scored against the published labels. size: 128 up to the sample's 640 px crop."""
250
+ s = inklens.sample_by(str(sample_id))
251
+ box = inklens.sample_box(s, int(size) if size else None)
252
+ volume, _ = inklens.read_sample(s, box)
253
+ return lens_volume(volume, reader, windows, sample=s, box=box)
254
+
255
+
256
+ def list_samples():
257
+ """The public samples Ink Lens can run on, with their crops and what each one is to the readers."""
258
+ return {"samples": [{k: s[k] for k in ("id", "title", "role", "crop", "surface_shape")}
259
+ for s in inklens.load_samples()["samples"]],
260
+ "readers": {n: {k: r[k] for k in ("title", "license", "source", "held_out")}
261
+ for n, r in engine.READERS.items()}}
262
+
263
+
264
+ def estimate(height=1024, width=1024, windows=3, reader="d9v2"):
265
+ """Patches and the ZeroGPU seconds one call on a height x width region (9.6 um pixels) asks for."""
266
+ return engine.estimate(int(height), int(width), int(windows), str(reader))
267
+
268
+
269
+ INTRO = """# Ink Lens
270
+
271
+ Pick a region of a segment and get an ink map **with its own control**. One ZeroGPU call runs an openly licensed
272
+ 9 um ink model ([d9v2](https://github.com/TAUIL-Abd-Elilah/pherc0826-first-letters-search), MIT, or the Vesuvius
273
+ Challenge's [`ink_9um`](https://huggingface.co/scrollprize/ink_9um), MIT) over three depth windows, with the layers as
274
+ stored and reversed. The reversed map sets the threshold: only ink stronger than 99 % of what the control produces is
275
+ kept, and the region gets a status that can fail (`none`: no ink above the control).
276
+
277
+ The client (`inklens.py`, from [ChaseHendrick/Scrolls](https://github.com/ChaseHendrick/Scrolls/tree/main/spaces/ink-lens))
278
+ renders the region from your VC3D segment, calls this Space with your own Hugging Face token (your ZeroGPU quota
279
+ pays, about 10 s for a 1 cm region) and writes the result back as VC3D's own files: an overlay in the Ink Detection
280
+ panel, and letter-candidate pins as a point collection.
281
+
282
+ **Everything shown is model output, not a reading.**
283
+ """
284
+
285
+ AGENTS = """```python
286
+ from gradio_client import Client, handle_file
287
+ c = Client("SharpMeow/ink-lens", hf_token=YOUR_TOKEN) # your token: your own ZeroGPU quota
288
+ result, maps, preview = c.predict(handle_file("region.npz"), "d9v2", 3, api_name="/lens_region")
289
+ result["gate"]["status"] # ink | weak | none | too_small | unreadable
290
+ ```
291
+ Also `/lens_sample`, `/list_samples`, `/estimate`; every endpoint is an MCP tool at `/gradio_api/mcp/sse`."""
292
+
293
+
294
+ def build_demo():
295
+ import gradio as gr
296
+
297
+ def guard(fn):
298
+ @functools.wraps(fn)
299
+ def wrapped(*args, **kwargs):
300
+ try:
301
+ return fn(*args, **kwargs)
302
+ except (LensError, inklens.Refused, engine.EngineError, gate.GateError, volio.VolumeError) as exc:
303
+ raise gr.Error(str(exc)) from None
304
+ except gr.Error:
305
+ raise
306
+ except Exception as exc: # noqa: BLE001
307
+ import traceback
308
+ log(f"{fn.__name__} failed: {traceback.format_exc()}")
309
+ raise gr.Error(f"{type(exc).__name__}: {str(exc)[:300]}") from None
310
+ return wrapped
311
+
312
+ def page_sample(sid, size, reader, windows):
313
+ result, maps, img = guard(lens_sample)(sid, size, reader, windows)
314
+ return summary_md(result), result, maps, img
315
+
316
+ def page_upload(f, reader, windows):
317
+ result, maps, img = guard(lens_region)(f, reader, windows)
318
+ return summary_md(result), result, maps, img
319
+
320
+ samples = [(s["title"], s["id"]) for s in inklens.load_samples()["samples"]]
321
+ with gr.Blocks(title="Ink Lens") as demo:
322
+ gr.Markdown(INTRO)
323
+ with gr.Row():
324
+ with gr.Column(scale=2, min_width=300):
325
+ with gr.Tab("Public sample"):
326
+ sid = gr.Dropdown(samples, value=samples[0][1], label="Sample")
327
+ size = gr.Slider(128, 640, value=640, step=64, label="Region side (px at 9.4 um)")
328
+ run_s = gr.Button("Run Ink Lens", variant="primary")
329
+ with gr.Tab("Your region (.npz)"):
330
+ up = gr.File(label="region.npz (array 'volume', uint8, layers first)", file_types=[".npz"],
331
+ type="filepath")
332
+ run_u = gr.Button("Run Ink Lens", variant="primary")
333
+ reader = gr.Radio(list(engine.READER_CHOICES), value="d9v2", label="Reader")
334
+ windows = gr.Radio([3, 1], value=3, label="Depth windows")
335
+ with gr.Accordion("For agents and scripts", open=False):
336
+ gr.Markdown(AGENTS)
337
+ with gr.Accordion("Connect your tool", open=False):
338
+ # The data's URLs and ready snippets, made by python -m kit spaceconnect render from connect.json
339
+ gr.HTML((HERE / "connect.html").read_text() if (HERE / "connect.html").exists() else "")
340
+ with gr.Column(scale=3, min_width=320):
341
+ img = gr.Image(label="Middle CT layer, kept ink in amber", type="numpy", format="png")
342
+ md = gr.Markdown("Choose a sample or upload a region, then run.")
343
+ res = gr.JSON(label="Result")
344
+ maps = gr.File(label="Maps (.npz: forward, reverse, kept)")
345
+ outs = [md, res, maps, img]
346
+ run_s.click(page_sample, [sid, size, reader, windows], outs, api_visibility="private",
347
+ concurrency_id="gpu", concurrency_limit=2)
348
+ run_u.click(page_upload, [up, reader, windows], outs, api_visibility="private", concurrency_id="gpu",
349
+ concurrency_limit=2)
350
+ with gr.Row(visible=False):
351
+ a_file = gr.File(type="filepath", file_types=[".npz"], label="volume_npz")
352
+ a_reader, a_windows = gr.Textbox("d9v2", label="reader"), gr.Number(3, precision=0, label="windows")
353
+ a_sid, a_size = gr.Textbox("0841-w00", label="sample_id"), gr.Number(640, precision=0, label="size")
354
+ a_h, a_w = gr.Number(1024, precision=0, label="height"), gr.Number(1024, precision=0, label="width")
355
+ a_json, a_maps, a_img, a_info = gr.JSON(), gr.File(), gr.Image(type="numpy", format="png"), gr.JSON()
356
+ btns = [gr.Button() for _ in range(4)]
357
+ for btn, fn, ins, o, conc in (
358
+ (btns[0], lens_region, [a_file, a_reader, a_windows], [a_json, a_maps, a_img], "gpu"),
359
+ (btns[1], lens_sample, [a_sid, a_size, a_reader, a_windows], [a_json, a_maps, a_img], "gpu"),
360
+ (btns[2], list_samples, [], a_info, None),
361
+ (btns[3], estimate, [a_h, a_w, a_windows, a_reader], a_info, None)):
362
+ btn.click(guard(fn), ins, o, api_name=fn.__name__, api_description=fn.__doc__.split("\n\n")[0],
363
+ concurrency_id=conc, concurrency_limit=2 if conc else 8)
364
+ gr.HTML('<footer style="opacity:.7;font-size:.85em">Built by Chase Hendrick · readers by TAUIL-Abd-Elilah and '
365
+ f'the Vesuvius Challenge · data by the Vesuvius Challenge (CC BY-NC 4.0) · Ink Lens {engine.VERSION}'
366
+ '</footer>')
367
+ return demo
368
+
369
+
370
+ if __name__ == "__main__":
371
+ startup()
372
+ build_demo().queue(max_size=128, default_concurrency_limit=4).launch(
373
+ mcp_server=True, max_file_size=f"{MAX_UPLOAD_BYTES >> 20}mb", allowed_paths=[str(OUT)])
bridge.py ADDED
@@ -0,0 +1,116 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Ink Lens: a minimal client for the VC3D agent bridge (JSON-RPC 2.0, one JSON message per line, over the local
2
+ socket VC3D opens with --agent-bridge). Standard library only.
3
+
4
+ Protocol and discovery as in villa main 8aa507c12, volume-cartographer/apps/VC3D/agent_bridge/SPEC.md: VC3D writes
5
+ ~/.vc3d/agent_bridge/<pid>.json with {pid, name, path, startedAt}; clients skip records whose process is gone and take
6
+ the newest live one. Methods Ink Lens uses: state.get, segments.list, canvas.get_cursor_volume_point,
7
+ points.save_json, points.load_json and viewer.center_on_point (rpc_description.json).
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import itertools
13
+ import json
14
+ import os
15
+ import socket
16
+ from pathlib import Path
17
+
18
+ REGISTRY = Path.home() / ".vc3d" / "agent_bridge"
19
+
20
+
21
+ class BridgeError(RuntimeError):
22
+ """No bridge, or the bridge answered with an error."""
23
+
24
+
25
+ def _alive(pid):
26
+ try:
27
+ os.kill(int(pid), 0)
28
+ except (OSError, ValueError, TypeError):
29
+ return False
30
+ return True
31
+
32
+
33
+ def discover(name=None, registry=REGISTRY):
34
+ """The socket path of a live bridge: the one called `name`, else the newest. A path given as `name` is used as
35
+ it is."""
36
+ if name and ("/" in name or name.endswith(".sock")):
37
+ return name
38
+ recs = []
39
+ for f in sorted(Path(registry).glob("*.json")) if Path(registry).is_dir() else []:
40
+ try:
41
+ r = json.loads(f.read_text())
42
+ except (OSError, json.JSONDecodeError):
43
+ continue
44
+ if not isinstance(r, dict) or not r.get("path") or not _alive(r.get("pid")):
45
+ continue
46
+ if name and r.get("name") != name:
47
+ continue
48
+ recs.append(r)
49
+ if not recs:
50
+ raise BridgeError("no live VC3D agent bridge found" + (f" named {name!r}" if name else "") +
51
+ f" in {registry}; start VC3D with --agent-bridge")
52
+ return max(recs, key=lambda r: r.get("startedAt", 0))["path"]
53
+
54
+
55
+ class Bridge:
56
+ def __init__(self, path, timeout=30.0):
57
+ self.path = path
58
+ self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
59
+ self.sock.settimeout(timeout)
60
+ try:
61
+ self.sock.connect(path)
62
+ except OSError as exc:
63
+ raise BridgeError(f"cannot connect to the VC3D bridge at {path}: {exc}") from None
64
+ self.file = self.sock.makefile("rb")
65
+ self.ids = itertools.count(1)
66
+
67
+ def call(self, method, params=None):
68
+ mid = next(self.ids)
69
+ req = {"jsonrpc": "2.0", "id": mid, "method": method}
70
+ if params is not None:
71
+ req["params"] = params
72
+ self.sock.sendall((json.dumps(req) + "\n").encode("utf-8"))
73
+ while True:
74
+ line = self.file.readline()
75
+ if not line:
76
+ raise BridgeError(f"the bridge closed the connection during {method}")
77
+ msg = json.loads(line)
78
+ if msg.get("id") != mid: # a notification or another client's deferred answer
79
+ continue
80
+ if "error" in msg:
81
+ e = msg["error"]
82
+ raise BridgeError(f"{method}: [{e.get('code')}] {e.get('message')} {e.get('data') or ''}".strip())
83
+ return msg.get("result")
84
+
85
+ def close(self):
86
+ try:
87
+ self.file.close()
88
+ self.sock.close()
89
+ except OSError:
90
+ pass
91
+
92
+ def __enter__(self):
93
+ return self
94
+
95
+ def __exit__(self, *exc):
96
+ self.close()
97
+ return False
98
+
99
+
100
+ def active_segment(br):
101
+ """{id, path} of VC3D's active segment, or a BridgeError."""
102
+ segs = br.call("segments.list", {"onlyLoaded": True}).get("segments", [])
103
+ act = [s for s in segs if s.get("active")]
104
+ if not act:
105
+ raise BridgeError("VC3D has no active segment; open one first")
106
+ if not act[0].get("path"):
107
+ raise BridgeError(f"VC3D's active segment {act[0].get('id')} has no folder on disk")
108
+ return act[0]
109
+
110
+
111
+ def cursor_point(br, viewer=None):
112
+ res = br.call("canvas.get_cursor_volume_point", {"viewer": viewer} if viewer else {})
113
+ p = res.get("volumePoint") if isinstance(res, dict) else None
114
+ if not isinstance(p, dict):
115
+ raise BridgeError(f"canvas.get_cursor_volume_point returned no volumePoint: {res!r}")
116
+ return [float(p["x"]), float(p["y"]), float(p["z"])]
connect.html ADDED
@@ -0,0 +1,85 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ <section class="scc" id="connect" aria-label="Connect your tool"><style>.scc{--a:var(--scc-accent,#4ea8de);color:inherit;font:inherit;line-height:1.5;max-width:60rem}
2
+ .scc h2{font-size:1.15em;margin:.2em 0 .3em}.scc h3{font-size:1em;margin:0 0 .2em}
3
+ .scc p{margin:.3em 0}.scc a{color:var(--a)}
4
+ .scc .scc-src{border:1px solid color-mix(in srgb,currentColor 18%,transparent);border-radius:10px;padding:.7em .9em;margin:.7em 0;background:color-mix(in srgb,currentColor 4%,transparent)}
5
+ .scc .scc-meta{font-size:.85em;opacity:.8}
6
+ .scc details{border-top:1px solid color-mix(in srgb,currentColor 12%,transparent);padding:.35em 0}
7
+ .scc summary{cursor:pointer;font-weight:600;list-style-position:inside}
8
+ .scc .scc-b{font-weight:400;font-size:.75em;padding:.05em .5em;border-radius:99px;margin-left:.5em;border:1px solid currentColor;opacity:.75;white-space:nowrap}
9
+ .scc .scc-b.ok{color:#3fb37f}.scc .scc-b.src{color:var(--a)}.scc .scc-b.warn{color:#e0a030}
10
+ .scc .scc-code{position:relative;margin:.4em 0 .2em}
11
+ .scc pre{margin:0;padding:.7em .8em;border-radius:8px;overflow:auto;font-size:.82em;background:color-mix(in srgb,currentColor 9%,transparent);white-space:pre}
12
+ .scc code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
13
+ .scc button.scc-copy{all:unset;box-sizing:border-box;position:absolute;top:.35em;right:.35em;font-size:.75em;line-height:1.4;padding:.1em .6em;border-radius:6px;border:1px solid color-mix(in srgb,currentColor 30%,transparent);background:color-mix(in srgb,currentColor 8%,transparent);color:inherit;cursor:pointer}
14
+ .scc button.scc-copy:hover{border-color:var(--a)}
15
+ .scc .scc-url{position:relative}.scc .scc-url pre{padding-right:4.5em;white-space:pre-wrap;word-break:break-all}
16
+ .scc .scc-go{display:inline-block;margin:.3em 0;padding:.25em .8em;border-radius:6px;border:1px solid var(--a);text-decoration:none}
17
+ .scc footer{font-size:.8em;opacity:.75;margin-top:.6em}</style>
18
+ <h2>Connect your tool</h2>
19
+ <p>The sample segments Ink Lens reads are open data, and each one reads straight from its URL in your own tool. The page is also an API and an MCP server once it is deployed.</p>
20
+ <div class="scc-src" id="connect-layers"><h3>Sample layers, PHerc0841 w00 (9.366 um surface volume)</h3>
21
+ <p class="scc-meta">CC BY-NC 4.0 (Vesuvius Challenge open data) · <a href="https://scrollprize.org/data_browser/PHerc0841" target="_blank" rel="noopener">browse</a></p>
22
+ <div class="scc-url"><button type="button" class="scc-copy" data-testid="connect-copy" onclick="navigator.clipboard&&navigator.clipboard.writeText(this.parentNode.querySelector('code').innerText).then(()=>{this.textContent='Copied';setTimeout(()=>this.textContent='Copy',1200)})">Copy</button><pre><code>https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr</code></pre></div>
23
+ <details><summary>Python (zarr)<span class="scc-b ok">tested 2026-10-24</span></summary>
24
+ <div class="scc-code"><button type="button" class="scc-copy" data-testid="connect-copy" onclick="navigator.clipboard&&navigator.clipboard.writeText(this.parentNode.querySelector('code').innerText).then(()=>{this.textContent='Copied';setTimeout(()=>this.textContent='Copy',1200)})">Copy</button><pre><code># pip install &quot;zarr&gt;=3&quot; fsspec aiohttp
25
+ import zarr
26
+
27
+ root = zarr.open_group(&quot;https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr&quot;, mode=&quot;r&quot;) # OME-Zarr, zarr v2
28
+ a = root[&quot;0&quot;] # level 0 is full resolution; level L is 2**L times coarser
29
+ print(a.shape, a.dtype, a.chunks)
30
+ block = a[0:64, 2800:2864, 2900:2964] # (z, y, x); reads only the chunks it touches</code></pre></div></details>
31
+ <details><summary>villa&#x27;s vesuvius package<span class="scc-b ok">tested 2026-10-24</span></summary>
32
+ <div class="scc-code"><button type="button" class="scc-copy" data-testid="connect-copy" onclick="navigator.clipboard&&navigator.clipboard.writeText(this.parentNode.querySelector('code').innerText).then(()=>{this.textContent='Copied';setTimeout(()=>this.textContent='Copy',1200)})">Copy</button><pre><code># pip install &quot;vesuvius[volume-only]&quot;
33
+ from vesuvius import Volume
34
+
35
+ v = Volume(type=&quot;zarr&quot;, path=&quot;https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr/0&quot;) # one pyramid level
36
+ block = v[0:64, 2800:2864, 2900:2964]</code></pre></div></details>
37
+ <details><summary>curl<span class="scc-b ok">tested 2026-10-24</span></summary>
38
+ <div class="scc-code"><button type="button" class="scc-copy" data-testid="connect-copy" onclick="navigator.clipboard&&navigator.clipboard.writeText(this.parentNode.querySelector('code').innerText).then(()=>{this.textContent='Copied';setTimeout(()=>this.textContent='Copy',1200)})">Copy</button><pre><code>curl -s https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr/.zattrs # OME multiscales metadata
39
+ curl -s https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr/0/.zarray # one level: shape, chunks, dtype, codec</code></pre></div></details>
40
+ </div>
41
+ <div class="scc-src" id="connect-segment"><h3>Its surface (tifxyz)</h3>
42
+ <p class="scc-meta">CC BY-NC 4.0 (Vesuvius Challenge open data)</p>
43
+ <div class="scc-url"><button type="button" class="scc-copy" data-testid="connect-copy" onclick="navigator.clipboard&&navigator.clipboard.writeText(this.parentNode.querySelector('code').innerText).then(()=>{this.textContent='Copied';setTimeout(()=>this.textContent='Copy',1200)})">Copy</button><pre><code>https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/mesh/20260220213127-on-20250821151531-9.366um.tifxyz</code></pre></div>
44
+ <details><summary>Python (numpy, tifffile)<span class="scc-b ok">tested 2026-10-24</span></summary>
45
+ <div class="scc-code"><button type="button" class="scc-copy" data-testid="connect-copy" onclick="navigator.clipboard&&navigator.clipboard.writeText(this.parentNode.querySelector('code').innerText).then(()=>{this.textContent='Copied';setTimeout(()=>this.textContent='Copy',1200)})">Copy</button><pre><code># pip install numpy tifffile
46
+ import io, json, urllib.request
47
+ import numpy as np, tifffile
48
+
49
+ T = &quot;https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/mesh/20260220213127-on-20250821151531-9.366um.tifxyz&quot;
50
+ meta = json.load(urllib.request.urlopen(T + &quot;/meta.json&quot;)) # scale, bbox, format
51
+ get = lambda c: tifffile.imread(io.BytesIO(urllib.request.urlopen(f&quot;{T}/{c}.tif&quot;).read()))
52
+ xyz = np.stack([get(c) for c in &quot;xyz&quot;], -1) # xyz[i, j] = (x, y, z) in scan voxels; -1 = no surface</code></pre></div></details>
53
+ </div>
54
+ <div class="scc-src" id="connect-api"><h3>Call Ink Lens from code or an agent</h3>
55
+ <p class="scc-meta">Code Apache 2.0; d9v2 MIT; scans CC BY-NC 4.0 · Not deployed yet; these calls work once it is. Model output, not a reading.</p>
56
+ <div class="scc-url"><button type="button" class="scc-copy" data-testid="connect-copy" onclick="navigator.clipboard&&navigator.clipboard.writeText(this.parentNode.querySelector('code').innerText).then(()=>{this.textContent='Copied';setTimeout(()=>this.textContent='Copy',1200)})">Copy</button><pre><code>https://huggingface.co/spaces/SharpMeow/ink-lens</code></pre></div>
57
+ <details><summary>Python /lens_sample<span class="scc-b warn">not deployed yet</span></summary>
58
+ <div class="scc-code"><button type="button" class="scc-copy" data-testid="connect-copy" onclick="navigator.clipboard&&navigator.clipboard.writeText(this.parentNode.querySelector('code').innerText).then(()=>{this.textContent='Copied';setTimeout(()=>this.textContent='Copy',1200)})">Copy</button><pre><code># pip install gradio_client
59
+ from gradio_client import Client
60
+
61
+ client = Client(&quot;SharpMeow/ink-lens&quot;)
62
+ result = client.predict(sample_id=&quot;0841-w00&quot;, size=640, reader=&quot;d9v2&quot;, windows=3, api_name=&quot;/lens_sample&quot;)</code></pre></div></details>
63
+ <details><summary>Python /list_samples<span class="scc-b warn">not deployed yet</span></summary>
64
+ <div class="scc-code"><button type="button" class="scc-copy" data-testid="connect-copy" onclick="navigator.clipboard&&navigator.clipboard.writeText(this.parentNode.querySelector('code').innerText).then(()=>{this.textContent='Copied';setTimeout(()=>this.textContent='Copy',1200)})">Copy</button><pre><code># pip install gradio_client
65
+ from gradio_client import Client
66
+
67
+ client = Client(&quot;SharpMeow/ink-lens&quot;)
68
+ result = client.predict(api_name=&quot;/list_samples&quot;)</code></pre></div></details>
69
+ <details><summary>curl /lens_sample<span class="scc-b warn">not deployed yet</span></summary>
70
+ <div class="scc-code"><button type="button" class="scc-copy" data-testid="connect-copy" onclick="navigator.clipboard&&navigator.clipboard.writeText(this.parentNode.querySelector('code').innerText).then(()=>{this.textContent='Copied';setTimeout(()=>this.textContent='Copy',1200)})">Copy</button><pre><code>URL=https://sharpmeow-ink-lens.hf.space
71
+ EVENT=$(curl -s -X POST $URL/gradio_api/call/lens_sample -H &#x27;Content-Type: application/json&#x27; \
72
+ -d &#x27;{&quot;data&quot;: [&quot;0841-w00&quot;, 640, &quot;d9v2&quot;, 3]}&#x27; | python3 -c &#x27;import json,sys; print(json.load(sys.stdin)[&quot;event_id&quot;])&#x27;)
73
+ curl -sN $URL/gradio_api/call/lens_sample/$EVENT</code></pre></div></details>
74
+ <details><summary>MCP (Claude, Cursor and other agents)<span class="scc-b warn">not deployed yet</span></summary>
75
+ <div class="scc-code"><button type="button" class="scc-copy" data-testid="connect-copy" onclick="navigator.clipboard&&navigator.clipboard.writeText(this.parentNode.querySelector('code').innerText).then(()=>{this.textContent='Copied';setTimeout(()=>this.textContent='Copy',1200)})">Copy</button><pre><code>{
76
+ &quot;mcpServers&quot;: {
77
+ &quot;ink-lens&quot;: {
78
+ &quot;url&quot;: &quot;https://sharpmeow-ink-lens.hf.space/gradio_api/mcp/sse&quot;
79
+ }
80
+ }
81
+ }
82
+
83
+ Tool list: https://sharpmeow-ink-lens.hf.space/gradio_api/mcp/schema</code></pre></div></details>
84
+ </div>
85
+ <footer>Machine-readable: <a href="https://huggingface.co/spaces/SharpMeow/ink-lens/blob/main/connect.json" target="_blank" rel="noopener">connect.json</a> and <a href="https://huggingface.co/spaces/SharpMeow/ink-lens/blob/main/CONNECT.md" target="_blank" rel="noopener">CONNECT.md</a>. Checked 2026-10-24. "Tested" means the snippet ran against this public data on that date. Scan data keeps its own license (the Vesuvius Challenge open data is CC BY-NC 4.0).</footer></section>
connect.json ADDED
@@ -0,0 +1,64 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "schema": "space-connect/1",
3
+ "space": "SharpMeow/ink-lens",
4
+ "title": "Ink Lens",
5
+ "checked": "2026-10-24",
6
+ "intro": "The sample segments Ink Lens reads are open data, and each one reads straight from its URL in your own tool. The page is also an API and an MCP server once it is deployed.",
7
+ "sources": [
8
+ {
9
+ "id": "layers",
10
+ "title": "Sample layers, PHerc0841 w00 (9.366 um surface volume)",
11
+ "kind": "ome-zarr",
12
+ "url": "https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr",
13
+ "zarr_format": 2,
14
+ "example": {
15
+ "level": "0",
16
+ "start": [
17
+ 0,
18
+ 2800,
19
+ 2900
20
+ ]
21
+ },
22
+ "tools": [
23
+ "zarr",
24
+ "vesuvius",
25
+ "curl"
26
+ ],
27
+ "license": "CC BY-NC 4.0 (Vesuvius Challenge open data)",
28
+ "browse": "https://scrollprize.org/data_browser/PHerc0841"
29
+ },
30
+ {
31
+ "id": "segment",
32
+ "title": "Its surface (tifxyz)",
33
+ "kind": "tifxyz",
34
+ "url": "https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/mesh/20260220213127-on-20250821151531-9.366um.tifxyz",
35
+ "license": "CC BY-NC 4.0 (Vesuvius Challenge open data)"
36
+ },
37
+ {
38
+ "id": "api",
39
+ "title": "Call Ink Lens from code or an agent",
40
+ "kind": "gradio-api",
41
+ "url": "https://huggingface.co/spaces/SharpMeow/ink-lens",
42
+ "space": "SharpMeow/ink-lens",
43
+ "host": "https://sharpmeow-ink-lens.hf.space",
44
+ "status": "not-deployed",
45
+ "endpoints": [
46
+ {
47
+ "api": "/lens_sample",
48
+ "args": {
49
+ "sample_id": "0841-w00",
50
+ "size": 640,
51
+ "reader": "d9v2",
52
+ "windows": 3
53
+ }
54
+ },
55
+ {
56
+ "api": "/list_samples",
57
+ "args": {}
58
+ }
59
+ ],
60
+ "license": "Code Apache 2.0; d9v2 MIT; scans CC BY-NC 4.0",
61
+ "note": "Not deployed yet; these calls work once it is. Model output, not a reading."
62
+ }
63
+ ]
64
+ }
engine.py ADDED
@@ -0,0 +1,541 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Ink Lens engine: an openly licensed 9 um ink model on one region, three depth windows, both depth orders.
2
+
3
+ The model is built by villa's own flat ink inference (vesuvius.ink_detection.inference.infer.configure_model, at the
4
+ commit pinned in VILLA_COMMIT) from a checkpoint downloaded by URL and refused unless its SHA-256 matches. The patch
5
+ schedule (128 px patches, stride 64, the last flush with the end), the layer choice (center crop, reversed for the
6
+ control), villa's per-patch robust normalisation and the Hann blend are villa's; two things differ from villa's
7
+ command line, both to fit one ZeroGPU call:
8
+
9
+ 1. the robust normalisation runs batched on the device (robust_torch), checked against villa's CPU function
10
+ (robust_np is a line-for-line copy of villa's normalize_robust for a patch with no mask; tests/test_inklens.py
11
+ compares them, and compares robust_np with villa's own function when villa is importable);
12
+ 2. the maps stay float (0 to 1) instead of villa's uint8 encoding, so the control-set threshold is not quantised.
13
+
14
+ run_reference() is the same algorithm in numpy with any predict function: the tests run it with a stand-in model,
15
+ and the torch path is checked against it.
16
+
17
+ python3 engine.py estimate 1024 1024 --windows 3 patches and the GPU seconds one call asks for
18
+ python3 engine.py fetch d9v2 download and check a checkpoint into the cache
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import hashlib
24
+ import math
25
+ import os
26
+ import platform
27
+ import shutil
28
+ import subprocess
29
+ import sys
30
+ import tarfile
31
+ import tempfile
32
+ import time
33
+ import urllib.request
34
+ from pathlib import Path
35
+
36
+ VERSION = "0.1.0"
37
+ VILLA_REPO = "https://github.com/ScrollPrize/villa.git"
38
+ VILLA_TARBALL = "https://codeload.github.com/ScrollPrize/villa/tar.gz/{commit}"
39
+ VILLA_COMMIT = "8aa507c1215f1fa8758f13d0538f7af9710e02d7" # ScrollPrize/villa main, 18 Oct 2026
40
+ CACHE = Path(os.environ.get("INKLENS_CACHE") or Path(tempfile.gettempdir()) / "ink-lens")
41
+ USER_AGENT = f"ink-lens/{VERSION}"
42
+
43
+ # Openly licensed 9 um readers that drop into villa's flat inference. Public held-out scores (PHerc0841, crops with a
44
+ # 64 px inner edge, raw / reversed AUC) are in docs/results.json; d9v2 is the default.
45
+ READERS = {
46
+ "d9v2": {
47
+ "title": "d9v2 (TAUIL-Abd-Elilah, MIT)",
48
+ "url": "https://github.com/TAUIL-Abd-Elilah/pherc0826-first-letters-search/releases/download/v1.0/"
49
+ "d9v2_ft-012000.pth",
50
+ "file": "d9v2_ft-012000.pth",
51
+ "sha256": "50d2ad0ef7690a6a422640804d38f01409da8bc96cfc1ab72f45324a4a18f966",
52
+ "license": "MIT",
53
+ "source": "https://github.com/TAUIL-Abd-Elilah/pherc0826-first-letters-search",
54
+ "held_out": "PHerc0841 w00, ag896, ag405 (its reader/test.txt)",
55
+ },
56
+ "ink_9um": {
57
+ "title": "ink_9um seed 42 step 75,000 (Vesuvius Challenge, MIT)",
58
+ "url": "https://huggingface.co/scrollprize/ink_9um/resolve/main/hybrid_3d2d-seed42/step-075000.pth",
59
+ "file": "ink_9um-seed42-step-075000.pth",
60
+ "sha256": "e635558ae6a1a807a7e5ec1e83adfd45bc3c0ac53883ea43f1d4e085d62a9cab",
61
+ "license": "MIT",
62
+ "source": "https://huggingface.co/scrollprize/ink_9um",
63
+ "held_out": "PHerc0841 (its label dataset has no PHerc0841 segment)",
64
+ },
65
+ }
66
+ READER_CHOICES = ("d9v2", "ink_9um", "both")
67
+
68
+ PATCH, STRIDE, DEPTH = 128, 64, 17
69
+ STACK = 21 # layers kept around the middle: the three windows below fit in it
70
+ WINDOW_OFFSETS = {1: (2,), 3: (0, 2, 4)} # window starts inside the 21-layer stack (2 is villa's own center)
71
+ BATCH = 64
72
+ MIN_SIDE, MAX_SIDE = PATCH, 2048
73
+ MIN_LAYERS, MAX_LAYERS = DEPTH, 65
74
+ # One call's duration: a fixed start plus a per-patch allowance, capped. The per-patch figure is an estimate (3 to
75
+ # 6 ms per patch with batched fp16 and normalisation on the GPU) with a margin; every receipt records the measured
76
+ # seconds so the first calls calibrate it.
77
+ GPU_START_S, GPU_PER_PATCH_S, GPU_MAX_S = 4.0, 0.012, 40
78
+
79
+
80
+ class EngineError(ValueError):
81
+ """A request the engine refuses; the message says why."""
82
+
83
+
84
+ # ---------------------------------------------------------------- sizing
85
+
86
+ def positions(length, patch=PATCH, stride=STRIDE):
87
+ """Patch starts along one axis, the last flush with the end (villa's _sliding_positions_1d)."""
88
+ if length <= patch:
89
+ return [0]
90
+ out = list(range(0, length - patch + 1, max(1, stride)))
91
+ if out[-1] != length - patch:
92
+ out.append(length - patch)
93
+ return out
94
+
95
+
96
+ def readers_of(choice):
97
+ if choice not in READER_CHOICES:
98
+ raise EngineError(f"reader {choice!r}: choose one of {', '.join(READER_CHOICES)}")
99
+ return ("d9v2", "ink_9um") if choice == "both" else (choice,)
100
+
101
+
102
+ def patches(height, width, windows=3, reader="d9v2"):
103
+ """Patches one call runs: per pass the patch grid, times windows, times two depth orders, times readers."""
104
+ if windows not in WINDOW_OFFSETS:
105
+ raise EngineError(f"windows {windows}: use 1 or 3")
106
+ return len(positions(height)) * len(positions(width)) * windows * 2 * len(readers_of(reader))
107
+
108
+
109
+ def gpu_seconds(n_patches):
110
+ """The duration a call asks ZeroGPU for; refuses a call that would need more than GPU_MAX_S."""
111
+ need = math.ceil(GPU_START_S + n_patches * GPU_PER_PATCH_S)
112
+ if need > GPU_MAX_S:
113
+ raise EngineError(f"{n_patches} patches need about {need} GPU seconds, more than the {GPU_MAX_S} s one call "
114
+ "may ask for; use a smaller region, one depth window, or local mode")
115
+ return need
116
+
117
+
118
+ def estimate(height, width, windows=3, reader="d9v2"):
119
+ check_side(height, width)
120
+ n = patches(height, width, windows, reader)
121
+ out = {"height": int(height), "width": int(width), "windows": int(windows), "reader": reader, "patches": n}
122
+ try:
123
+ out["gpu_seconds_requested"] = gpu_seconds(n)
124
+ except EngineError as exc:
125
+ out["gpu_seconds_requested"] = None
126
+ out["refused"] = str(exc)
127
+ return out
128
+
129
+
130
+ def check_side(height, width):
131
+ for name, side in (("height", height), ("width", width)):
132
+ if not MIN_SIDE <= int(side) <= MAX_SIDE:
133
+ raise EngineError(f"{name} {side} px: a region is {MIN_SIDE} to {MAX_SIDE} px a side at 9.6 um")
134
+
135
+
136
+ def check_volume(volume, windows=3):
137
+ """Refuse anything but a uint8 (layers, rows, columns) region of the right size and depth."""
138
+ import numpy as np
139
+ a = np.asarray(volume)
140
+ if a.ndim != 3:
141
+ raise EngineError(f"a surface volume has 3 axes (layers, rows, columns), this one has {a.ndim}")
142
+ if a.dtype != np.uint8:
143
+ raise EngineError(f"type {a.dtype}: the engine takes uint8 (volio.to_uint8 converts uint16)")
144
+ L, H, W = a.shape
145
+ need = STACK if windows == 3 else DEPTH
146
+ if not need <= L <= MAX_LAYERS:
147
+ raise EngineError(f"{L} layers: {windows} depth window{'s' if windows > 1 else ''} need{'' if windows > 1 else 's'} "
148
+ f"{need} to {MAX_LAYERS} layers, layers first")
149
+ check_side(H, W)
150
+ if not a.any():
151
+ raise EngineError("the region is all zero (off the segment, or a hole in it)")
152
+ return L, H, W
153
+
154
+
155
+ def stack(volume, windows=3):
156
+ """The middle STACK layers (or all, if fewer), as villa's center crop chooses them (upper center when uneven)."""
157
+ L = volume.shape[0]
158
+ n = min(L, STACK)
159
+ start = L // 2 - n // 2
160
+ return volume[start:start + n]
161
+
162
+
163
+ def window_indices(n_layers, offset, direction):
164
+ """Layer indices of one 17-layer window inside the stack; reversed for the control."""
165
+ if n_layers < STACK: # one window, centered (villa's own choice)
166
+ start = n_layers // 2 - DEPTH // 2
167
+ else:
168
+ start = offset
169
+ idx = list(range(start, start + DEPTH))
170
+ return idx[::-1] if direction == "reverse" else idx
171
+
172
+
173
+ def passes(windows):
174
+ """(offset, direction) for every pass of one reader: each window in both orders."""
175
+ return [(o, d) for o in WINDOW_OFFSETS[windows] for d in ("forward", "reverse")]
176
+
177
+
178
+ # ---------------------------------------------------------------- villa's normalisation, numpy and torch
179
+
180
+ def robust_np(patch):
181
+ """villa's normalize_robust (vesuvius/image_proc/intensity/normalization.py at VILLA_COMMIT) with no mask:
182
+ clip to the 1st and 99th percentiles, subtract the median, divide by 1.4826 x MAD, with villa's fallbacks."""
183
+ import numpy as np
184
+ arr = np.asarray(patch).astype(np.float32, copy=True)
185
+ valid = arr.reshape(-1)
186
+ if valid.size == 0:
187
+ return arr
188
+ std_preclip = float(np.std(valid))
189
+ lower = float(np.percentile(valid, 1.0))
190
+ upper = float(np.percentile(valid, 99.0))
191
+ np.clip(arr, lower, upper, out=arr)
192
+ valid = arr.reshape(-1)
193
+ median = float(np.median(valid))
194
+ mad = float(np.median(np.abs(valid - median)))
195
+ scaled = 1.4826 * mad
196
+ if not np.isfinite(scaled) or scaled < 1e-6:
197
+ span = upper - lower
198
+ cands = []
199
+ if np.isfinite(std_preclip):
200
+ cands.append(abs(std_preclip))
201
+ if np.isfinite(span):
202
+ cands.append(abs(span) / 2.0)
203
+ scaled = next((c for c in cands if c >= 1e-6), None)
204
+ if scaled is None or not np.isfinite(scaled):
205
+ scaled = 1.0
206
+ arr -= median
207
+ arr /= scaled
208
+ np.nan_to_num(arr, copy=False, nan=0.0, posinf=0.0, neginf=0.0)
209
+ return arr
210
+
211
+
212
+ def _lerp_sorted(torch, s, q):
213
+ """numpy's linear percentile of each row of an already sorted (B, N) tensor."""
214
+ n = s.shape[1]
215
+ pos = q * (n - 1)
216
+ lo = int(math.floor(pos))
217
+ hi = min(lo + 1, n - 1)
218
+ frac = pos - lo
219
+ return s[:, lo] + (s[:, hi] - s[:, lo]) * frac
220
+
221
+
222
+ def robust_torch(x):
223
+ """robust_np on every row of a (B, N) float32 tensor at once, on its device."""
224
+ import torch
225
+ x = x.float()
226
+ s, _ = torch.sort(x, dim=1)
227
+ std_pre = x.std(dim=1, unbiased=False)
228
+ lower, upper = _lerp_sorted(torch, s, 0.01), _lerp_sorted(torch, s, 0.99)
229
+ x = torch.maximum(torch.minimum(x, upper[:, None]), lower[:, None])
230
+ s = torch.maximum(torch.minimum(s, upper[:, None]), lower[:, None])
231
+ median = _lerp_sorted(torch, s, 0.5)
232
+ dev, _ = torch.sort((x - median[:, None]).abs(), dim=1)
233
+ scaled = 1.4826 * _lerp_sorted(torch, dev, 0.5)
234
+ half_span = (upper - lower).abs() / 2.0
235
+ ok = torch.isfinite(scaled) & (scaled >= 1e-6)
236
+ fb = torch.where(torch.isfinite(std_pre) & (std_pre.abs() >= 1e-6), std_pre.abs(),
237
+ torch.where(torch.isfinite(half_span) & (half_span >= 1e-6), half_span,
238
+ torch.ones_like(half_span)))
239
+ scaled = torch.where(ok, scaled, fb)
240
+ out = (x - median[:, None]) / scaled[:, None]
241
+ return torch.nan_to_num(out, nan=0.0, posinf=0.0, neginf=0.0)
242
+
243
+
244
+ def hann2d():
245
+ """villa's floored Hann blend map (compute_importance_map_2d, mode hann), in numpy."""
246
+ import numpy as np
247
+ w1 = np.hanning(PATCH).astype(np.float32) # numpy's hanning is the symmetric (periodic=False) window
248
+ w = np.outer(w1, w1)
249
+ w /= max(float(w.max()), float(np.finfo(np.float32).eps))
250
+ return np.maximum(w, 0.001).astype(np.float32)
251
+
252
+
253
+ # ---------------------------------------------------------------- the numpy reference
254
+
255
+ def run_reference(volume, predict, windows=3):
256
+ """The whole algorithm in numpy: predict(batch (B, 1, 17, 128, 128) float32) -> (B, 128, 128) probabilities.
257
+ Returns {"forward": F, "reverse": R} (float32, 0 to 1), each the mean over the windows."""
258
+ import numpy as np
259
+ vol = stack(np.asarray(volume), windows)
260
+ L, H, W = vol.shape
261
+ ys, xs = positions(H), positions(W)
262
+ wmap = hann2d()
263
+ maps = {"forward": [], "reverse": []}
264
+ for off, direction in passes(windows):
265
+ idx = window_indices(L, off, direction)
266
+ psum = np.zeros((H, W), np.float32)
267
+ wsum = np.zeros((H, W), np.float32)
268
+ for y0 in ys:
269
+ for x0 in xs:
270
+ raw = vol[idx, y0:y0 + PATCH, x0:x0 + PATCH]
271
+ if not raw.any():
272
+ continue
273
+ p = np.asarray(predict(robust_np(raw)[None, None]), np.float32)[0]
274
+ psum[y0:y0 + PATCH, x0:x0 + PATCH] += p * wmap
275
+ wsum[y0:y0 + PATCH, x0:x0 + PATCH] += wmap
276
+ prob = np.divide(psum, wsum, out=np.zeros_like(psum), where=wsum > 1e-6)
277
+ maps[direction].append(np.clip(prob, 0, 1))
278
+ return {d: np.mean(m, axis=0).astype(np.float32) for d, m in maps.items()}
279
+
280
+
281
+ # ---------------------------------------------------------------- downloads
282
+
283
+ def sha256_file(path, block=1 << 22):
284
+ h = hashlib.sha256()
285
+ with open(path, "rb") as fh:
286
+ for chunk in iter(lambda: fh.read(block), b""):
287
+ h.update(chunk)
288
+ return h.hexdigest()
289
+
290
+
291
+ def _download(url, dest):
292
+ dest.parent.mkdir(parents=True, exist_ok=True)
293
+ part = dest.with_name(dest.name + ".part")
294
+ req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
295
+ with urllib.request.urlopen(req, timeout=600) as resp, open(part, "wb") as out:
296
+ shutil.copyfileobj(resp, out, 1 << 20)
297
+ os.replace(part, dest)
298
+
299
+
300
+ def ensure_checkpoint(name, cache=CACHE):
301
+ """A reader's checkpoint, downloaded once and refused unless its SHA-256 matches READERS. INKLENS_<NAME> (for
302
+ example INKLENS_D9V2) may name a local copy; its SHA-256 is still checked."""
303
+ spec = READERS[name]
304
+ env = os.environ.get("INKLENS_" + name.upper())
305
+ path = Path(env).expanduser() if env else Path(cache) / "checkpoints" / spec["file"]
306
+ if not path.is_file():
307
+ if env:
308
+ raise EngineError(f"INKLENS_{name.upper()}={env} does not exist")
309
+ _download(spec["url"], path)
310
+ digest = sha256_file(path)
311
+ if digest != spec["sha256"]:
312
+ raise EngineError(f"{path} has SHA-256 {digest}, expected {spec['sha256']} for {name}; refusing it")
313
+ return path
314
+
315
+
316
+ def _git_commit(path):
317
+ try:
318
+ return subprocess.run(["git", "-C", str(path), "rev-parse", "HEAD"], capture_output=True, text=True,
319
+ check=True).stdout.strip()
320
+ except (OSError, subprocess.CalledProcessError):
321
+ return "unknown"
322
+
323
+
324
+ def _villa_tarball(tmp, commit):
325
+ root = tmp.resolve()
326
+ kept = 0
327
+ req = urllib.request.Request(VILLA_TARBALL.format(commit=commit), headers={"User-Agent": USER_AGENT})
328
+ with urllib.request.urlopen(req, timeout=600) as resp, tarfile.open(fileobj=resp, mode="r|gz") as tf:
329
+ for m in tf:
330
+ _, _, rel = m.name.partition("/")
331
+ if not rel.startswith("vesuvius/src/"):
332
+ continue
333
+ target = (root / rel).resolve()
334
+ if root not in target.parents or m.issym() or m.islnk():
335
+ continue
336
+ if m.isdir():
337
+ target.mkdir(parents=True, exist_ok=True)
338
+ elif m.isfile():
339
+ target.parent.mkdir(parents=True, exist_ok=True)
340
+ with tf.extractfile(m) as src, open(target, "wb") as out:
341
+ shutil.copyfileobj(src, out)
342
+ kept += 1
343
+ if not kept:
344
+ raise EngineError(f"the villa tarball for {commit} held no vesuvius/src files")
345
+
346
+
347
+ def ensure_villa(cache=CACHE):
348
+ """villa's vesuvius package on sys.path: VILLA_SRC (a local vesuvius/src) when set, else the pinned commit,
349
+ downloaded once (sparse git fetch, else GitHub's tarball)."""
350
+ if os.environ.get("VILLA_SRC"):
351
+ src = Path(os.environ["VILLA_SRC"]).expanduser().resolve()
352
+ info = {"source": "VILLA_SRC", "commit": _git_commit(src)}
353
+ else:
354
+ dest = Path(cache) / f"villa-{VILLA_COMMIT[:12]}"
355
+ if not (dest / "COMMIT").is_file():
356
+ tmp = dest.with_name(dest.name + ".part")
357
+ shutil.rmtree(tmp, ignore_errors=True)
358
+ tmp.mkdir(parents=True)
359
+ try:
360
+ git = ["git", "-C", str(tmp)]
361
+ for cmd in (["init", "-q"], ["remote", "add", "origin", VILLA_REPO],
362
+ ["sparse-checkout", "set", "vesuvius/src"],
363
+ ["fetch", "-q", "--depth", "1", "--filter=blob:none", "origin", VILLA_COMMIT],
364
+ ["checkout", "-q", "FETCH_HEAD"]):
365
+ subprocess.run(git + cmd, capture_output=True, text=True, check=True, timeout=600)
366
+ except (OSError, subprocess.SubprocessError):
367
+ shutil.rmtree(tmp, ignore_errors=True)
368
+ tmp.mkdir(parents=True)
369
+ _villa_tarball(tmp, VILLA_COMMIT)
370
+ (tmp / "COMMIT").write_text(VILLA_COMMIT + "\n")
371
+ shutil.rmtree(dest, ignore_errors=True)
372
+ os.replace(tmp, dest)
373
+ src = dest / "vesuvius" / "src"
374
+ info = {"source": "pinned download", "commit": (dest / "COMMIT").read_text().strip()}
375
+ if not (src / "vesuvius" / "ink_detection" / "inference" / "infer.py").is_file():
376
+ raise EngineError(f"{src} holds no villa vesuvius package")
377
+ if str(src) not in sys.path:
378
+ sys.path.insert(0, str(src))
379
+ info["pinned"] = VILLA_COMMIT
380
+ return info
381
+
382
+
383
+ def load_villa_model(name, cache=CACHE):
384
+ """(model, preprocessing, amp dtype, info) for one reader, built by villa's configure_model. The checkpoint is
385
+ opened with torch.load(weights_only=True): villa's loader allows any pickle, so it is replaced for this call."""
386
+ import argparse
387
+ import torch
388
+ villa = ensure_villa(cache)
389
+ path = ensure_checkpoint(name, cache)
390
+ from vesuvius.ink_detection.inference import infer
391
+ original = infer.load_checkpoint
392
+ infer.load_checkpoint = lambda p: torch.load(str(p), map_location="cpu", weights_only=True)
393
+ try:
394
+ cm = infer.configure_model(argparse.Namespace(checkpoint=path, amp_dtype="auto"))
395
+ finally:
396
+ infer.load_checkpoint = original
397
+ got = (int(cm.patch_size), int(cm.input_depth))
398
+ if got != (PATCH, DEPTH):
399
+ raise EngineError(f"{name} has patch and depth {got}; Ink Lens is built for {(PATCH, DEPTH)}")
400
+ if cm.preprocessing not in ("tifxyz_robust", "divide_255"):
401
+ raise EngineError(f"{name} asks for preprocessing {cm.preprocessing!r}, which Ink Lens does not run")
402
+ info = {"name": name, "sha256": READERS[name]["sha256"], "url": READERS[name]["url"],
403
+ "license": READERS[name]["license"], "preprocessing": cm.preprocessing,
404
+ "amp_on_cuda": str(cm.amp_dtype).replace("torch.", ""), "villa": villa, "loader": "weights_only=True"}
405
+ return cm.model.eval(), cm.preprocessing, cm.amp_dtype, info
406
+
407
+
408
+ # ---------------------------------------------------------------- the torch engine
409
+
410
+ def pick_device(prefer=None):
411
+ import torch
412
+ if prefer:
413
+ return torch.device(prefer)
414
+ if torch.cuda.is_available():
415
+ return torch.device("cuda")
416
+ if getattr(torch.backends, "mps", None) is not None and torch.backends.mps.is_available():
417
+ return torch.device("mps")
418
+ return torch.device("cpu")
419
+
420
+
421
+ class Engine:
422
+ """Readers loaded once; run() does one region on one device.
423
+
424
+ models: {name: (module, preprocessing, amp_dtype, info)} to use instead of downloading (the tests pass a
425
+ stand-in); otherwise every name in `readers` is loaded through villa."""
426
+
427
+ def __init__(self, readers=("d9v2",), cache=CACHE, models=None, place_on_cuda=True):
428
+ t0 = time.time()
429
+ import torch
430
+ self.torch = torch
431
+ self.models = dict(models) if models else {n: load_villa_model(n, cache) for n in readers}
432
+ if place_on_cuda and torch.cuda.is_available():
433
+ for m in self.models.values():
434
+ m[0].to("cuda")
435
+ self.startup_s = round(time.time() - t0, 1)
436
+
437
+ def describe(self):
438
+ return {"engine": f"ink-lens {VERSION}", "readers": {n: m[3] for n, m in self.models.items()},
439
+ "patch": PATCH, "stride": STRIDE, "depth": DEPTH, "stack": STACK, "blend": "hann (villa, floored)",
440
+ "batch": BATCH, "torch": self.torch.__version__}
441
+
442
+ def run(self, volume, reader="d9v2", windows=3, device=None, batch=BATCH):
443
+ """{"forward": F, "reverse": R, "per_reader": {...}, ...} for one uint8 region, float32 maps in 0 to 1."""
444
+ import numpy as np
445
+ torch = self.torch
446
+ names = readers_of(reader)
447
+ missing = [n for n in names if n not in self.models]
448
+ if missing:
449
+ raise EngineError(f"reader {', '.join(missing)} is not loaded here")
450
+ check_volume(volume, windows)
451
+ dev = pick_device(device)
452
+ t0 = time.perf_counter()
453
+ vol = stack(np.asarray(volume), windows)
454
+ L, H, W = vol.shape
455
+ stack_start = int(np.asarray(volume).shape[0] // 2 - L // 2)
456
+ vt = torch.from_numpy(np.ascontiguousarray(vol)).to(dev)
457
+ coords = [(y, x) for y in positions(H) for x in positions(W)]
458
+ wmap = torch.from_numpy(hann2d()).to(dev)
459
+ per_reader, n_patches = {}, 0
460
+ for name in names:
461
+ model, prep, amp, _ = self.models[name]
462
+ model = model.to(dev)
463
+ maps = {"forward": [], "reverse": []}
464
+ for off, direction in passes(windows):
465
+ idx = torch.tensor(window_indices(L, off, direction), device=dev)
466
+ sub = vt.index_select(0, idx)
467
+ psum = torch.zeros((H, W), dtype=torch.float32, device=dev)
468
+ wsum = torch.zeros((H, W), dtype=torch.float32, device=dev)
469
+ for b0 in range(0, len(coords), batch):
470
+ chunk = coords[b0:b0 + batch]
471
+ raw = torch.stack([sub[:, y:y + PATCH, x:x + PATCH] for y, x in chunk]) # (B, 17, 128, 128)
472
+ keep = raw.reshape(len(chunk), -1).any(dim=1) # villa skips all-zero patches, before normalising
473
+ if not bool(keep.any()):
474
+ continue
475
+ if not bool(keep.all()):
476
+ chunk = [c for c, k in zip(chunk, keep.tolist()) if k]
477
+ raw = raw[keep]
478
+ flat = raw.reshape(len(chunk), -1).float()
479
+ norm = robust_torch(flat) if prep == "tifxyz_robust" else flat / 255.0
480
+ images = norm.reshape(len(chunk), 1, DEPTH, PATCH, PATCH)
481
+ ctx = (torch.autocast("cuda", dtype=amp) if dev.type == "cuda" and amp is not None
482
+ else _null())
483
+ with torch.inference_mode(), ctx:
484
+ logits = model(images)
485
+ prob = logits.float().sigmoid()
486
+ if prob.shape[-2:] != (PATCH, PATCH):
487
+ prob = torch.nn.functional.interpolate(prob, size=(PATCH, PATCH), mode="bilinear",
488
+ align_corners=False)
489
+ prob = prob[:, 0]
490
+ for (y, x), p in zip(chunk, prob):
491
+ psum[y:y + PATCH, x:x + PATCH] += p * wmap
492
+ wsum[y:y + PATCH, x:x + PATCH] += wmap
493
+ n_patches += len(chunk)
494
+ out = torch.where(wsum > 1e-6, psum / wsum.clamp_min(1e-6), torch.zeros_like(psum)).clamp(0, 1)
495
+ maps[direction].append(out)
496
+ per_reader[name] = {d: torch.stack(m).mean(0).cpu().numpy().astype(np.float32) for d, m in maps.items()}
497
+ if dev.type == "cuda":
498
+ torch.cuda.synchronize(dev)
499
+ F = np.mean([per_reader[n]["forward"] for n in names], axis=0).astype(np.float32)
500
+ R = np.mean([per_reader[n]["reverse"] for n in names], axis=0).astype(np.float32)
501
+ name = torch.cuda.get_device_name(dev) if dev.type == "cuda" else (platform.processor() or platform.machine())
502
+ return {"forward": F, "reverse": R, "per_reader": per_reader, "readers": list(names), "windows": windows,
503
+ "window_layers": {f"{o}:{d}": window_indices(L, o, d) for o, d in passes(windows)},
504
+ "stack_layers": int(L), "stack_start": stack_start, "patches": n_patches, "device": str(dev), "device_name": name,
505
+ "seconds": round(time.perf_counter() - t0, 3)}
506
+
507
+
508
+ class _null:
509
+ def __enter__(self):
510
+ return None
511
+
512
+ def __exit__(self, *exc):
513
+ return False
514
+
515
+
516
+ def main(argv=None):
517
+ import argparse
518
+ import json
519
+ ap = argparse.ArgumentParser(description="Ink Lens engine helpers")
520
+ sub = ap.add_subparsers(dest="cmd", required=True)
521
+ e = sub.add_parser("estimate")
522
+ e.add_argument("height", type=int)
523
+ e.add_argument("width", type=int)
524
+ e.add_argument("--windows", type=int, default=3, choices=(1, 3))
525
+ e.add_argument("--reader", default="d9v2", choices=READER_CHOICES)
526
+ f = sub.add_parser("fetch")
527
+ f.add_argument("reader", choices=sorted(READERS))
528
+ a = ap.parse_args(argv)
529
+ try:
530
+ if a.cmd == "estimate":
531
+ print(json.dumps(estimate(a.height, a.width, a.windows, a.reader), indent=1))
532
+ else:
533
+ print(json.dumps({"reader": a.reader, "path": str(ensure_checkpoint(a.reader))}))
534
+ except EngineError as exc:
535
+ print(f"refused: {exc}", file=sys.stderr)
536
+ return 2
537
+ return 0
538
+
539
+
540
+ if __name__ == "__main__":
541
+ sys.exit(main())
gate.py ADDED
@@ -0,0 +1,138 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Ink Lens: the control-set threshold and the region status (numpy only).
2
+
3
+ The rule, frozen in docs/prereg/2026-10-20-ink-lens-gate.md before any map of it existed:
4
+
5
+ - F and R are the mean ink probabilities (0 to 1) of the region with its layers as stored and reversed, each averaged
6
+ over the same depth windows and readers.
7
+ - Papyrus: pixels whose middle CT layer is above the region's 5th percentile of CT and above 0 (so air and the
8
+ masked outside of a segment do not lower the threshold).
9
+ - T is the 99th percentile of R over the papyrus pixels: the level that only 1 % of the control's own pixels pass.
10
+ - Kept ink: papyrus pixels with F > T. Excess: the fraction of papyrus pixels with F > T, divided by 0.01.
11
+ - Status: ink when excess >= 3, weak when 1.5 <= excess < 3, none below 1.5, too_small under 100,000 papyrus pixels
12
+ (about 3 mm square at 9.6 um), unreadable when a map is not finite, constant, or identical to its control.
13
+
14
+ A region with no text, or where the model reads the reversed volume as well as the stored one, has an excess near 1
15
+ and the status none: the check can fail. Everything it keeps is model output, not a reading.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ RULE_ID = "ink-lens-gate-v1"
21
+ CT_PERCENTILE = 5.0
22
+ CONTROL_PERCENTILE = 99.0
23
+ BASE_RATE = 0.01
24
+ INK_EXCESS = 3.0
25
+ WEAK_EXCESS = 1.5
26
+ MIN_PAPYRUS = 100_000
27
+ STATUSES = ("ink", "weak", "none", "too_small", "unreadable")
28
+ STATUS_TEXT = {
29
+ "ink": "ink above the control: at least 3 times as many pixels pass the control's 99th percentile as the control",
30
+ "weak": "some ink above the control: 1.5 to 3 times the control's share; look before trusting it",
31
+ "none": "no ink above the control: the stored order passes the control's 99th percentile no more than 1.5 times "
32
+ "as often as the control itself",
33
+ "too_small": "too little papyrus in the region to judge (under 100,000 pixels, about 3 mm square)",
34
+ "unreadable": "the maps cannot be judged (not finite, constant, or the same as the control)",
35
+ }
36
+
37
+
38
+ class GateError(ValueError):
39
+ """Maps the gate cannot take at all (wrong shapes); the message says why."""
40
+
41
+
42
+ def papyrus(ct_middle, percentile=CT_PERCENTILE):
43
+ """Boolean mask of papyrus pixels in a region: middle CT layer above its own percentile and above 0."""
44
+ import numpy as np
45
+ ct = np.asarray(ct_middle)
46
+ if ct.ndim != 2:
47
+ raise GateError(f"the CT layer is 2-D, not {ct.shape}")
48
+ nz = ct[ct > 0]
49
+ if nz.size == 0:
50
+ return np.zeros(ct.shape, bool)
51
+ floor = max(float(np.percentile(ct, percentile)), 0.0)
52
+ return ct > floor
53
+
54
+
55
+ def _unreadable(F, R, mask):
56
+ import numpy as np
57
+ reasons = []
58
+ for name, m in (("stored-order map", F), ("control map", R)):
59
+ if not np.all(np.isfinite(m)):
60
+ reasons.append(f"the {name} has values that are not finite")
61
+ elif mask.any() and float(m[mask].max()) - float(m[mask].min()) < 1e-6:
62
+ reasons.append(f"the {name} is constant on the papyrus")
63
+ if not reasons and mask.any() and np.array_equal(F[mask], R[mask]):
64
+ reasons.append("the stored-order map is identical to its control (a broken run, or the control was not run)")
65
+ return reasons
66
+
67
+
68
+ def decide(F, R, ct_middle, min_papyrus=MIN_PAPYRUS):
69
+ """The gate on one region: threshold, excess, status and counts, as a JSON-able dict."""
70
+ import numpy as np
71
+ F = np.asarray(F, dtype=np.float32)
72
+ R = np.asarray(R, dtype=np.float32)
73
+ if F.shape != R.shape or F.ndim != 2:
74
+ raise GateError(f"the map {F.shape} and its control {R.shape} must be 2-D and the same shape")
75
+ mask = papyrus(ct_middle)
76
+ if mask.shape != F.shape:
77
+ raise GateError(f"the CT layer {mask.shape} and the maps {F.shape} differ in shape")
78
+ n = int(mask.sum())
79
+ out = {"rule": RULE_ID, "papyrus_px": n, "region_px": int(mask.size), "threshold": None, "excess": None,
80
+ "forward_above": None, "control_above": None, "status": None}
81
+ reasons = _unreadable(F, R, mask)
82
+ if reasons:
83
+ out.update(status="unreadable", reasons=reasons)
84
+ elif n < min_papyrus:
85
+ out.update(status="too_small")
86
+ else:
87
+ T = float(np.percentile(R[mask], CONTROL_PERCENTILE))
88
+ f_above = float((F[mask] > T).mean())
89
+ r_above = float((R[mask] > T).mean())
90
+ excess = f_above / BASE_RATE
91
+ status = "ink" if excess >= INK_EXCESS else "weak" if excess >= WEAK_EXCESS else "none"
92
+ out.update(threshold=round(T, 6), excess=round(excess, 4), forward_above=round(f_above, 6),
93
+ control_above=round(r_above, 6), status=status)
94
+ out["status_text"] = STATUS_TEXT[out["status"]]
95
+ out["note"] = "Model output, not a reading."
96
+ return out
97
+
98
+
99
+ def kept(F, decision, ct_middle):
100
+ """F where it passes the control's threshold on papyrus, else 0 (float32). Nothing passes unless the status is
101
+ ink or weak."""
102
+ import numpy as np
103
+ F = np.asarray(F, dtype=np.float32)
104
+ out = np.zeros_like(F)
105
+ if decision.get("status") not in ("ink", "weak"):
106
+ return out
107
+ m = papyrus(ct_middle) & (F > float(decision["threshold"]))
108
+ out[m] = F[m]
109
+ return out
110
+
111
+
112
+ def to_u8(kept_map):
113
+ """The kept map as uint8 for an overlay: 0 where nothing is kept (transparent in VC3D), else 1 to 255."""
114
+ import numpy as np
115
+ k = np.asarray(kept_map, dtype=np.float32)
116
+ out = np.zeros(k.shape, np.uint8)
117
+ on = k > 0
118
+ out[on] = np.clip(np.rint(k[on] * 254) + 1, 1, 255).astype(np.uint8)
119
+ return out
120
+
121
+
122
+ def label_shares(kept_map, ink, supervised, inner=64):
123
+ """The preregistered label check: the share of labeled ink pixels kept and the share of labeled background
124
+ pixels kept, inside the supervision mask with an inner edge left out."""
125
+ import numpy as np
126
+ k = np.asarray(kept_map) > 0
127
+ m = np.asarray(supervised, bool).copy()
128
+ if inner:
129
+ m[:inner] = m[-inner:] = False
130
+ m[:, :inner] = m[:, -inner:] = False
131
+ ink = np.asarray(ink, bool)
132
+ ink_px, bg_px = int((m & ink).sum()), int((m & ~ink).sum())
133
+ ink_share = float((k & m & ink).sum()) / ink_px if ink_px else None
134
+ bg_share = float((k & m & ~ink).sum()) / bg_px if bg_px else None
135
+ passes = None if ink_share is None or bg_share is None else ink_share > bg_share
136
+ return {"ink_px": ink_px, "background_px": bg_px, "ink_kept_share": None if ink_share is None else round(ink_share, 5),
137
+ "background_kept_share": None if bg_share is None else round(bg_share, 5), "ink_share_larger": passes,
138
+ "inner": inner}
inklens.py ADDED
@@ -0,0 +1,627 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Ink Lens client: a control-checked ink map of one region of a VC3D segment, written back as VC3D's own files.
2
+
3
+ python3 inklens.py estimate 1024 1024 [--windows 3] [--reader d9v2]
4
+ python3 inklens.py samples
5
+ python3 inklens.py demo 0841-w00 [--local | --space OWNER/NAME] [--size 640] [--vc3d-out DIR] [--score] [--json]
6
+ python3 inklens.py run --segment SEGDIR (--surface-volume PATH | --volume OME_ZARR) --box X Y W H
7
+ [--um-per-px UM] [--local | --space OWNER/NAME] [--reader d9v2|ink_9um|both]
8
+ [--windows 3|1] [--no-pins] [--letter-mm 3.0] [--bridge [NAME]] [--dry-run] [--json]
9
+ python3 inklens.py run --from-vc3d [--bridge NAME] --volume OME_ZARR --size 1024 ...
10
+
11
+ What run does, in order, stopping at the first refusal (exit 2):
12
+ 1. reads the region: from a surface volume that covers the segment (zarr, .npy, .npz or .tif, layers first), or
13
+ by rendering only the region with vc_render_tifxyz (--volume; the binary ships with VC3D);
14
+ 2. pools it to about 9.6 um (2.4 um renders: 4 x 4 x 4 mean, as the organizers' prepare_9um_isotropic_input.py);
15
+ 3. runs the ink model in both depth orders over three depth windows: on a Hugging Face ZeroGPU Space with your own
16
+ token, so your own ZeroGPU quota pays (--space, the default), or on this machine (--local: CUDA, Apple MPS or
17
+ CPU, no account);
18
+ 4. applies the control-set threshold (gate.py) and recomputes it here from the returned maps;
19
+ 5. reads the kept map with the Scroll Text Reader (kit/letterread.py), its reverse-depth twin as the control map;
20
+ 6. writes into SEGDIR: inklens/<run>.png (the whole segment canvas, transparent except kept ink), inklens/mosaic.png
21
+ (every run on this segment so far), records for both in ink-detections.json (existing records kept),
22
+ inklens/<run>.pins.json (a VC3D point collection) and inklens/<run>.json (the receipt).
23
+ With --bridge, the pins are merged into VC3D's current point collections and the view centers on the region.
24
+
25
+ Exit codes: 0 ink or weak, 3 none or too_small, 2 refused. Everything it writes is model output, not a reading.
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import argparse
31
+ import hashlib
32
+ import json
33
+ import math
34
+ import os
35
+ import shutil
36
+ import subprocess
37
+ import sys
38
+ import tempfile
39
+ import time
40
+ from pathlib import Path
41
+
42
+ HERE = Path(__file__).resolve().parent
43
+ if str(HERE) not in sys.path:
44
+ sys.path.insert(0, str(HERE))
45
+ import engine # noqa: E402
46
+ import gate # noqa: E402
47
+ import vc3dout # noqa: E402
48
+ import volio # noqa: E402
49
+
50
+ VERSION = engine.VERSION
51
+ DEFAULT_SPACE = os.environ.get("INKLENS_SPACE", "SharpMeow/ink-lens")
52
+ SAMPLES_FILE = HERE / "samples.json"
53
+ EXIT_OK, EXIT_REFUSED, EXIT_NONE = 0, 2, 3
54
+ MAX_UPLOAD_BYTES = 64 << 20
55
+ LETTER_MM = 3.0
56
+ READER_WEIGHTS = "letters-v2-ccby"
57
+ NOTE = "Model output, not a reading."
58
+
59
+
60
+ class Refused(Exception):
61
+ """A request Ink Lens refuses; the message says why (exit 2)."""
62
+
63
+
64
+ # ---------------------------------------------------------------- samples
65
+
66
+ def load_samples(path=SAMPLES_FILE):
67
+ data = json.loads(Path(path).read_text())
68
+ if data.get("bucket") != volio.BUCKET:
69
+ raise Refused(f"samples must come from {volio.BUCKET}")
70
+ seen = set()
71
+ for s in data["samples"]:
72
+ if s["id"] in seen:
73
+ raise Refused(f"sample {s['id']} is listed twice")
74
+ seen.add(s["id"])
75
+ for part in ("surface_volume", "labels"):
76
+ v = s.get(part, "")
77
+ if not v or "://" in v or v.startswith("/") or ".." in v.split("/"):
78
+ raise Refused(f"{s['id']}: {part} must be a plain path inside the segment")
79
+ H, W = s["surface_shape"]
80
+ y0, y1, x0, x1 = s["crop"]
81
+ if not (0 <= y0 < y1 <= H and 0 <= x0 < x1 <= W):
82
+ raise Refused(f"{s['id']}: crop {s['crop']} is outside the {H} x {W} surface")
83
+ return data
84
+
85
+
86
+ def sample_by(key, data=None):
87
+ data = data or load_samples()
88
+ for s in data["samples"]:
89
+ if key in (s["id"], s["title"]):
90
+ return s
91
+ raise Refused(f"no sample {key!r}; the samples are {', '.join(x['id'] for x in data['samples'])}")
92
+
93
+
94
+ def sample_url(s, part="surface_volume"):
95
+ return f"{volio.BUCKET}/{s['scroll']}/segments/{s['segment']}/{s[part]}"
96
+
97
+
98
+ def sample_box(s, size=None, at=None):
99
+ """(y0, y1, x0, x1): the sample's crop, a size x size square at its center, or at a given (y0, x0)."""
100
+ y0, y1, x0, x1 = (int(v) for v in s["crop"])
101
+ if at is not None:
102
+ H, W = s["surface_shape"]
103
+ size = int(size or (y1 - y0))
104
+ y, x = int(at[0]), int(at[1])
105
+ if not (0 <= y and 0 <= x and y + size <= H and x + size <= W):
106
+ raise Refused(f"a {size} px region at rows {y}, columns {x} is outside the {H} x {W} surface")
107
+ return y, y + size, x, x + size
108
+ if size is None:
109
+ return y0, y1, x0, x1
110
+ size = int(size)
111
+ if not engine.MIN_SIDE <= size <= min(y1 - y0, x1 - x0):
112
+ raise Refused(f"size {size}: use {engine.MIN_SIDE} to {min(y1 - y0, x1 - x0)} px for {s['id']}")
113
+ top, left = (y0 + y1) // 2 - size // 2, (x0 + x1) // 2 - size // 2
114
+ return top, top + size, left, left + size
115
+
116
+
117
+ def read_sample(s, box):
118
+ y0, y1, x0, x1 = box
119
+ data, info = volio.read_region(sample_url(s), (y0, x0, y1 - y0, x1 - x0))
120
+ return volio.to_uint8(data), info
121
+
122
+
123
+ def labels_for(s, box, shape):
124
+ """Ink and supervision on the region's grid, through kit.auc (needs kit and zarr)."""
125
+ kit = find_kit()
126
+ if kit is None:
127
+ raise Refused("label scoring needs this repository's kit/ (and zarr)")
128
+ from kit import auc, fetch
129
+ with tempfile.TemporaryDirectory(prefix="inklens-labels-") as tmp:
130
+ fetch.fetch_prefix(f"{s['scroll']}/segments/{s['segment']}/{s['labels']}", tmp)
131
+ return auc.labels_on_map(Path(tmp) / "inklabels.zarr", Path(tmp) / "supervision.zarr", "2",
132
+ tuple(s["surface_shape"]), tuple(box), tuple(shape))
133
+
134
+
135
+ # ---------------------------------------------------------------- the lens: model, gate, letters
136
+
137
+ def find_kit():
138
+ """Put this repository's kit/ on sys.path if Ink Lens runs from inside it; returns the root or None."""
139
+ for folder in (HERE, *HERE.parents):
140
+ if (folder / "kit" / "__init__.py").is_file():
141
+ if str(folder) not in sys.path:
142
+ sys.path.insert(0, str(folder))
143
+ return folder
144
+ return None
145
+
146
+
147
+ def ct_middle(volume):
148
+ return volume[volume.shape[0] // 2]
149
+
150
+
151
+ def analyze(F, R, volume, min_papyrus=gate.MIN_PAPYRUS):
152
+ """The gate on one region's maps: decision, kept map (float) and the control's own kept map."""
153
+ import numpy as np
154
+ ct = ct_middle(volume)
155
+ d = gate.decide(F, R, ct, min_papyrus=min_papyrus)
156
+ kept = gate.kept(F, d, ct)
157
+ kept_r = np.zeros_like(kept)
158
+ if d["status"] in ("ink", "weak"):
159
+ m = gate.papyrus(ct) & (R > d["threshold"])
160
+ kept_r[m] = R[m]
161
+ return d, kept, kept_r
162
+
163
+
164
+ _ENGINE = {}
165
+
166
+
167
+ def local_engine(names):
168
+ key = tuple(sorted(names))
169
+ if key not in _ENGINE:
170
+ _ENGINE[key] = engine.Engine(readers=names)
171
+ return _ENGINE[key]
172
+
173
+
174
+ def run_local(volume, reader="d9v2", windows=3, device=None):
175
+ eng = local_engine(engine.readers_of(reader))
176
+ out = eng.run(volume, reader=reader, windows=windows, device=device)
177
+ out["engine"] = eng.describe()
178
+ out["where"] = "local"
179
+ return out
180
+
181
+
182
+ def hf_token(explicit=None):
183
+ """The user's own Hugging Face token (so ZeroGPU bills their quota): --token, HF_TOKEN, or `hf auth login`'s."""
184
+ if explicit:
185
+ return explicit
186
+ if os.environ.get("HF_TOKEN"):
187
+ return os.environ["HF_TOKEN"]
188
+ try:
189
+ from huggingface_hub import get_token
190
+ return get_token()
191
+ except Exception: # noqa: BLE001 (no huggingface_hub, or no stored token)
192
+ return None
193
+
194
+
195
+ def pack_volume(volume, path):
196
+ import numpy as np
197
+ np.savez_compressed(path, volume=volume)
198
+ size = Path(path).stat().st_size
199
+ if size > MAX_UPLOAD_BYTES:
200
+ raise Refused(f"the region packs to {size / 2 ** 20:.1f} MB; the Space takes at most "
201
+ f"{MAX_UPLOAD_BYTES >> 20} MB. Use a smaller region or --local")
202
+ return path
203
+
204
+
205
+ def unpack_maps(path):
206
+ import numpy as np
207
+ with np.load(path, allow_pickle=False) as z:
208
+ return {k: z[k] for k in z.files}
209
+
210
+
211
+ def run_space(volume, space=DEFAULT_SPACE, reader="d9v2", windows=3, token=None, client_factory=None):
212
+ """One call to the Ink Lens Space with the user's own token. Returns the run dict (maps as float32)."""
213
+ tok = hf_token(token)
214
+ if not tok:
215
+ raise Refused("Space mode runs on your own ZeroGPU quota, so it needs your Hugging Face token: run "
216
+ "'hf auth login' or set HF_TOKEN (a read token is enough). Or use --local to run on this machine")
217
+ if client_factory is None:
218
+ try:
219
+ from gradio_client import Client, handle_file
220
+ except ImportError:
221
+ raise Refused("Space mode needs gradio_client (pip install gradio_client), or use --local") from None
222
+ import inspect
223
+ kw = "hf_token" if "hf_token" in inspect.signature(Client).parameters else "token"
224
+
225
+ def client_factory(src):
226
+ return Client(src, **{kw: tok}, verbose=False), handle_file
227
+ with tempfile.TemporaryDirectory(prefix="inklens-up-") as tmp:
228
+ packed = pack_volume(volume, Path(tmp) / "region.npz")
229
+ client, handle = client_factory(space)
230
+ t0 = time.time()
231
+ result, maps_file = client.predict(handle(str(packed)), reader, int(windows), api_name="/lens_region")[:2]
232
+ if isinstance(result, str):
233
+ result = json.loads(result)
234
+ if not isinstance(result, dict) or result.get("error"):
235
+ raise Refused(f"the Space refused the region: {result.get('error') if isinstance(result, dict) else result}")
236
+ maps = unpack_maps(maps_file if isinstance(maps_file, str) else maps_file["path"])
237
+ run = {"forward": maps["forward"].astype("float32"), "reverse": maps["reverse"].astype("float32"),
238
+ "where": f"space {space}", "space_result": result, "round_trip_s": round(time.time() - t0, 2)}
239
+ run.update({k: result.get(k) for k in ("readers", "windows", "patches", "device", "device_name", "seconds",
240
+ "gpu_seconds_requested", "engine")})
241
+ return run
242
+
243
+
244
+ def check_space_gate(run, decision):
245
+ """The Space's own gate must agree with the gate recomputed here from the maps it returned."""
246
+ theirs = (run.get("space_result") or {}).get("gate")
247
+ if theirs is None:
248
+ return
249
+ if theirs.get("status") != decision["status"]:
250
+ raise Refused(f"the Space says {theirs.get('status')!r} but its own maps give {decision['status']!r} here; "
251
+ "nothing is written")
252
+
253
+
254
+ def letters(kept, kept_r, um_per_px, letter_mm=LETTER_MM, weights=READER_WEIGHTS):
255
+ """The Scroll Text Reader on the kept map, the control's own kept map as its control map. None without kit."""
256
+ if find_kit() is None:
257
+ return None, "no kit/ next to Ink Lens: letter pins need this repository"
258
+ from kit import letterread
259
+ if not kept.any():
260
+ return None, "nothing kept, so nothing to read"
261
+ lp = letterread.letter_px_from_units(letter_mm, um_per_px)
262
+ res = letterread.read(kept, weights, letter_px=lp, control=kept_r, orientation=False)
263
+ return res, None
264
+
265
+
266
+ def letter_points(res, box_render, pool):
267
+ """Kept letters of a strong or weak read as render-pixel centers (row, column), with glyph and confidence."""
268
+ if not res or res.get("control", {}).get("status") not in ("strong", "weak"):
269
+ return []
270
+ out = []
271
+ for line in res.get("lines", []):
272
+ for L in line.get("letters", []):
273
+ if not L.get("kept"):
274
+ continue
275
+ y0, y1, x0, x1 = L["box"]
276
+ out.append({"row": box_render[0] + (y0 + y1) / 2 * pool, "col": box_render[1] + (x0 + x1) / 2 * pool,
277
+ "glyph": L["glyph"], "p": L["p"]})
278
+ return out
279
+
280
+
281
+ # ---------------------------------------------------------------- VC3D files
282
+
283
+ def run_id(reader, box):
284
+ return f"{time.strftime('%Y%m%dT%H%M%S')}-{reader}-y{int(box[0])}-x{int(box[1])}"
285
+
286
+
287
+ def write_vc3d(segdir, rid, box_render, pool, kept_u8, decision, receipt, pins=None, xyz=None):
288
+ """Write the run's files into the segment folder; returns their paths and the pins' voxel points."""
289
+ seg = vc3dout.segment(segdir)
290
+ out_dir = Path(segdir) / "inklens"
291
+ canvas, div = vc3dout.canvas(seg, box_render, kept_u8, pool)
292
+ png = vc3dout.png_bytes(canvas)
293
+ run_png = vc3dout.atomic_write(out_dir / f"{rid}.png", png)
294
+ mosaic, merged = vc3dout.merge_mosaic(out_dir / "mosaic.png", canvas)
295
+ mosaic_png = vc3dout.atomic_write(out_dir / "mosaic.png", vc3dout.png_bytes(mosaic))
296
+ sha = hashlib.sha256(png).hexdigest()
297
+ label = f"Ink Lens {receipt['reader']} {decision['status']} y{int(box_render[0])} x{int(box_render[1])}"
298
+ recs = [vc3dout.record(seg, f"inklens/{rid}.png", label, sha, canvas.shape[::-1],
299
+ {"status": decision["status"], "excess": decision["excess"], "run": rid}),
300
+ vc3dout.record(seg, "inklens/mosaic.png", "Ink Lens mosaic (all runs)",
301
+ hashlib.sha256(mosaic_png.read_bytes()).hexdigest(), mosaic.shape[::-1])]
302
+ rec_info = vc3dout.merge_records(segdir, recs)
303
+ files = {"png": str(run_png), "mosaic": str(mosaic_png), "records": rec_info["file"]}
304
+ voxels = []
305
+ if pins:
306
+ if xyz is None:
307
+ xyz = vc3dout.load_xyz(segdir)
308
+ for p in pins:
309
+ gr, gc = vc3dout.render_to_grid(seg, p["row"], p["col"])
310
+ v = vc3dout.grid_to_voxel(xyz, gr, gc)
311
+ if v is not None:
312
+ voxels.append(v)
313
+ if voxels:
314
+ doc = vc3dout.points_doc(f"Ink Lens {rid}", voxels, metadata={"ink_lens_run": rid})
315
+ files["pins"] = str(vc3dout.atomic_write(out_dir / f"{rid}.pins.json", json.dumps(doc, indent=1) + "\n"))
316
+ receipt = dict(receipt, files=files, canvas_size=list(canvas.shape[::-1]), canvas_divisor=div,
317
+ mosaic_merged=merged, pins_written=len(voxels), segment_key=seg["key"])
318
+ files["receipt"] = str(vc3dout.atomic_write(out_dir / f"{rid}.json", json.dumps(receipt, indent=1) + "\n"))
319
+ return files, voxels
320
+
321
+
322
+ def bridge_push(name, pins_path, center):
323
+ """Merge the pins into VC3D's current point collections (save, merge, load) and center the view."""
324
+ import bridge
325
+ path = bridge.discover(name)
326
+ with bridge.Bridge(path) as br, tempfile.TemporaryDirectory(prefix="inklens-points-") as tmp:
327
+ cur = Path(tmp) / "current.json"
328
+ br.call("points.save_json", {"path": str(cur)})
329
+ existing = json.loads(cur.read_text()) if cur.is_file() and cur.stat().st_size else None
330
+ merged = vc3dout.merge_points(existing, json.loads(Path(pins_path).read_text()))
331
+ out = Path(tmp) / "merged.json"
332
+ out.write_text(json.dumps(merged))
333
+ br.call("points.load_json", {"path": str(out)})
334
+ if center:
335
+ br.call("viewer.center_on_point", {"point": {"x": center[0], "y": center[1], "z": center[2]}})
336
+ return {"bridge": path, "collections": len(merged["collections"])}
337
+
338
+
339
+ # ---------------------------------------------------------------- reading a region of a segment
340
+
341
+ def ome_voxel_um(path):
342
+ """The level-0 voxel size in micrometers from an OME-Zarr's multiscales, or None."""
343
+ try:
344
+ raw = volio._read(str(path).rstrip("/"), ".zattrs")
345
+ a = json.loads(raw or b"{}")
346
+ ms = a["multiscales"][0]
347
+ scale = ms["datasets"][0]["coordinateTransformations"][0]["scale"]
348
+ unit = (ms.get("axes") or [{}])[-1].get("unit", "micrometer")
349
+ f = {"micrometer": 1.0, "nanometer": 1e-3, "millimeter": 1e3}.get(unit, 1.0)
350
+ return float(scale[-1]) * f
351
+ except (KeyError, IndexError, TypeError, ValueError, json.JSONDecodeError, volio.VolumeError):
352
+ return None
353
+
354
+
355
+ def render_region(segdir, volume, box_render, layers, binary=None, timeout_min=20):
356
+ """vc_render_tifxyz on just the region (crop flags), uncompressed zarr in a temporary folder; the array."""
357
+ exe = binary or shutil.which("vc_render_tifxyz")
358
+ if not exe:
359
+ raise Refused("vc_render_tifxyz is not on PATH (it ships with VC3D builds); give --render-binary, or render "
360
+ "the segment's surface volume yourself and pass --surface-volume")
361
+ y, x, h, w = box_render
362
+ with tempfile.TemporaryDirectory(prefix="inklens-render-") as tmp:
363
+ out = Path(tmp) / "region.zarr"
364
+ cmd = [exe, "--volume", str(volume), "--group-idx", "0", "--scale", "1", "--segmentation", str(segdir),
365
+ "--num-slices", str(layers), "--crop-x", str(x), "--crop-y", str(y), "--crop-width", str(w),
366
+ "--crop-height", str(h), "--zarr-output", str(out), "--zarr-compressor", "none", "--pyramid", "0",
367
+ "--timeout", str(timeout_min)]
368
+ p = subprocess.run(cmd, capture_output=True, text=True)
369
+ if p.returncode != 0:
370
+ raise Refused(f"vc_render_tifxyz failed ({p.returncode}): {(p.stderr or p.stdout)[-600:]}")
371
+ arr = volio.open_zarr(out)
372
+ data = arr.read((0, arr.shape[0]), (0, arr.shape[1]), (0, arr.shape[2]))
373
+ return data, {"render": " ".join(cmd[:1] + [c if c != str(out) else "TMP/region.zarr" for c in cmd[1:]])}
374
+
375
+
376
+ # ---------------------------------------------------------------- commands
377
+
378
+ def emit(obj, as_json):
379
+ if as_json:
380
+ print(json.dumps(obj, indent=1, default=str))
381
+ else:
382
+ for k, v in obj.items():
383
+ if isinstance(v, (dict, list)):
384
+ v = json.dumps(v, default=str)
385
+ print(f"{k}: {v}")
386
+
387
+
388
+ def exit_for(status):
389
+ return EXIT_OK if status in ("ink", "weak") else EXIT_NONE
390
+
391
+
392
+ def lens(volume, args):
393
+ if args.local:
394
+ return run_local(volume, args.reader, args.windows, device=getattr(args, "device", None))
395
+ return run_space(volume, args.space, args.reader, args.windows, token=getattr(args, "token", None))
396
+
397
+
398
+ def cmd_estimate(a):
399
+ emit(engine.estimate(a.height, a.width, a.windows, a.reader), a.json)
400
+ return EXIT_OK
401
+
402
+
403
+ def cmd_samples(a):
404
+ emit({"samples": [{k: s[k] for k in ("id", "title", "role", "crop")} for s in load_samples()["samples"]]}, True)
405
+ return EXIT_OK
406
+
407
+
408
+ def cmd_demo(a):
409
+ """A public sample end to end: read, lens, gate, letters; with --vc3d-out, VC3D's files into a downloaded copy
410
+ of the sample's tifxyz mesh."""
411
+ s = sample_by(a.sample)
412
+ box = sample_box(s, a.size, a.at)
413
+ est = engine.estimate(box[1] - box[0], box[3] - box[2], a.windows, a.reader)
414
+ if a.dry_run:
415
+ emit({"sample": s["id"], "box": box, "estimate": est}, a.json)
416
+ return EXIT_OK
417
+ volume, src = read_sample(s, box)
418
+ run = lens(volume, a)
419
+ decision, kept, kept_r = analyze(run["forward"], run["reverse"], volume)
420
+ check_space_gate(run, decision)
421
+ out = {"sample": s["id"], "role": s["role"], "box": list(box), "where": run["where"], "gate": decision,
422
+ "patches": run.get("patches"), "seconds": run.get("seconds"), "device": run.get("device"), "note": NOTE}
423
+ if a.score:
424
+ ink, sup = labels_for(s, box, run["forward"].shape)
425
+ from kit import auc
426
+ out["labels"] = {"shares": gate.label_shares(kept, ink, sup),
427
+ "auc_forward": auc.score_array(run["forward"], ink, sup, inner=64)["auc"],
428
+ "auc_reverse": auc.score_array(run["reverse"], ink, sup, inner=64)["auc"]}
429
+ res, why = (None, "skipped (--no-pins)") if a.no_pins else letters(kept, kept_r, s["um_per_px"], a.letter_mm)
430
+ out["letters"] = summarize_letters(res, why)
431
+ if a.vc3d_out:
432
+ if not s.get("tifxyz"):
433
+ raise Refused(f"sample {s['id']} has no tifxyz mesh listed; pick one that does for --vc3d-out")
434
+ segdir = fetch_tifxyz(s, Path(a.vc3d_out))
435
+ box_render = (box[0], box[2], box[1] - box[0], box[3] - box[2]) # (y, x, h, w)
436
+ rid = run_id(a.reader, box_render)
437
+ receipt = make_receipt(run, decision, a, box_render=box_render, pool=1,
438
+ source={"sample": s["id"], **src}, letters=out["letters"])
439
+ pins = letter_points(res, box_render, 1)
440
+ files, voxels = write_vc3d(segdir, rid, box_render, 1, gate.to_u8(kept), decision, receipt, pins)
441
+ out["vc3d"] = {"segment": str(segdir), "files": files, "pins": len(voxels)}
442
+ if res:
443
+ vc3dout.atomic_write(Path(segdir) / "inklens" / f"{rid}.letters.json", json.dumps(res, indent=1))
444
+ if a.save_maps:
445
+ import numpy as np
446
+ np.savez_compressed(a.save_maps, forward=run["forward"], reverse=run["reverse"], kept=kept,
447
+ ct=ct_middle(volume))
448
+ emit(out, a.json)
449
+ return exit_for(decision["status"])
450
+
451
+
452
+ def fetch_tifxyz(s, dest):
453
+ """Copy a public sample's tifxyz mesh (meta.json and the x, y, z bands, about 0.6 MB) into dest/<name>."""
454
+ name = s["tifxyz"].rstrip("/").split("/")[-1]
455
+ segdir = Path(dest) / name
456
+ segdir.mkdir(parents=True, exist_ok=True)
457
+ for f in ("meta.json", "x.tif", "y.tif", "z.tif"):
458
+ target = segdir / f
459
+ if not target.is_file():
460
+ data = volio._get(f"{volio.BUCKET}/{s['scroll']}/segments/{s['segment']}/{s['tifxyz']}/{f}")
461
+ if data is None:
462
+ raise Refused(f"{s['id']}: {f} of its tifxyz mesh is missing from the bucket")
463
+ vc3dout.atomic_write(target, data)
464
+ return segdir
465
+
466
+
467
+ def summarize_letters(res, why):
468
+ if res is None:
469
+ return {"status": None, "why": why}
470
+ c = res.get("control", {})
471
+ return {"status": c.get("status"), "letters_kept": c.get("letters_kept"),
472
+ "null_letters_kept": c.get("null_letters_kept"),
473
+ "control_map_letters": (c.get("control_map") or {}).get("letters_kept"),
474
+ "weights": READER_WEIGHTS, "note": "letter strings are hypotheses for a person, kept in the sidecar file"}
475
+
476
+
477
+ def make_receipt(run, decision, a, box_render, pool, source, letters=None):
478
+ return {"tool": f"Ink Lens {VERSION}", "note": NOTE, "reader": a.reader, "windows": a.windows,
479
+ "readers": run.get("readers"), "engine": run.get("engine"), "where": run.get("where"),
480
+ "device": run.get("device"), "device_name": run.get("device_name"), "patches": run.get("patches"),
481
+ "gpu_seconds_requested": run.get("gpu_seconds_requested"), "seconds": run.get("seconds"),
482
+ "window_layers": run.get("window_layers"), "box_render_px": [int(v) for v in box_render],
483
+ "pool": pool, "source": source, "gate": decision, "letters": letters,
484
+ "created": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())}
485
+
486
+
487
+ def cmd_run(a):
488
+ seg = vc3dout.segment(a.segment) if a.segment else None
489
+ center = None
490
+ if a.from_vc3d:
491
+ import bridge
492
+ with bridge.Bridge(bridge.discover(a.bridge)) as br:
493
+ if seg is None:
494
+ seg = vc3dout.segment(bridge.active_segment(br)["path"])
495
+ center = bridge.cursor_point(br)
496
+ xyz = vc3dout.load_xyz(seg["dir"])
497
+ gr, gc, dist = vc3dout.voxel_to_grid(xyz, center)
498
+ if dist > 50:
499
+ raise Refused(f"the cursor is {dist:.0f} voxels from the active segment; put it on the segment")
500
+ r, c = gr / seg["scale"][1], gc / seg["scale"][0]
501
+ if seg is None:
502
+ raise Refused("give --segment SEGDIR (a tifxyz folder), or --from-vc3d with a running VC3D")
503
+ um = a.um_per_px or (ome_voxel_um(a.volume) if a.volume else None)
504
+ if um is None:
505
+ raise Refused("give --um-per-px (the render's pixel size in micrometers)")
506
+ pool = volio.pool_factor(um)
507
+ if a.from_vc3d:
508
+ side = a.size * pool
509
+ box = (int(r - side / 2), int(c - side / 2), side, side)
510
+ elif a.box:
511
+ x, y, w, h = a.box
512
+ box = (y, x, h, w)
513
+ else:
514
+ raise Refused("give --box X Y W H (render pixels of the segment at scale 1) or --from-vc3d")
515
+ cw, ch = seg["canvas_px"]
516
+ y, x, h, w = box
517
+ if not (0 <= y and 0 <= x and y + h <= ch and x + w <= cw):
518
+ raise Refused(f"the box rows {y}..{y + h}, columns {x}..{x + w} is outside the segment canvas {cw} x {ch}")
519
+ mh, mw = h // pool, w // pool
520
+ est = engine.estimate(mh, mw, a.windows, a.reader)
521
+ if a.dry_run:
522
+ rid = run_id(a.reader, box)
523
+ emit({"segment": seg["dir"], "box_render_px": box, "pool": pool, "map_px": [mh, mw], "estimate": est,
524
+ "would_write": [f"inklens/{rid}.png", "inklens/mosaic.png", "ink-detections.json",
525
+ f"inklens/{rid}.pins.json", f"inklens/{rid}.json"]}, a.json)
526
+ return EXIT_OK
527
+ if not a.local and est.get("refused"):
528
+ raise Refused(est["refused"])
529
+ layers = engine.STACK * pool
530
+ if a.surface_volume:
531
+ data, src = volio.read_region(a.surface_volume, box)
532
+ elif a.volume:
533
+ data, src = render_region(seg["dir"], a.volume, box, layers, a.render_binary)
534
+ else:
535
+ raise Refused("give --surface-volume PATH or --volume OME_ZARR")
536
+ volume = volio.pool(volio.to_uint8(data), pool)
537
+ run = lens(volume, a)
538
+ decision, kept, kept_r = analyze(run["forward"], run["reverse"], volume)
539
+ check_space_gate(run, decision)
540
+ res, why = (None, "skipped (--no-pins)") if a.no_pins else letters(kept, kept_r, um * pool, a.letter_mm)
541
+ rid = run_id(a.reader, box)
542
+ summary = summarize_letters(res, why)
543
+ receipt = make_receipt(run, decision, a, box, pool, src, summary)
544
+ files, voxels = write_vc3d(seg["dir"], rid, box, pool, gate.to_u8(kept), decision, receipt,
545
+ letter_points(res, box, pool))
546
+ if res:
547
+ vc3dout.atomic_write(Path(seg["dir"]) / "inklens" / f"{rid}.letters.json", json.dumps(res, indent=1))
548
+ out = {"run": rid, "segment": seg["dir"], "gate": decision, "letters": summary, "files": files,
549
+ "pins": len(voxels), "where": run["where"], "note": NOTE}
550
+ if a.bridge is not None and files.get("pins"):
551
+ out["bridge"] = bridge_push(a.bridge or None, files["pins"], center or voxels[0])
552
+ elif a.bridge is not None:
553
+ out["bridge"] = "no pins to load; in VC3D reopen the segment to see the new ink map"
554
+ emit(out, a.json)
555
+ return exit_for(decision["status"])
556
+
557
+
558
+ def parser():
559
+ ap = argparse.ArgumentParser(prog="inklens", description=__doc__.split("\n\n")[0])
560
+ sub = ap.add_subparsers(dest="cmd", required=True)
561
+
562
+ def common(p):
563
+ g = p.add_mutually_exclusive_group()
564
+ g.add_argument("--local", action="store_true", help="run the model on this machine (CUDA, MPS or CPU)")
565
+ g.add_argument("--space", default=DEFAULT_SPACE, help=f"Hugging Face Space (default {DEFAULT_SPACE})")
566
+ p.add_argument("--token", help="Hugging Face token (default: HF_TOKEN or `hf auth login`)")
567
+ p.add_argument("--device", help="local mode: cuda, mps or cpu (default: the best available)")
568
+ p.add_argument("--reader", default="d9v2", choices=engine.READER_CHOICES)
569
+ p.add_argument("--windows", type=int, default=3, choices=(1, 3))
570
+ p.add_argument("--no-pins", action="store_true", help="skip the Scroll Text Reader and the letter pins")
571
+ p.add_argument("--letter-mm", type=float, default=LETTER_MM)
572
+ p.add_argument("--dry-run", action="store_true", help="print the plan and the GPU estimate; run nothing")
573
+ p.add_argument("--json", action="store_true")
574
+
575
+ e = sub.add_parser("estimate", help="patches and GPU seconds for a region")
576
+ e.add_argument("height", type=int)
577
+ e.add_argument("width", type=int)
578
+ e.add_argument("--windows", type=int, default=3, choices=(1, 3))
579
+ e.add_argument("--reader", default="d9v2", choices=engine.READER_CHOICES)
580
+ e.add_argument("--json", action="store_true")
581
+ e.set_defaults(fn=cmd_estimate)
582
+
583
+ s = sub.add_parser("samples", help="the public samples")
584
+ s.set_defaults(fn=cmd_samples)
585
+
586
+ d = sub.add_parser("demo", help="a public sample end to end")
587
+ d.add_argument("sample")
588
+ d.add_argument("--size", type=int, help="a size x size square (default: the sample's 640 px crop)")
589
+ d.add_argument("--at", type=int, nargs=2, metavar=("ROW", "COL"), help="the square's top-left corner instead")
590
+ d.add_argument("--vc3d-out", help="download the sample's tifxyz mesh here and write VC3D's files into it")
591
+ d.add_argument("--score", action="store_true", help="score the maps and the kept ink against the labels")
592
+ d.add_argument("--save-maps", help="also save forward, reverse, kept and the CT layer as .npz")
593
+ common(d)
594
+ d.set_defaults(fn=cmd_demo)
595
+
596
+ r = sub.add_parser("run", help="a region of a VC3D segment, written back as VC3D files")
597
+ r.add_argument("--segment", help="the tifxyz segment folder")
598
+ r.add_argument("--surface-volume", help="a surface volume of the whole segment (zarr, .npy, .npz, .tif)")
599
+ r.add_argument("--volume", help="the scan's OME-Zarr: render only the region with vc_render_tifxyz")
600
+ r.add_argument("--render-binary", help="path to vc_render_tifxyz")
601
+ r.add_argument("--um-per-px", type=float, help="pixel size of the render (default: from the OME-Zarr)")
602
+ r.add_argument("--box", type=int, nargs=4, metavar=("X", "Y", "W", "H"), help="region in render pixels")
603
+ r.add_argument("--from-vc3d", action="store_true", help="center the region on VC3D's cursor (needs --bridge)")
604
+ r.add_argument("--size", type=int, default=1024, help="with --from-vc3d: region side at 9.6 um (default 1024)")
605
+ r.add_argument("--bridge", nargs="?", const="", default=None,
606
+ help="VC3D agent bridge name or socket (default: the newest live one)")
607
+ common(r)
608
+ r.set_defaults(fn=cmd_run)
609
+ return ap
610
+
611
+
612
+ def main(argv=None):
613
+ a = parser().parse_args(argv)
614
+ try:
615
+ return a.fn(a)
616
+ except (Refused, engine.EngineError, gate.GateError, vc3dout.VC3DError, volio.VolumeError) as exc:
617
+ print(f"refused: {exc}", file=sys.stderr)
618
+ return EXIT_REFUSED
619
+ except Exception as exc: # noqa: BLE001
620
+ if type(exc).__name__ == "BridgeError":
621
+ print(f"refused: {exc}", file=sys.stderr)
622
+ return EXIT_REFUSED
623
+ raise
624
+
625
+
626
+ if __name__ == "__main__":
627
+ sys.exit(main())
kit/__init__.py ADDED
@@ -0,0 +1,7 @@
 
 
 
 
 
 
 
 
1
+ """Scrolls kit: planning, environment checks and experiment records for the Vesuvius Challenge.
2
+
3
+ The reading pipeline itself (VC3D, the ``vesuvius`` library, ink detection) lives in
4
+ ScrollPrize/villa. This package wraps it; it does not reimplement it.
5
+ """
6
+
7
+ __version__ = "0.4.1"
kit/auc.py ADDED
@@ -0,0 +1,345 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Pixel AUC of an ink map against a segment's published ink labels.
2
+
3
+ On a labeled segment no model was trained on (PHerc0841 for `ink_9um`, v8in, d9v2 and Reader
4
+ v2, but not for Hecate, whose base model's trainer lists all three PHerc0841 segments;
5
+ PHerc0139 w045 for v8in only, since ink_9um trained on its 2.4 um render), this is the generalization
6
+ number: the chance that a labeled ink pixel scores above a
7
+ labeled non-ink pixel. Only pixels inside the supervision mask count, because the
8
+ labelers marked ink and non-ink there and nowhere else. Reference values (Community
9
+ reports, not checked here): `ink_9um` on PHerc0841 team surfaces, 0.74 to 0.81 (Bullo27);
10
+ on the PHerc0139 title, 0.81 to 0.95 depending on the checkpoint (Nieuwlaar).
11
+
12
+ The labels sit on the 2.4 um scan's grid. Its pyramid level 2 is the 9 um surface grid up
13
+ to a uniform scale (w045: 5,820 x 8,020 labels for 5,980 x 8,240 surface pixels), so labels
14
+ are mapped onto the map by nearest neighbor, and a scale that differs between the axes is
15
+ refused. A map that covers only a window of the surface gives that window with `crop` and
16
+ the full surface shape with `surface_shape`.
17
+
18
+ The reverse-direction map is the control: it reads the same CT, so it is shown the same
19
+ ink, but in the wrong depth order. A forward AUC well above the reverse AUC says the model
20
+ reads ink, not just brightness.
21
+
22
+ Pixels where the map is exactly 0 are left out by default: villa and v8in write 0 where
23
+ they made no prediction (outside the surface). The count is reported.
24
+
25
+ Sampling noise: a segment's labels cover about 1 cm2 (PHerc0841: 0.9 to 1.4 cm2 each), and
26
+ neighboring pixels are not independent, so an AUC carries more noise than its pixel count
27
+ suggests. `bootstrap` resamples square blocks (default 107 px, 1 mm at 9.366 um) with
28
+ replacement and reports a 95 % interval; `compare` scores a second map on the same pixels
29
+ with the same draws and reports the difference, its interval, and the share of draws in
30
+ which the first map is not ahead. On PHerc0841 a strong map's interval is +-0.01 to +-0.04,
31
+ so a ranking by a smaller margin on one segment is noise (docs/logs/2026-10-07-overlap-and-baseline.md).
32
+ """
33
+
34
+ from .layers import _zarr
35
+ from .verify import VerifyError, _numpy, load_map
36
+
37
+ DEFAULT_LEVEL = "2"
38
+ MAX_AXIS_MISMATCH = 0.005
39
+ BLOCK_PX = 107 # 1 mm at 9.366 um
40
+ BOOT_BINS = 1024 # score bins for the resampled AUCs (the point estimate stays exact)
41
+
42
+
43
+ def _load(path):
44
+ np = _numpy()
45
+ if str(path).endswith(".npy"):
46
+ return np.load(path)
47
+ return load_map(path)
48
+
49
+
50
+ def _same_file(a, b):
51
+ import os
52
+ try:
53
+ return os.path.samefile(a, b)
54
+ except OSError:
55
+ return False
56
+
57
+
58
+ def _levels(path, level):
59
+ zarr = _zarr()
60
+ try:
61
+ node = zarr.open(str(path), mode="r")
62
+ except Exception as exc: # zarr raises several types for a missing or malformed store
63
+ raise VerifyError(f"cannot open {path} as zarr: {exc}") from exc
64
+ if not hasattr(node, "shape"):
65
+ if level not in node:
66
+ raise VerifyError(f"{path}: no level {level!r}; levels: {sorted(node.keys())}")
67
+ node = node[level]
68
+ return node
69
+
70
+
71
+ MIN_FLOAT_LEVELS = 256 # a float map spanning fewer of the 65,536 levels is rescaled min..max
72
+
73
+
74
+ def _quantize(np, values):
75
+ """Integer scores for exact histogram AUC: uint8 and uint16 as is, floats to 0..65535.
76
+
77
+ A float map is read as 0..1 (or 0..255, or 0..65535 when its largest value says so), as
78
+ before. A float map that does not fit that reading, with a value below 0 or above 65535
79
+ (logits, signed integers) or a range so narrow it falls on fewer than MIN_FLOAT_LEVELS
80
+ levels, is instead stretched from its own minimum to its maximum, which keeps every pixel's
81
+ rank. NaN and infinite values are refused: they have no rank."""
82
+ if values.dtype in (np.uint8, np.uint16):
83
+ return values.astype(np.int64), 65536
84
+ v = values.astype(np.float64)
85
+ if not np.isfinite(v).all():
86
+ bad = int((~np.isfinite(v)).sum())
87
+ raise VerifyError(f"the map holds {bad} NaN or infinite values; replace them (with 0 for no "
88
+ "prediction) before scoring")
89
+ if not v.size:
90
+ return v.astype(np.int64), 65536
91
+ low, top = float(v.min()), float(v.max())
92
+ if low >= 0 and top <= 65535:
93
+ s = v / (255.0 if top <= 255 else 65535.0) if top > 1.0 else v
94
+ q = np.clip(np.round(s * 65535), 0, 65535).astype(np.int64)
95
+ if top == low or int(q.max()) - int(q.min()) >= MIN_FLOAT_LEVELS:
96
+ return q, 65536
97
+ if top == low: # a constant map outside 0..65535, such as a blank sham written as logits: every pixel ties
98
+ return np.zeros(v.shape, dtype=np.int64), 65536
99
+ return np.round((v - low) / (top - low) * 65535).astype(np.int64), 65536
100
+
101
+
102
+ def auc_scores(ink_scores, background_scores):
103
+ """Mann-Whitney AUC with ties counted half.
104
+
105
+ The two arrays must be on one scale. score_array quantizes the whole map once before
106
+ splitting it, so a float map is never scaled differently for ink and for background."""
107
+ np = _numpy()
108
+ if len(ink_scores) == 0 or len(background_scores) == 0:
109
+ return None
110
+ if ink_scores.dtype != np.int64 or background_scores.dtype != np.int64:
111
+ both, _ = _quantize(np, np.concatenate([ink_scores.ravel(), background_scores.ravel()]))
112
+ ink_scores, background_scores = both[:ink_scores.size], both[ink_scores.size:]
113
+ a, b, n = ink_scores, background_scores, 65536
114
+ ha = np.bincount(a, minlength=n).astype(np.float64)
115
+ hb = np.bincount(b, minlength=n).astype(np.float64)
116
+ below = np.concatenate(([0.0], np.cumsum(hb)[:-1])) # background strictly below each score
117
+ wins = float((ha * below).sum() + 0.5 * (ha * hb).sum())
118
+ return wins / (float(ha.sum()) * float(hb.sum()))
119
+
120
+
121
+ def label_grid(labels_shape, surface_shape, crop, map_shape):
122
+ """Row and column indices into the labels for every map pixel (nearest neighbor)."""
123
+ np = _numpy()
124
+ sy = labels_shape[0] / surface_shape[0]
125
+ sx = labels_shape[1] / surface_shape[1]
126
+ if abs(sy - sx) > MAX_AXIS_MISMATCH * max(sy, sx):
127
+ raise VerifyError(f"labels {labels_shape} and surface {surface_shape} differ in scale between axes "
128
+ f"({sy:.4f} vs {sx:.4f}); they are not the same grid")
129
+ y0, y1, x0, x1 = crop if crop is not None else (0, surface_shape[0], 0, surface_shape[1])
130
+ if not (0 <= y0 < y1 <= surface_shape[0] and 0 <= x0 < x1 <= surface_shape[1]):
131
+ raise VerifyError(f"crop {[y0, y1, x0, x1]} is outside the {surface_shape[0]} x {surface_shape[1]} surface")
132
+ if (y1 - y0, x1 - x0) != tuple(map_shape):
133
+ raise VerifyError(f"map shape {tuple(map_shape)} does not match the window {y1 - y0} x {x1 - x0}")
134
+ rows = np.minimum(((np.arange(y0, y1) + 0.5) * sy).astype(np.int64), labels_shape[0] - 1)
135
+ cols = np.minimum(((np.arange(x0, x1) + 0.5) * sx).astype(np.int64), labels_shape[1] - 1)
136
+ return rows, cols
137
+
138
+
139
+ def labels_on_map(labels, mask, level, surface_shape, crop, map_shape):
140
+ """Boolean ink and supervision arrays on the map's own grid."""
141
+ np = _numpy()
142
+ lab = _levels(labels, level)
143
+ msk = _levels(mask, level)
144
+ if lab.shape != msk.shape:
145
+ raise VerifyError(f"labels {lab.shape} and mask {msk.shape} differ in shape at level {level}")
146
+ rows, cols = label_grid(lab.shape, surface_shape, crop, map_shape)
147
+ r0, r1, c0, c1 = int(rows.min()), int(rows.max()) + 1, int(cols.min()), int(cols.max()) + 1
148
+ ink = np.asarray(lab[r0:r1, c0:c1])[np.ix_(rows - r0, cols - c0)] > 0
149
+ supervised = np.asarray(msk[r0:r1, c0:c1])[np.ix_(rows - r0, cols - c0)] > 0
150
+ return ink, supervised
151
+
152
+
153
+ def score_array(prediction, ink, mask, keep_zero=False, inner=0):
154
+ """AUC of a 2D map against same-shape boolean ink and mask arrays.
155
+
156
+ inner > 0 leaves out that many pixels along every edge of the map, where a map inferred on
157
+ a cropped input saw less context than the same pixels of a whole-segment map."""
158
+ np = _numpy()
159
+ if inner:
160
+ if 2 * inner >= min(prediction.shape):
161
+ raise VerifyError(f"inner {inner} leaves nothing of a {prediction.shape} map")
162
+ mask = mask.copy()
163
+ mask[:inner] = mask[-inner:] = False
164
+ mask[:, :inner] = mask[:, -inner:] = False
165
+ q, _ = _quantize(np, prediction) # one scale for the whole map
166
+ use = mask & (np.ones_like(mask) if keep_zero else prediction != 0)
167
+ result = {
168
+ "auc": auc_scores(q[use & ink], q[use & ~ink]),
169
+ "ink_px": int((use & ink).sum()),
170
+ "background_px": int((use & ~ink).sum()),
171
+ "zero_px_in_mask": int((mask & (prediction == 0)).sum()),
172
+ "zero_px_counted": bool(keep_zero),
173
+ "inner": inner,
174
+ }
175
+ if result["auc"] is not None:
176
+ result["auc"] = round(result["auc"], 4)
177
+ return result
178
+
179
+
180
+ def _edge_mask(np, mask, inner):
181
+ if inner:
182
+ mask = mask.copy()
183
+ mask[:inner] = mask[-inner:] = False
184
+ mask[:, :inner] = mask[:, -inner:] = False
185
+ return mask
186
+
187
+
188
+ def _auc_hist(np, a, b):
189
+ """AUC from per-bin counts of ink (a) and background (b), ties half; works on stacks."""
190
+ below = np.cumsum(b, axis=-1) - b
191
+ return ((a * below).sum(-1) + 0.5 * (a * b).sum(-1)) / (a.sum(-1) * b.sum(-1))
192
+
193
+
194
+ def _block_ids(np, keys):
195
+ """Sorted occupied block IDs without sorting every pixel when the grid is dense.
196
+
197
+ Keep the counting workspace bounded by pixel count; sparse, very large coordinate
198
+ ranges retain the original unique/sort path rather than allocating by canvas area.
199
+ """
200
+ slots = int(keys.max()) + 1
201
+ if slots > max(4096, 4 * len(keys)):
202
+ return np.unique(keys, return_inverse=True)
203
+ occupied = np.bincount(keys, minlength=slots) > 0
204
+ blocks = np.flatnonzero(occupied)
205
+ inverse = np.cumsum(occupied, dtype=np.int64)[keys] - 1
206
+ return blocks, inverse
207
+
208
+
209
+ def _compact_histograms(np, hists, weights):
210
+ """Remove globally empty score columns when reductions remain integer-exact.
211
+
212
+ At <=2**26 pixels, all nonnegative count products, cumulative sums and half ties
213
+ are exactly representable in float64. Check both the original population and every
214
+ draw. Larger populations keep the historical reduction layout unchanged.
215
+ """
216
+ counts = (hists[0][0] + hists[0][1]).sum(1)
217
+ if counts.sum() > 2 ** 26 or (weights @ counts).max() > 2 ** 26:
218
+ return hists
219
+ occupied = np.zeros(BOOT_BINS, dtype=bool)
220
+ for hi, hb in hists:
221
+ occupied |= (hi + hb).any(0)
222
+ if occupied.all():
223
+ return hists
224
+ return [(hi[:, occupied], hb[:, occupied]) for hi, hb in hists]
225
+
226
+
227
+ def block_bootstrap(prediction, ink, mask, draws=300, block_px=BLOCK_PX, seed=0, other=None,
228
+ keep_zero=False, inner=0):
229
+ """Block-bootstrap interval of the AUC, and of the difference to `other` (same pixels, same draws)."""
230
+ np = _numpy()
231
+ if draws < 20:
232
+ raise VerifyError("use at least 20 bootstrap draws")
233
+ if block_px < 1:
234
+ raise VerifyError("block size must be at least 1 px")
235
+ mask = _edge_mask(np, mask, inner)
236
+ use = mask & (np.ones_like(mask) if keep_zero else prediction != 0)
237
+ maps = [prediction]
238
+ if other is not None:
239
+ if other.shape != prediction.shape:
240
+ raise VerifyError(f"compared map shape {other.shape} differs from the map's {prediction.shape}")
241
+ use &= (np.ones_like(mask) if keep_zero else other != 0)
242
+ maps.append(other)
243
+ ys, xs = np.nonzero(use)
244
+ if len(ys) == 0:
245
+ raise VerifyError("no supervised pixels to resample")
246
+ keys = (ys // block_px) * (prediction.shape[1] // block_px + 1) + xs // block_px
247
+ blocks, inv = _block_ids(np, keys)
248
+ lab = ink[ys, xs]
249
+ if lab.all() or not lab.any():
250
+ raise VerifyError("the mask holds only one class; no AUC to resample")
251
+ hists = []
252
+ for m in maps:
253
+ q, _ = _quantize(np, m)
254
+ top = 255 if m.dtype == np.uint8 else 65535 # _quantize keeps uint8 as 0..255
255
+ qb = q[ys, xs] * (BOOT_BINS - 1) // top
256
+ count = len(blocks) * BOOT_BINS
257
+ indices = inv * BOOT_BINS + qb
258
+ hi = np.bincount(indices[lab], minlength=count).reshape(len(blocks), BOOT_BINS).astype(np.float64)
259
+ hb = np.bincount(indices[~lab], minlength=count).reshape(len(blocks), BOOT_BINS).astype(np.float64)
260
+ hists.append((hi, hb))
261
+ rng = np.random.default_rng(seed)
262
+ w = np.stack([np.bincount(rng.integers(0, len(blocks), len(blocks)), minlength=len(blocks))
263
+ for _ in range(draws)]).astype(np.float64)
264
+ hists = _compact_histograms(np, hists, w)
265
+ stats = [_auc_hist(np, w @ hi, w @ hb) for hi, hb in hists]
266
+ lo, hi_ = np.percentile(stats[0], [2.5, 97.5])
267
+ result = {"draws": draws, "block_px": block_px, "blocks": int(len(blocks)), "seed": seed,
268
+ "ci95": [round(float(lo), 4), round(float(hi_), 4)], "half_width": round(float(hi_ - lo) / 2, 4)}
269
+ if other is not None:
270
+ full = [float(_auc_hist(np, hi.sum(0), hb.sum(0))) for hi, hb in hists]
271
+ diff = stats[0] - stats[1]
272
+ dlo, dhi = np.percentile(diff, [2.5, 97.5])
273
+ result["compare"] = {
274
+ "auc_map": round(full[0], 4), "auc_other": round(full[1], 4), "difference": round(full[0] - full[1], 4),
275
+ "ci95": [round(float(dlo), 4), round(float(dhi), 4)],
276
+ "share_draws_map_not_ahead": round(float((diff <= 0).mean()), 4),
277
+ "pixels": int(len(ys)),
278
+ }
279
+ return result
280
+
281
+
282
+ def score_files(prediction, labels, mask, control=None, level=DEFAULT_LEVEL, crop=None,
283
+ surface_shape=None, keep_zero=False, inner=0, bootstrap=0, block_px=BLOCK_PX,
284
+ compare=None, seed=0):
285
+ np = _numpy()
286
+ pred = np.squeeze(_load(prediction))
287
+ if pred.ndim != 2:
288
+ raise VerifyError(f"{prediction}: expected a 2D map, got shape {pred.shape}")
289
+ if surface_shape is None:
290
+ if crop is not None:
291
+ raise VerifyError("a cropped map needs the full surface shape (surface_shape)")
292
+ surface_shape = pred.shape
293
+ ink, supervised = labels_on_map(labels, mask, level, surface_shape, crop, pred.shape)
294
+ result = {"forward": score_array(pred, ink, supervised, keep_zero, inner),
295
+ "files": {"prediction": str(prediction), "labels": str(labels), "mask": str(mask),
296
+ "control": None if control is None else str(control)},
297
+ "level": level, "crop": crop}
298
+ if control is not None:
299
+ ctrl = np.squeeze(_load(control))
300
+ if ctrl.shape != pred.shape:
301
+ raise VerifyError(f"control shape {ctrl.shape} differs from the map's {pred.shape}")
302
+ # the same file is refused; an identical copy still scores, and its zero gap fails the control honestly
303
+ # (a constant known-bad map, such as a blank sham, equals its own reverse)
304
+ if _same_file(control, prediction):
305
+ raise VerifyError(f"control {control} is the map itself; give the reverse-depth map as the control")
306
+ result["control"] = score_array(ctrl, ink, supervised, keep_zero, inner)
307
+ if bootstrap or compare is not None:
308
+ other = None
309
+ if compare is not None:
310
+ other = np.squeeze(_load(compare))
311
+ result["files"]["compare"] = str(compare)
312
+ result["bootstrap"] = block_bootstrap(pred, ink, supervised, bootstrap or 300, block_px, seed, other,
313
+ keep_zero, inner)
314
+ return result
315
+
316
+
317
+ def format_result(result):
318
+ def line(label, r):
319
+ if r["auc"] is None:
320
+ return f"{label}: no AUC (ink {r['ink_px']} px, background {r['background_px']} px in the mask)"
321
+ zeros = ""
322
+ if r["zero_px_in_mask"]:
323
+ zeros = (f" ({r['zero_px_in_mask']} zero px in the mask counted)" if r["zero_px_counted"]
324
+ else f" ({r['zero_px_in_mask']} unpredicted px in the mask left out)")
325
+ edge = f", {r['inner']} px edge left out" if r.get("inner") else ""
326
+ return (f"{label}: AUC {r['auc']:.4f} on {r['ink_px']} ink and {r['background_px']} background px"
327
+ + edge + zeros)
328
+
329
+ rows = [line("map ", result["forward"])]
330
+ if "control" in result:
331
+ rows.append(line("control", result["control"]))
332
+ f, c = result["forward"]["auc"], result["control"]["auc"]
333
+ if f is not None and c is not None:
334
+ rows.append(f"map minus control: {f - c:+.4f} (near 0 means the model is not reading ink in this direction)")
335
+ b = result.get("bootstrap")
336
+ if b:
337
+ rows.append(f"map AUC 95 % interval {b['ci95'][0]:.4f} to {b['ci95'][1]:.4f} ({b['draws']} draws of "
338
+ f"{b['blocks']} blocks of {b['block_px']} px)")
339
+ c = b.get("compare")
340
+ if c:
341
+ verdict = ("ahead beyond sampling noise" if c["ci95"][0] > 0 else
342
+ "behind beyond sampling noise" if c["ci95"][1] < 0 else "not distinguishable from noise")
343
+ rows.append(f"map minus compared map: {c['difference']:+.4f}, 95 % interval {c['ci95'][0]:+.4f} to "
344
+ f"{c['ci95'][1]:+.4f} on {c['pixels']} shared px: {verdict}")
345
+ return "\n".join(rows)
kit/fetch.py ADDED
@@ -0,0 +1,126 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Mirror one prefix of the public Vesuvius Challenge bucket over anonymous HTTPS.
2
+
3
+ The same files ``aws s3 sync --no-sign-request`` would fetch, without the AWS CLI.
4
+ Existing files of the right size are skipped, so an interrupted fetch resumes.
5
+ """
6
+
7
+ import concurrent.futures
8
+ import os
9
+ import re
10
+ import shutil
11
+ import urllib.parse
12
+ import urllib.request
13
+ from pathlib import Path
14
+
15
+ from . import s3retry
16
+
17
+ BUCKET_URL = "https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com"
18
+ W035_9UM = ("PHerc0139/segments/20260317000000-w035_2026031718/surface-volumes/"
19
+ "9.362um-1.2m-113keV-volume-20250728140407.zarr")
20
+ # Unseen by v8in (its patch pack lists w033, w035, w041, w044 for PHerc0139). Not held out
21
+ # from ink_9um: its 2.4 um render is ink_9um training segment pherc0139-w029, so for ink_9um
22
+ # and its fine-tunes this native 9.362 um render is a cross-scan check on a training surface
23
+ # (docs/logs/2026-10-08-w045-not-held-out.md).
24
+ W045_9UM = ("PHerc0139/segments/20260126000000-w045_2026012619/surface-volumes/"
25
+ "9.362um-1.2m-113keV-volume-20250728140407.zarr")
26
+ ALIASES = {"w035": W035_9UM, "w045": W045_9UM}
27
+
28
+
29
+ class FetchError(Exception):
30
+ pass
31
+
32
+
33
+ def parse_listing(xml):
34
+ """Return ([(key, size)], next_token or None) from one ListObjectsV2 page."""
35
+ entries = [
36
+ (key, int(size))
37
+ for key, size in re.findall(r"<Contents>.*?<Key>([^<]+)</Key>.*?<Size>(\d+)</Size>.*?</Contents>", xml, re.S)
38
+ ]
39
+ token = re.search(r"<NextContinuationToken>([^<]+)</NextContinuationToken>", xml)
40
+ return entries, token.group(1) if token else None
41
+
42
+
43
+ def list_prefix(prefix, opener=urllib.request.urlopen, base=BUCKET_URL):
44
+ prefix = prefix.strip("/") + "/"
45
+ entries, token, seen = [], None, set()
46
+ while True:
47
+ url = f"{base}/?list-type=2&max-keys=1000&prefix={urllib.parse.quote(prefix)}"
48
+ if token:
49
+ url += "&continuation-token=" + urllib.parse.quote(token, safe="")
50
+ page, token = parse_listing(s3retry.open_url(url, opener, 60).read().decode())
51
+ entries += page
52
+ if not token:
53
+ return prefix, entries
54
+ if token in seen:
55
+ raise FetchError("bucket listing repeated a continuation token")
56
+ seen.add(token)
57
+
58
+
59
+ def local_path(dest, prefix, key):
60
+ relative = key[len(prefix):]
61
+ if not relative or relative.startswith("/") or ".." in Path(relative).parts:
62
+ raise FetchError(f"refusing unsafe key {key!r}")
63
+ return Path(dest) / relative
64
+
65
+
66
+ MARGIN_BYTES = 1 << 30 # leave at least 1 GiB free after a fetch
67
+
68
+
69
+ def plan(prefix, dest, opener=urllib.request.urlopen, base=BUCKET_URL):
70
+ """What a fetch would do, before it starts: objects, total bytes, bytes still missing at dest, free bytes there."""
71
+ prefix, entries = list_prefix(prefix, opener, base)
72
+ if not entries:
73
+ raise FetchError(f"nothing under s3://vesuvius-challenge-open-data/{prefix}")
74
+ missing = 0
75
+ for key, size in entries:
76
+ out = local_path(dest, prefix, key)
77
+ if not (out.exists() and out.stat().st_size == size):
78
+ missing += size
79
+ probe = Path(dest)
80
+ while not probe.exists() and probe != probe.parent:
81
+ probe = probe.parent
82
+ free = shutil.disk_usage(probe).free
83
+ return {"prefix": prefix, "objects": len(entries), "total_bytes": sum(s for _, s in entries),
84
+ "missing_bytes": missing, "free_bytes": free, "fits": missing + MARGIN_BYTES <= free,
85
+ "entries": entries}
86
+
87
+
88
+ def human(n):
89
+ for unit in ("B", "KB", "MB", "GB", "TB"):
90
+ if abs(n) < 1000 or unit == "TB":
91
+ return f"{n:.0f} {unit}" if unit == "B" else f"{n:.1f} {unit}"
92
+ n /= 1000
93
+
94
+
95
+ def fetch_prefix(prefix, dest, workers=16, opener=urllib.request.urlopen, base=BUCKET_URL, entries=None):
96
+ if entries is None:
97
+ prefix, entries = list_prefix(prefix, opener, base)
98
+ else:
99
+ prefix = prefix.strip("/") + "/"
100
+ if not entries:
101
+ raise FetchError(f"nothing under s3://vesuvius-challenge-open-data/{prefix}")
102
+
103
+ def get(entry):
104
+ key, size = entry
105
+ out = local_path(dest, prefix, key)
106
+ if out.exists() and out.stat().st_size == size:
107
+ return 0
108
+ out.parent.mkdir(parents=True, exist_ok=True)
109
+ last = None
110
+ for _ in range(4):
111
+ try:
112
+ # a false 404 (S3's NoSuchBucket for a key it just listed) is asked again on a new connection
113
+ data = s3retry.open_url(f"{base}/{urllib.parse.quote(key)}", opener, 120).read()
114
+ if len(data) != size:
115
+ raise FetchError(f"{key}: got {len(data)} bytes, expected {size}")
116
+ tmp = out.with_name(out.name + ".part")
117
+ tmp.write_bytes(data)
118
+ os.replace(tmp, out)
119
+ return size
120
+ except Exception as exc: # retried: truncated reads happen (villa issue #1666)
121
+ last = exc
122
+ raise FetchError(f"{key}: {last}")
123
+
124
+ with concurrent.futures.ThreadPoolExecutor(workers) as pool:
125
+ fetched = sum(pool.map(get, entries))
126
+ return len(entries), fetched, sum(size for _, size in entries)
kit/layers.py ADDED
@@ -0,0 +1,147 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Export a rendered surface volume (zarr) to numbered layer TIFFs: 00.tif, 01.tif, ...
2
+
3
+ villa's `vc_render_tifxyz --zarr-output` and the team's published surface volumes are
4
+ zarr stores of shape (layers, height, width), uint8, either a bare array or an OME-Zarr
5
+ group whose full-resolution level is "0". v8in (YoussefMoNader/ink-8um-v8in) reads a
6
+ directory of numbered layer images instead, and uses the central 24 when there are more.
7
+
8
+ Chunks of these stores usually hold every layer (w045: 28 x 128 x 128), so reading one
9
+ layer decompresses all depths in each touched chunk. The export therefore reads all requested
10
+ layers in row bands into memory when they fit under max_bytes (w045: about 1.4 GB),
11
+ and falls back to one layer at a time otherwise. Depth order is kept as
12
+ stored; reverse it at inference time (v8in `--reverse`), not here, so one export serves both
13
+ directions. Needs numpy, tifffile and zarr (all in villa's environment).
14
+
15
+ The depth-shuffle control (after aviad12g's vesuvius-depth-order-control) is the exception:
16
+ `shuffle` writes the layers in a fixed random order, never the stored or the reversed one. A
17
+ model that reads ink loses it there; on PHerc0841 every released reader we tried fell to
18
+ about 0.5 AUC on shuffled layers, a cleaner null than the reversed volume, which keeps a
19
+ depth structure. `kit shuffle` writes a zarr (villa's input); `kit layers --shuffle` writes
20
+ v8in's layer folder in the same order.
21
+ """
22
+
23
+ from pathlib import Path
24
+
25
+ from .verify import VerifyError, _numpy, missing
26
+
27
+
28
+ def _zarr():
29
+ try:
30
+ import zarr
31
+ except ImportError as exc:
32
+ raise missing("zarr") from exc
33
+ return zarr
34
+
35
+
36
+ def open_volume(path, level="0"):
37
+ """Return the (layers, height, width) array of a surface-volume zarr."""
38
+ zarr = _zarr()
39
+ try:
40
+ node = zarr.open(str(path), mode="r")
41
+ except Exception as exc: # zarr raises several types for a missing or malformed store
42
+ raise VerifyError(f"cannot open {path} as zarr: {exc}") from exc
43
+ if not hasattr(node, "shape"):
44
+ if level not in node:
45
+ raise VerifyError(f"{path}: zarr group has no level {level!r}; levels: {sorted(node.keys())}")
46
+ node = node[level]
47
+ if len(node.shape) != 3:
48
+ raise VerifyError(f"{path}: expected (layers, height, width), got shape {node.shape}")
49
+ return node
50
+
51
+
52
+ def depth_permutation(n, seed):
53
+ """A fixed random order of n layers that is neither the stored nor the reversed order."""
54
+ np = _numpy()
55
+ if n < 3:
56
+ raise VerifyError(f"a depth shuffle needs at least 3 layers, got {n}")
57
+ rng = np.random.default_rng(seed)
58
+ ident = list(range(n))
59
+ while True:
60
+ perm = [int(i) for i in rng.permutation(n)]
61
+ if perm != ident and perm != ident[::-1]:
62
+ return perm
63
+
64
+
65
+ DEFAULT_MAX_BYTES = 4 * 1024 ** 3
66
+ BAND_ROWS = 1024
67
+
68
+
69
+ def export_layers(volume, out_dir, start=0, count=None, compression="zlib", crop=None,
70
+ max_bytes=DEFAULT_MAX_BYTES, order=None):
71
+ """Write layers start .. start+count-1 of volume as 00.tif, 01.tif, ... in out_dir, which must
72
+ not already hold numbered layer TIFFs.
73
+
74
+ crop is (y0, y1, x0, x1) in full-resolution pixels, or None for the whole layer. order, a
75
+ permutation of range(count), writes layer start+order[i] as file i (the shuffle control)."""
76
+ np = _numpy()
77
+ import tifffile
78
+
79
+ total = volume.shape[0]
80
+ if count is None:
81
+ count = total - start
82
+ if start < 0 or count < 1 or start + count > total:
83
+ raise VerifyError(f"layers {start}..{start + count - 1} are outside the volume's {total} layers")
84
+ h, w = volume.shape[1:]
85
+ y0, y1, x0, x1 = 0, h, 0, w
86
+ if crop is not None:
87
+ y0, y1, x0, x1 = crop
88
+ if not (0 <= y0 < y1 <= h and 0 <= x0 < x1 <= w):
89
+ raise VerifyError(f"crop {list(crop)} is outside the {h} x {w} layer")
90
+ region = (slice(y0, y1), slice(x0, x1))
91
+ if volume.dtype != np.uint8:
92
+ raise VerifyError(f"the volume is {volume.dtype}; v8in expects uint8 layers")
93
+ out = Path(out_dir)
94
+ if out.is_dir() and any(p.suffix == ".tif" and p.stem.isdigit() for p in out.iterdir()):
95
+ raise VerifyError(f"{out} already holds layer TIFFs from an earlier export, which v8in would read too; "
96
+ "remove them or give an empty folder")
97
+ stack = None
98
+ if count * (y1 - y0) * (x1 - x0) <= max_bytes:
99
+ stack = np.empty((count, y1 - y0, x1 - x0), dtype=np.uint8)
100
+ for band in range(y0, y1, BAND_ROWS):
101
+ end = min(band + BAND_ROWS, y1)
102
+ stack[:, band - y0:end - y0] = volume[start:start + count, band:end, x0:x1]
103
+ if order is None:
104
+ order = list(range(count))
105
+ elif sorted(order) != list(range(count)):
106
+ raise VerifyError(f"order must be a permutation of 0..{count - 1}")
107
+ out.mkdir(parents=True, exist_ok=True)
108
+ width = max(2, len(str(count - 1)))
109
+ written = []
110
+ for i, src in enumerate(order):
111
+ layer = stack[src] if stack is not None else np.asarray(volume[(start + src, *region)])
112
+ path = out / f"{i:0{width}d}.tif"
113
+ tifffile.imwrite(path, layer, compression=compression)
114
+ written.append(path)
115
+ return written
116
+
117
+
118
+ def export_file(src, out_dir, start=0, count=None, level="0", crop=None, max_bytes=DEFAULT_MAX_BYTES,
119
+ shuffle_seed=None):
120
+ volume = open_volume(src, level)
121
+ n = (volume.shape[0] - start) if count is None else count
122
+ order = None if shuffle_seed is None else depth_permutation(n, shuffle_seed)
123
+ written = export_layers(volume, out_dir, start, count, crop=crop, max_bytes=max_bytes, order=order)
124
+ return {"source": str(src), "shape": list(volume.shape), "start": start, "crop": crop,
125
+ "layers": len(written), "out_dir": str(out_dir), "order": order}
126
+
127
+
128
+ def shuffle_file(src, dst, seed, level="0", crop=None):
129
+ """Write src's layers in a fixed random order to a new zarr (array "0"), for villa's reader."""
130
+ np = _numpy()
131
+ zarr = _zarr()
132
+ if Path(dst).exists():
133
+ raise VerifyError(f"{dst} already exists; remove it or give a new path for the shuffled zarr")
134
+ volume = open_volume(src, level)
135
+ n, h, w = volume.shape
136
+ y0, y1, x0, x1 = crop if crop is not None else (0, h, 0, w)
137
+ if not (0 <= y0 < y1 <= h and 0 <= x0 < x1 <= w):
138
+ raise VerifyError(f"crop {list(crop)} is outside the {h} x {w} layer")
139
+ order = depth_permutation(n, seed)
140
+ data = np.empty((n, y1 - y0, x1 - x0), dtype=volume.dtype)
141
+ for band in range(y0, y1, BAND_ROWS):
142
+ end = min(band + BAND_ROWS, y1)
143
+ data[:, band - y0:end - y0] = volume[:, band:end, x0:x1][order]
144
+ group = zarr.open_group(str(dst), mode="w-")
145
+ group.create_array("0", data=data, chunks=(n, min(128, y1 - y0), min(128, x1 - x0)))
146
+ group.attrs["depth_shuffle"] = {"source": str(src), "seed": seed, "order": order, "crop": crop}
147
+ return {"source": str(src), "out": str(dst), "shape": list(data.shape), "seed": seed, "order": order}
kit/verify.py ADDED
@@ -0,0 +1,191 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Compare two ink maps from the same input: a reference (e.g. CPU) and a candidate (e.g. MPS).
2
+
3
+ Acceptance follows the GENChase Apple GPU backend
4
+ (https://github.com/ChaseHendrick/GENChase/blob/main/apps/validate/APPLE-GPU.md):
5
+ agreement under a stated tolerance counts only if a deliberately wrong input, the
6
+ control, is caught by the same comparison. Without a control the verdict says so.
7
+
8
+ Default tolerance: villa PR #1865 reported CPU and MPS maps differing by at most 1 of
9
+ 255 gray levels on 0.002% of pixels. The defaults (2 levels, at most 0.01% of pixels
10
+ beyond that) leave margin above that report without accepting a different map.
11
+
12
+ The maps are villa's uint8 TIFFs. Reading them needs numpy and tifffile (and
13
+ imagecodecs for LZW); villa's environment has all three.
14
+ """
15
+
16
+ import math
17
+
18
+ DEFAULT_TOLERANCE = 2
19
+ DEFAULT_MAX_FRACTION = 1e-4
20
+ ROWS_PER_BLOCK = 1024
21
+
22
+ PASS = "pass"
23
+ PASS_UNCONTROLLED = "pass-uncontrolled"
24
+ FAIL = "fail"
25
+ CONTROL_NOT_CAUGHT = "control-not-caught"
26
+
27
+
28
+ # The extra that installs the map tools' dependencies (numpy, tifffile, imagecodecs, zarr, scipy; pyproject.toml).
29
+ MAPS_INSTALL = 'python -m pip install "scrolls-workbench[maps]"'
30
+
31
+ # The command running now, for install hints: (what the user typed, the kit command), such as
32
+ # ("python -m kit auc", "auc"). kit.cli sets it while a command runs; None when kit is used as a library.
33
+ RUNNING = None
34
+
35
+
36
+ class VerifyError(Exception):
37
+ pass
38
+
39
+
40
+ def missing(module):
41
+ """The VerifyError for a map tool that cannot import `module`: the command that needs it, the maps
42
+ extra that installs it, and how to run the command inside villa's environment instead."""
43
+ typed, name = RUNNING if RUNNING else (None, None)
44
+ need = f"{module} is required for {typed}" if typed else f"{module} is required"
45
+ note = " (its zarr needs Python 3.11 or newer)" if module == "zarr" else ""
46
+ return VerifyError(f"{need}. Install the maps extra{note}: {MAPS_INSTALL}, or run inside villa's environment: "
47
+ f"uv run --project \"$VILLA/vesuvius\" --extra models python -m kit {name or 'COMMAND'} ...")
48
+
49
+
50
+ def _numpy():
51
+ try:
52
+ import numpy
53
+ except ImportError as exc:
54
+ raise missing("numpy") from exc
55
+ return numpy
56
+
57
+
58
+ def load_map(path):
59
+ np = _numpy()
60
+ try:
61
+ import tifffile
62
+ except ImportError as exc:
63
+ raise missing("tifffile") from exc
64
+ try:
65
+ array = tifffile.imread(str(path))
66
+ except Exception as exc: # tifffile raises several types, e.g. for LZW without imagecodecs
67
+ raise VerifyError(f"cannot read {path}: {exc}") from exc
68
+ array = np.squeeze(array)
69
+ if array.ndim != 2:
70
+ raise VerifyError(f"{path}: expected a 2D map, got shape {array.shape}")
71
+ return array
72
+
73
+
74
+ def compare(reference, candidate, tolerance=DEFAULT_TOLERANCE):
75
+ """Statistics of candidate minus reference, computed in row blocks to bound memory."""
76
+ np = _numpy()
77
+ if reference.shape != candidate.shape:
78
+ return {"shape_match": False, "reference_shape": list(reference.shape),
79
+ "candidate_shape": list(candidate.shape)}
80
+ n = reference.size
81
+ max_abs = 0.0
82
+ sum_abs = 0.0
83
+ over = 0
84
+ sx = sy = sxx = syy = sxy = 0.0
85
+ for start in range(0, reference.shape[0], ROWS_PER_BLOCK):
86
+ a = reference[start:start + ROWS_PER_BLOCK].astype(np.float64)
87
+ b = candidate[start:start + ROWS_PER_BLOCK].astype(np.float64)
88
+ d = np.abs(b - a)
89
+ # NaN or inf in one map and not the other is a disagreement: d is then NaN or inf, and
90
+ # max() and "d > tolerance" would both pass a NaN by. Equal values (inf and inf) or NaN in
91
+ # both maps at the same pixel agree.
92
+ same = (a == b) | (np.isnan(a) & np.isnan(b))
93
+ bad = ~(d <= tolerance) & ~same
94
+ d = np.where(same, 0.0, d)
95
+ if bad.any() and not np.isfinite(d[bad]).all():
96
+ max_abs = math.inf
97
+ max_abs = max(max_abs, float(d.max()))
98
+ sum_abs += float(d.sum())
99
+ over += int(bad.sum())
100
+ sx += float(a.sum())
101
+ sy += float(b.sum())
102
+ sxx += float((a * a).sum())
103
+ syy += float((b * b).sum())
104
+ sxy += float((a * b).sum())
105
+ cov = sxy - sx * sy / n
106
+ var_a = sxx - sx * sx / n
107
+ var_b = syy - sy * sy / n
108
+ pearson = cov / math.sqrt(var_a * var_b) if var_a > 0 and var_b > 0 else None
109
+ return {
110
+ "shape_match": True,
111
+ "shape": list(reference.shape),
112
+ "pixels": n,
113
+ "tolerance": tolerance,
114
+ "max_abs_diff": max_abs,
115
+ "mean_abs_diff": sum_abs / n,
116
+ "pixels_over_tolerance": over,
117
+ "fraction_over_tolerance": over / n,
118
+ "pearson": pearson,
119
+ }
120
+
121
+
122
+ def agrees(stats, max_fraction=DEFAULT_MAX_FRACTION):
123
+ return bool(stats.get("shape_match")) and stats["fraction_over_tolerance"] <= max_fraction
124
+
125
+
126
+ def verdict(candidate_agrees, control_agrees=None):
127
+ if not candidate_agrees:
128
+ return FAIL
129
+ if control_agrees is None:
130
+ return PASS_UNCONTROLLED
131
+ if control_agrees:
132
+ return CONTROL_NOT_CAUGHT
133
+ return PASS
134
+
135
+
136
+ def verify_arrays(reference, candidate, control=None, tolerance=DEFAULT_TOLERANCE,
137
+ max_fraction=DEFAULT_MAX_FRACTION):
138
+ np = _numpy()
139
+ if reference.dtype.kind == "f" and reference.size and not np.isfinite(reference).any():
140
+ # NaN at the same pixel counts as agreement, so an all-NaN candidate (both devices overflowing,
141
+ # say) would agree with an all-NaN reference and any finite control would look caught
142
+ raise VerifyError("the reference map has no finite values; a broken reference cannot show agreement")
143
+ result = {"candidate": compare(reference, candidate, tolerance), "max_fraction": max_fraction}
144
+ result["candidate_agrees"] = agrees(result["candidate"], max_fraction)
145
+ control_agrees = None
146
+ if control is not None:
147
+ if control.shape != reference.shape:
148
+ # A control of another shape would "disagree" by shape alone and turn any candidate
149
+ # into a pass; it shows nothing about whether the comparison can fail.
150
+ raise VerifyError(f"control shape {tuple(control.shape)} differs from the reference's "
151
+ f"{tuple(reference.shape)}; the control must be the same map made wrongly")
152
+ result["control"] = compare(reference, control, tolerance)
153
+ control_agrees = agrees(result["control"], max_fraction)
154
+ result["control_agrees"] = control_agrees
155
+ result["verdict"] = verdict(result["candidate_agrees"], control_agrees)
156
+ return result
157
+
158
+
159
+ def verify_files(reference, candidate, control=None, tolerance=DEFAULT_TOLERANCE,
160
+ max_fraction=DEFAULT_MAX_FRACTION):
161
+ result = verify_arrays(
162
+ load_map(reference), load_map(candidate),
163
+ None if control is None else load_map(control),
164
+ tolerance, max_fraction,
165
+ )
166
+ result["files"] = {"reference": str(reference), "candidate": str(candidate),
167
+ "control": None if control is None else str(control)}
168
+ return result
169
+
170
+
171
+ EXPLAIN = {
172
+ PASS: "candidate agrees with the reference, and the control was caught",
173
+ PASS_UNCONTROLLED: "candidate agrees, but no control was given, so this comparison was not shown able to fail",
174
+ FAIL: "candidate does not agree with the reference",
175
+ CONTROL_NOT_CAUGHT: "the control also agreed, so this comparison cannot tell maps apart; it proves nothing",
176
+ }
177
+
178
+
179
+ def format_result(result):
180
+ def line(label, stats):
181
+ if not stats.get("shape_match"):
182
+ return f"{label}: shape mismatch {stats['reference_shape']} vs {stats['candidate_shape']}"
183
+ pearson = "n/a" if stats["pearson"] is None else f"{stats['pearson']:.6f}"
184
+ return (f"{label}: max |diff| {stats['max_abs_diff']:.0f}, mean {stats['mean_abs_diff']:.4f}, "
185
+ f"{stats['fraction_over_tolerance']:.6%} of pixels over {stats['tolerance']}, pearson {pearson}")
186
+
187
+ rows = [line("candidate", result["candidate"])]
188
+ if "control" in result:
189
+ rows.append(line("control ", result["control"]))
190
+ rows.append(f"verdict: {result['verdict']} ({EXPLAIN[result['verdict']]})")
191
+ return "\n".join(rows)
requirements.txt ADDED
@@ -0,0 +1,20 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Ink Lens on a Hugging Face ZeroGPU Space (Gradio 6.28.0 and Python 3.12 come from the README card; `spaces` is
2
+ # preinstalled there). The torch, torchvision, numpy, zarr and numcodecs pins are the ones the AutoPipeline ink Space
3
+ # and Scroll Lens run on the same hardware; einops, timm, pyyaml, pynrrd, aiohttp and requests are what villa's
4
+ # vesuvius package imports for flat ink inference (it is downloaded at a pinned commit, see engine.VILLA_COMMIT). mcp
5
+ # and pydantic as Scroll Lens pins them for gradio's MCP server.
6
+ torch==2.13.0
7
+ torchvision==0.28.0
8
+ numpy==2.5.2
9
+ zarr==3.4.1
10
+ numcodecs==0.16.5
11
+ tifffile==2026.9.20
12
+ pynrrd==1.1.3
13
+ einops==0.8.2
14
+ timm==1.0.30
15
+ pyyaml==6.0.3
16
+ requests==2.34.2
17
+ aiohttp==3.14.5
18
+ huggingface_hub==1.33.0
19
+ mcp==1.30.0
20
+ pydantic>=2.11.10,<=2.12.5
samples.json ADDED
@@ -0,0 +1,55 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "note": "Public crops of released segments that are not prize-eligible. Ink Lens reads them anonymously from the open-data bucket when someone runs one; nothing is bundled. Crops are (y0, y1, x0, x1) on the segment's 9 um surface volume, the 640 px windows of densest labeled ink used in docs/results.json. A window chosen with the labels gives a development number, not a blind test.",
3
+ "bucket": "https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com",
4
+ "samples": [
5
+ {
6
+ "id": "0841-w00",
7
+ "title": "PHerc0841 w00 (held out from d9v2 and ink_9um)",
8
+ "scroll": "PHerc0841",
9
+ "segment": "20260220213127-w00",
10
+ "surface_volume": "surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr",
11
+ "labels": "ink-labels/2.403um-volume-20260319124803/20260918",
12
+ "tifxyz": "mesh/20260220213127-on-20250821151531-9.366um.tifxyz",
13
+ "um_per_px": 9.366,
14
+ "surface_shape": [4220, 4760],
15
+ "crop": [2624, 3264, 2688, 3328],
16
+ "role": "development"
17
+ },
18
+ {
19
+ "id": "0841-ag896",
20
+ "title": "PHerc0841 auto-grown 896 (held out from d9v2 and ink_9um)",
21
+ "scroll": "PHerc0841",
22
+ "segment": "20260220214732-auto_grown_20260220144552896",
23
+ "surface_volume": "surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr",
24
+ "labels": "ink-labels/2.403um-volume-20260319124803/20260918",
25
+ "um_per_px": 9.366,
26
+ "surface_shape": [4640, 4720],
27
+ "crop": [2496, 3136, 1600, 2240],
28
+ "role": "development"
29
+ },
30
+ {
31
+ "id": "0841-ag405",
32
+ "title": "PHerc0841 auto-grown 405 (held out from d9v2 and ink_9um)",
33
+ "scroll": "PHerc0841",
34
+ "segment": "20260221022814-auto_grown_20260220174252405",
35
+ "surface_volume": "surface-volumes/9.366um-1.2m-113keV-volume-20250821151531.zarr",
36
+ "labels": "ink-labels/2.403um-volume-20260319124803/20260918",
37
+ "um_per_px": 9.366,
38
+ "surface_shape": [3760, 4900],
39
+ "crop": [1024, 1664, 2496, 3136],
40
+ "role": "development"
41
+ },
42
+ {
43
+ "id": "0139-w035",
44
+ "title": "PHerc0139 w035 (training segment: a pipeline check, not a test)",
45
+ "scroll": "PHerc0139",
46
+ "segment": "20260317000000-w035_2026031718",
47
+ "surface_volume": "surface-volumes/9.362um-1.2m-113keV-volume-20250728140407.zarr",
48
+ "labels": "ink-labels/2.399um-volume-20260102150214/20260918",
49
+ "um_per_px": 9.362,
50
+ "surface_shape": [5820, 5240],
51
+ "crop": [1920, 2560, 2304, 2944],
52
+ "role": "training"
53
+ }
54
+ ]
55
+ }
vc3dout.py ADDED
@@ -0,0 +1,417 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Ink Lens: VC3D's own files for one region of a tifxyz segment (numpy and the standard library only).
2
+
3
+ Every rule below is read from ScrollPrize/villa main 8aa507c12 (volume-cartographer/):
4
+
5
+ - Ink overlay: VC3D reads SEGDIR/ink-detections.json, a JSON array of records whose local_file is relative to SEGDIR
6
+ (apps/VC3D/OpenDataSegmentCache.cpp:651-694). A file with at least one record replaces the list in
7
+ catalog-origin.json's ink_detections, which VC3D reads only when the file is missing or empty, so merge_records
8
+ starts from the file's records, or from that catalog list when the file has none, and replaces only a record for
9
+ the same file. A record is offered on a segment
10
+ only when its segment_id or segment_long_id equals the segment's key (overlays/InkDetectionOverlayController.cpp
11
+ 52-65, 502-510): the catalog ids in meta.json when present, else the segment's id, which is meta.json's uuid for an
12
+ Open Data representation and the folder name otherwise (core/src/Segmentation.cpp:42-56). VC3D hides every
13
+ non-JPEG record in a group that has a JPEG, the group being segment_long_id when set (:41-50, 243-253), and catalog
14
+ maps are JPEGs, so our records carry the key in segment_id only and leave segment_long_id unset.
15
+ - The image is read unchanged; a single-channel 8-bit image is drawn with alpha equal to the pixel value, so 0 is
16
+ transparent (InkDetectionOverlayController.cpp:512-580). It is stretched over the whole segment grid, each axis on
17
+ its own (:395-437), so the PNG covers the whole canvas and its aspect equals the grid's over meta.json's scale.
18
+ - Points: a VC3D point collection file {"vc_pointcollections_json_version": "1", "collections": {id: {name, points:
19
+ {id: {p: [x, y, z], creation_time, wind_a}}, metadata, color}}} (core/src/PointCollections.cpp:36-119, 571-662).
20
+ creation_time is in milliseconds (:226). Loading one replaces every current collection and the file's other
21
+ top-level keys (:647), so merge_points adds to a saved file and keeps those keys. VC3D numbers points across all
22
+ collections (getNextPointId, :856), and a point id held by two collections is ambiguous to the agent bridge
23
+ (AgentBridgeHandlers_points.cpp:94-110), so merged points get ids after every existing one.
24
+ - Grid to voxels: x.tif, y.tif and z.tif hold the voxel position of each grid vertex; a vertex with a -1 coordinate
25
+ is a hole (core/src/QuadSurface.cpp:279) and one with z <= 0 is dropped on load (:1077-1096).
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import json
31
+ import os
32
+ import struct
33
+ import tempfile
34
+ import time
35
+ import zlib
36
+ from pathlib import Path
37
+
38
+ POINTS_VERSION = "1"
39
+ ASPECT_TOL = 0.02 # the canvas aspect may differ from the grid's by 2 % (whole pixels), as kit.villafmt allows
40
+ MAX_CANVAS_SIDE = 16384 # a canvas longer than this is written at a whole-number fraction of the map's resolution
41
+ NOTE = "Model output, not a reading."
42
+
43
+
44
+ class VC3DError(ValueError):
45
+ """A segment or file Ink Lens will not write into; the message says why."""
46
+
47
+
48
+ # ---------------------------------------------------------------- small file helpers
49
+
50
+ def atomic_write(path, data):
51
+ path = Path(path)
52
+ path.parent.mkdir(parents=True, exist_ok=True)
53
+ fd, tmp = tempfile.mkstemp(prefix=path.name + ".", suffix=".part", dir=str(path.parent))
54
+ try:
55
+ with os.fdopen(fd, "wb") as fh:
56
+ fh.write(data if isinstance(data, bytes) else data.encode("utf-8"))
57
+ os.replace(tmp, path)
58
+ except BaseException:
59
+ try:
60
+ os.unlink(tmp)
61
+ except OSError:
62
+ pass
63
+ raise
64
+ return path
65
+
66
+
67
+ def png_bytes(gray):
68
+ """A 2-D uint8 array as an 8-bit grayscale PNG (zlib only)."""
69
+ import numpy as np
70
+ a = np.asarray(gray)
71
+ if a.ndim != 2 or a.dtype != np.uint8 or not a.size:
72
+ raise VC3DError(f"a PNG here is a non-empty 2-D uint8 array, not {a.dtype} {a.shape}")
73
+ h, w = a.shape
74
+ rows = np.zeros((h, w + 1), np.uint8)
75
+ rows[:, 1:] = a
76
+
77
+ def chunk(tag, data):
78
+ return struct.pack(">I", len(data)) + tag + data + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF)
79
+ return (b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 0, 0, 0, 0))
80
+ + chunk(b"IDAT", zlib.compress(rows.tobytes(), 6)) + chunk(b"IEND", b""))
81
+
82
+
83
+ def read_png_gray(data):
84
+ """An 8-bit grayscale, non-interlaced PNG (as png_bytes writes, any filter) as a 2-D uint8 array."""
85
+ import numpy as np
86
+ if data[:8] != b"\x89PNG\r\n\x1a\n":
87
+ raise VC3DError("not a PNG")
88
+ pos, idat, ihdr = 8, b"", None
89
+ while pos < len(data):
90
+ n, tag = struct.unpack(">I4s", data[pos:pos + 8])
91
+ body = data[pos + 8:pos + 8 + n]
92
+ if tag == b"IHDR":
93
+ ihdr = struct.unpack(">IIBBBBB", body)
94
+ elif tag == b"IDAT":
95
+ idat += body
96
+ elif tag == b"IEND":
97
+ break
98
+ pos += 12 + n
99
+ if ihdr is None:
100
+ raise VC3DError("a PNG with no IHDR")
101
+ w, h, depth, ctype, _, _, interlace = ihdr
102
+ if (depth, ctype, interlace) != (8, 0, 0):
103
+ raise VC3DError(f"only 8-bit grayscale non-interlaced PNGs are read here (depth {depth}, type {ctype})")
104
+ raw = np.frombuffer(zlib.decompress(idat), np.uint8).reshape(h, w + 1)
105
+ out = np.zeros((h, w), np.uint8)
106
+ prev = np.zeros(w, np.int32)
107
+ for y in range(h):
108
+ f, line = raw[y, 0], raw[y, 1:].astype(np.int32)
109
+ if f == 0:
110
+ cur = line
111
+ elif f == 2:
112
+ cur = (line + prev) & 255
113
+ else:
114
+ cur = np.zeros(w, np.int32)
115
+ for x in range(w):
116
+ a = cur[x - 1] if x else 0
117
+ b = prev[x]
118
+ c = prev[x - 1] if x else 0
119
+ if f == 1:
120
+ pred = a
121
+ elif f == 3:
122
+ pred = (a + b) // 2
123
+ elif f == 4:
124
+ p = a + b - c
125
+ pa, pb, pc = abs(p - a), abs(p - b), abs(p - c)
126
+ pred = a if pa <= pb and pa <= pc else b if pb <= pc else c
127
+ else:
128
+ raise VC3DError(f"PNG filter type {f}")
129
+ cur[x] = (line[x] + pred) & 255
130
+ out[y] = cur
131
+ prev = cur
132
+ return out
133
+
134
+
135
+ def tiff_size(path):
136
+ """(width, height) of a TIFF from its first IFD (classic or BigTIFF), with no imaging library."""
137
+ with open(path, "rb") as fh:
138
+ head = fh.read(16)
139
+ if head[:2] not in (b"II", b"MM"):
140
+ raise VC3DError(f"{path} is not a TIFF")
141
+ e = "<" if head[:2] == b"II" else ">"
142
+ magic = struct.unpack(e + "H", head[2:4])[0]
143
+ if magic == 42:
144
+ fh.seek(struct.unpack(e + "I", head[4:8])[0])
145
+ n = struct.unpack(e + "H", fh.read(2))[0]
146
+ entries = [fh.read(12) for _ in range(n)]
147
+ fmt = {3: "H", 4: "I"}
148
+ vals = {}
149
+ for ent in entries:
150
+ tag, typ, _ = struct.unpack(e + "HHI", ent[:8])
151
+ if tag in (256, 257) and typ in fmt:
152
+ vals[tag] = struct.unpack(e + fmt[typ], ent[8:8 + struct.calcsize(fmt[typ])])[0]
153
+ elif magic == 43:
154
+ fh.seek(struct.unpack(e + "Q", head[8:16])[0])
155
+ n = struct.unpack(e + "Q", fh.read(8))[0]
156
+ fmt = {3: "H", 4: "I", 16: "Q"}
157
+ vals = {}
158
+ for _ in range(n):
159
+ ent = fh.read(20)
160
+ tag, typ, _ = struct.unpack(e + "HHQ", ent[:12])
161
+ if tag in (256, 257) and typ in fmt:
162
+ vals[tag] = struct.unpack(e + fmt[typ], ent[12:12 + struct.calcsize(fmt[typ])])[0]
163
+ else:
164
+ raise VC3DError(f"{path} is not a TIFF (magic {magic})")
165
+ if 256 not in vals or 257 not in vals:
166
+ raise VC3DError(f"{path}: no image width or height tag")
167
+ return int(vals[256]), int(vals[257])
168
+
169
+
170
+ # ---------------------------------------------------------------- the segment
171
+
172
+ def segment_key(segdir, meta):
173
+ """The key VC3D matches an ink record against: catalog ids in meta.json if any, else the folder name."""
174
+ for k in ("vc_open_data_segment_long_id", "vc_open_data_catalog_segment_lineage_id", "vc_open_data_segment_id"):
175
+ v = meta.get(k) if isinstance(meta, dict) else None
176
+ if isinstance(v, str) and v:
177
+ return v
178
+ if isinstance(meta, dict) and "vc_open_data_representation" in meta:
179
+ u = meta.get("uuid")
180
+ if isinstance(u, str) and u:
181
+ return u
182
+ return Path(segdir).resolve().name
183
+
184
+
185
+ def segment(segdir):
186
+ """What Ink Lens needs to know of a tifxyz folder: key, grid size, scale and the render canvas in pixels."""
187
+ segdir = Path(segdir)
188
+ meta_path = segdir / "meta.json"
189
+ if not meta_path.is_file():
190
+ raise VC3DError(f"{segdir} has no meta.json; give a tifxyz segment folder")
191
+ try:
192
+ meta = json.loads(meta_path.read_text())
193
+ except (OSError, json.JSONDecodeError) as exc:
194
+ raise VC3DError(f"{meta_path}: {exc}") from None
195
+ if not isinstance(meta, dict) or meta.get("format") != "tifxyz":
196
+ raise VC3DError(f"{meta_path}: format is {meta.get('format') if isinstance(meta, dict) else None!r}, "
197
+ "VC3D needs tifxyz")
198
+ for band in ("x.tif", "y.tif", "z.tif"):
199
+ if not (segdir / band).is_file():
200
+ raise VC3DError(f"{segdir} has no {band}")
201
+ cols, rows = tiff_size(segdir / "x.tif")
202
+ sc = meta.get("scale")
203
+ if not (isinstance(sc, list) and len(sc) == 2 and all(isinstance(v, (int, float)) and v > 0 for v in sc)):
204
+ raise VC3DError(f"{meta_path}: scale {sc!r} is not two positive numbers")
205
+ sx, sy = float(sc[0]), float(sc[1])
206
+ return {"dir": str(segdir.resolve()), "key": segment_key(segdir, meta), "meta": meta, "grid": [rows, cols],
207
+ "scale": [sx, sy], "canvas_px": [int(round(cols / sx)), int(round(rows / sy))]}
208
+
209
+
210
+ def canvas(seg, box, map_u8, pool, max_side=MAX_CANVAS_SIDE):
211
+ """(canvas uint8, divisor): the whole segment canvas at the map's resolution, or at 1/k of it when longer than
212
+ max_side, with the region's map placed at box (y, x, h, w) in render pixels and 0 everywhere else."""
213
+ import numpy as np
214
+ cw, ch = seg["canvas_px"]
215
+ k = 1
216
+ while max(cw, ch) / (pool * k) > max_side:
217
+ k += 1
218
+ div = pool * k
219
+ W, H = max(1, int(round(cw / div))), max(1, int(round(ch / div)))
220
+ rows, cols = seg["grid"]
221
+ expected = (cols / seg["scale"][0]) / (rows / seg["scale"][1])
222
+ if abs((W / H) / expected - 1) > ASPECT_TOL:
223
+ raise VC3DError(f"a {W} x {H} canvas would not keep the grid's aspect {expected:.4f}; the segment is too "
224
+ "small for this map resolution")
225
+ m = np.asarray(map_u8)
226
+ if k > 1:
227
+ hh, ww = m.shape[0] // k * k, m.shape[1] // k * k
228
+ m = m[:hh, :ww].reshape(hh // k, k, ww // k, k).max(axis=(1, 3))
229
+ y, x = int(box[0]) // div, int(box[1]) // div
230
+ out = np.zeros((H, W), np.uint8)
231
+ y1, x1 = min(H, y + m.shape[0]), min(W, x + m.shape[1])
232
+ if y >= H or x >= W or y1 <= y or x1 <= x:
233
+ raise VC3DError(f"the region at rows {box[0]}, columns {box[1]} lies outside the segment's canvas {cw} x {ch}")
234
+ out[y:y1, x:x1] = m[:y1 - y, :x1 - x]
235
+ return out, div
236
+
237
+
238
+ def merge_mosaic(path, new):
239
+ """The running maximum of the mosaic at path and a new canvas; a mosaic of another size is replaced."""
240
+ import numpy as np
241
+ path = Path(path)
242
+ if path.is_file():
243
+ try:
244
+ old = read_png_gray(path.read_bytes())
245
+ except VC3DError:
246
+ old = None
247
+ if old is not None and old.shape == new.shape:
248
+ return np.maximum(old, new), True
249
+ return new, False
250
+
251
+
252
+ def merge_records(segdir, records):
253
+ """Add records to SEGDIR/ink-detections.json, keeping every record already there except one for the same
254
+ local_file. Refuses a file that is not a JSON array (VC3D would ignore it, and overwriting would lose it)."""
255
+ segdir = Path(segdir)
256
+ path = segdir / "ink-detections.json"
257
+ old = []
258
+ if path.exists():
259
+ try:
260
+ old = json.loads(path.read_text())
261
+ except (OSError, json.JSONDecodeError) as exc:
262
+ raise VC3DError(f"{path} is not readable JSON ({exc}); refusing to overwrite it") from None
263
+ if not isinstance(old, list):
264
+ raise VC3DError(f"{path} is not a JSON array; refusing to overwrite it")
265
+ if not any(isinstance(r, dict) for r in old):
266
+ old = catalog_records(segdir) # what VC3D shows now; writing the file must not hide it
267
+
268
+ def where(local_file):
269
+ f = Path(local_file)
270
+ return f if f.is_absolute() else (segdir / f).resolve()
271
+
272
+ new_files = {where(r["local_file"]) for r in records}
273
+ kept = [r for r in old if not (isinstance(r, dict) and isinstance(r.get("local_file"), str)
274
+ and where(r["local_file"]) in new_files)]
275
+ out = kept + list(records)
276
+ atomic_write(path, json.dumps(out, indent=2) + "\n")
277
+ return {"file": str(path), "records": len(out), "kept_existing": len(kept)}
278
+
279
+
280
+ def catalog_records(segdir):
281
+ """The ink_detections list of SEGDIR/catalog-origin.json (VC3D's fallback when ink-detections.json is missing or
282
+ empty), or [] when there is none or it does not parse, as VC3D treats it."""
283
+ path = Path(segdir) / "catalog-origin.json"
284
+ try:
285
+ origin = json.loads(path.read_text()) if path.is_file() else None
286
+ except (OSError, json.JSONDecodeError):
287
+ return []
288
+ items = origin.get("ink_detections") if isinstance(origin, dict) else None
289
+ return [r for r in items if isinstance(r, dict)] if isinstance(items, list) else []
290
+
291
+
292
+ def record(seg, local_file, label, sha256, size, extra=None):
293
+ # no segment_long_id: VC3D groups records by it and hides PNGs in a group that has a catalog JPEG
294
+ r = {"local_file": local_file, "label": label, "segment_id": seg["key"], "sample_id": "", "artifact_type": "ink-lens", "ink_lens": {"sha256": sha256, "size": list(size), "note": NOTE}}
295
+ if extra:
296
+ r["ink_lens"].update(extra)
297
+ return r
298
+
299
+
300
+ # ---------------------------------------------------------------- grid and voxels
301
+
302
+ def load_xyz(segdir):
303
+ """The x, y and z bands of a tifxyz folder as one (3, rows, cols) float32 array (needs tifffile)."""
304
+ import numpy as np
305
+ try:
306
+ import tifffile
307
+ except ImportError:
308
+ raise VC3DError("mapping pins onto the segment needs tifffile (pip install tifffile)") from None
309
+ bands = [tifffile.imread(str(Path(segdir) / f"{c}.tif")).astype(np.float32) for c in "xyz"]
310
+ if not (bands[0].shape == bands[1].shape == bands[2].shape):
311
+ raise VC3DError(f"{segdir}: x, y and z bands differ in size")
312
+ return np.stack(bands)
313
+
314
+
315
+ def render_to_grid(seg, r, c):
316
+ """Render pixel (row, column) at scale 1 to fractional grid (row, column)."""
317
+ sx, sy = seg["scale"]
318
+ return r * sy, c * sx
319
+
320
+
321
+ def grid_to_voxel(xyz, gr, gc):
322
+ """Bilinear voxel position [x, y, z] at fractional grid (row, column), or None on or next to a hole."""
323
+ import math
324
+ _, rows, cols = xyz.shape
325
+ if not (0 <= gr <= rows - 1 and 0 <= gc <= cols - 1):
326
+ return None
327
+ r0, c0 = int(math.floor(gr)), int(math.floor(gc))
328
+ r1, c1 = min(r0 + 1, rows - 1), min(c0 + 1, cols - 1)
329
+ fr, fc = gr - r0, gc - c0
330
+ corners = [xyz[:, r0, c0], xyz[:, r0, c1], xyz[:, r1, c0], xyz[:, r1, c1]]
331
+ for v in corners:
332
+ if (v == -1).any() or v[2] <= 0:
333
+ return None
334
+ top = corners[0] * (1 - fc) + corners[1] * fc
335
+ bot = corners[2] * (1 - fc) + corners[3] * fc
336
+ p = top * (1 - fr) + bot * fr
337
+ return [round(float(p[0]), 3), round(float(p[1]), 3), round(float(p[2]), 3)]
338
+
339
+
340
+ def voxel_to_grid(xyz, point):
341
+ """The grid vertex nearest a voxel point [x, y, z], as (row, column, distance in voxels); holes are skipped."""
342
+ import numpy as np
343
+ pts = xyz.reshape(3, -1).T
344
+ valid = ~(pts == -1).any(axis=1) & (pts[:, 2] > 0)
345
+ if not valid.any():
346
+ raise VC3DError("the segment has no valid vertex")
347
+ d = np.full(pts.shape[0], np.inf, np.float64)
348
+ d[valid] = np.linalg.norm(pts[valid] - np.asarray(point, np.float32), axis=1)
349
+ i = int(np.argmin(d))
350
+ return divmod(i, xyz.shape[2]) + (float(d[i]),)
351
+
352
+
353
+ # ---------------------------------------------------------------- point collections
354
+
355
+ def points_doc(name, points, color=(0.2, 0.9, 1.0), metadata=None):
356
+ """A VC3D point collection document with one collection."""
357
+ now = int(time.time() * 1000) # milliseconds, as VC3D stamps its own points
358
+ pts = {str(i + 1): {"p": list(p), "creation_time": now, "wind_a": None} for i, p in enumerate(points)}
359
+ md = {"winding_is_absolute": False}
360
+ md.update(metadata or {})
361
+ return {"vc_pointcollections_json_version": POINTS_VERSION,
362
+ "collections": {"1": {"name": name, "points": pts, "metadata": md, "color": list(color)}}}
363
+
364
+
365
+ def check_points_doc(doc):
366
+ """Problems VC3D's loader would have with a point collection document (empty list when it loads)."""
367
+ out = []
368
+ if not isinstance(doc, dict) or doc.get("vc_pointcollections_json_version") != POINTS_VERSION:
369
+ return [f"vc_pointcollections_json_version must be {POINTS_VERSION!r}"]
370
+ cols = doc.get("collections")
371
+ if not isinstance(cols, dict):
372
+ return ["collections is not an object"]
373
+ for cid, c in cols.items():
374
+ if not str(cid).isdigit():
375
+ out.append(f"collection id {cid!r} is not a whole number")
376
+ if not isinstance(c, dict) or not isinstance(c.get("name"), str):
377
+ out.append(f"collection {cid} has no name")
378
+ continue
379
+ pts = c.get("points", {})
380
+ if not isinstance(pts, dict):
381
+ out.append(f"collection {cid} points is not an object")
382
+ continue
383
+ for pid, p in pts.items():
384
+ if not str(pid).isdigit():
385
+ out.append(f"point id {pid!r} is not a whole number")
386
+ xyz = p.get("p") if isinstance(p, dict) else None
387
+ if not (isinstance(xyz, list) and len(xyz) == 3 and all(isinstance(v, (int, float)) for v in xyz)):
388
+ out.append(f"collection {cid} point {pid} has no p [x, y, z]")
389
+ elif isinstance(p, dict) and p.get("wind_a") is not None and not isinstance(p["wind_a"], (int, float)):
390
+ out.append(f"collection {cid} point {pid} has a wind_a that is neither a number nor null")
391
+ return out
392
+
393
+
394
+ def merge_points(existing, new):
395
+ """existing (a document VC3D saved, or None) plus every collection of new: collections renumbered after the
396
+ existing collection ids, points after every existing point id (VC3D's ids are unique across collections), the
397
+ saved file's other top-level keys kept; a collection of the same name is replaced."""
398
+ if existing is None:
399
+ existing = {"vc_pointcollections_json_version": POINTS_VERSION, "collections": {}}
400
+ probs = check_points_doc(existing)
401
+ if probs:
402
+ raise VC3DError("the saved point collections are not loadable: " + "; ".join(probs))
403
+ cols = dict(existing["collections"])
404
+ names = {c["name"] for c in new["collections"].values()}
405
+ cols = {k: v for k, v in cols.items() if v.get("name") not in names}
406
+ nxt = max([int(k) for k in cols] + [0]) + 1
407
+ pid = max([int(p) for c in cols.values() for p in (c.get("points") or {})] + [0]) + 1
408
+ for c in new["collections"].values():
409
+ pts = {}
410
+ for _, p in sorted((c.get("points") or {}).items(), key=lambda kv: int(kv[0])):
411
+ pts[str(pid)] = p
412
+ pid += 1
413
+ cols[str(nxt)] = dict(c, points=pts)
414
+ nxt += 1
415
+ out = {k: v for k, v in existing.items() if k not in ("vc_pointcollections_json_version", "collections")}
416
+ out.update({"vc_pointcollections_json_version": POINTS_VERSION, "collections": cols})
417
+ return out
volio.py ADDED
@@ -0,0 +1,262 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Ink Lens: reading a region of a surface volume, and pooling it to the 9.6 um grid the ink models expect.
2
+
3
+ numpy only. Reads, layers first (layers, rows, columns):
4
+ - a zarr array or OME-Zarr group, local or over HTTPS (the Vesuvius Challenge open-data bucket stores segment surface
5
+ volumes as uncompressed zarr v2, which this reads with no zarr package; other codecs use the zarr package if it
6
+ is installed);
7
+ - a .npy, a .npz (array "volume") or a multi-page .tif (tifffile).
8
+
9
+ Pooling follows the organizers' prepare_9um_isotropic_input.py for a 2.4 um render: mean over k x k pixels in each
10
+ layer and mean over k layers (k = 4 for 2.4 um to 9.6 um). A render already near 9.6 um is used as it is (k = 1).
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import json
16
+ import urllib.error
17
+ import urllib.request
18
+ from concurrent.futures import ThreadPoolExecutor
19
+ from pathlib import Path
20
+
21
+ BUCKET = "https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com"
22
+ TARGET_UM = 9.6
23
+ USER_AGENT = "ink-lens/0.1"
24
+
25
+
26
+ class VolumeError(ValueError):
27
+ """An input the reader refuses; the message says why."""
28
+
29
+
30
+ # ---------------------------------------------------------------- pooling
31
+
32
+ def pool_factor(um_per_px):
33
+ """The integer factor that brings a render of um_per_px close to 9.6 um: 1 for 7 um and above, else the nearest
34
+ whole number of 9.6 / um_per_px (4 for 2.4 um)."""
35
+ um = float(um_per_px)
36
+ if not um > 0:
37
+ raise VolumeError(f"pixel size {um_per_px} um must be positive")
38
+ if um >= 7.0:
39
+ return 1
40
+ return max(1, int(round(TARGET_UM / um)))
41
+
42
+
43
+ def pool(volume, k):
44
+ """Mean over k layers and k x k pixels, dropping a remainder at the far edge of each axis; uint8 out."""
45
+ import numpy as np
46
+ a = np.asarray(volume)
47
+ if a.ndim != 3:
48
+ raise VolumeError(f"a surface volume has 3 axes (layers, rows, columns), this one has {a.ndim}")
49
+ k = int(k)
50
+ if k == 1:
51
+ return np.ascontiguousarray(a)
52
+ L, H, W = (s // k * k for s in a.shape)
53
+ if min(L, H, W) == 0:
54
+ raise VolumeError(f"a {a.shape} volume is smaller than one {k} x {k} x {k} block")
55
+ b = a[:L, :H, :W].astype(np.float32).reshape(L // k, k, H // k, k, W // k, k).mean(axis=(1, 3, 5))
56
+ if a.dtype == np.uint8:
57
+ return np.clip(np.rint(b), 0, 255).astype(np.uint8)
58
+ return b
59
+
60
+
61
+ def to_uint8(volume):
62
+ """uint8 as it is; uint16 scaled by 1/257 (the bucket's 16-bit volumes map 0..65535 to 0..255 this way)."""
63
+ import numpy as np
64
+ a = np.asarray(volume)
65
+ if a.dtype == np.uint8:
66
+ return a
67
+ if a.dtype == np.uint16:
68
+ return (a // 257).astype(np.uint8)
69
+ raise VolumeError(f"type {a.dtype}: give a uint8 or uint16 surface volume")
70
+
71
+
72
+ # ---------------------------------------------------------------- zarr over HTTPS or on disk
73
+
74
+ def _get(url, timeout=60, tries=3):
75
+ """Bytes at url, or None for a missing key (HTTP 404, S3 NoSuchKey)."""
76
+ last = None
77
+ for _ in range(tries):
78
+ try:
79
+ req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
80
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
81
+ return resp.read()
82
+ except urllib.error.HTTPError as exc:
83
+ if exc.code == 404:
84
+ return None
85
+ last = exc
86
+ except (urllib.error.URLError, TimeoutError, OSError) as exc:
87
+ last = exc
88
+ raise VolumeError(f"cannot read {url}: {last}")
89
+
90
+
91
+ def _read(base, key, fetch=_get):
92
+ if str(base).startswith(("http://", "https://")):
93
+ return fetch(f"{str(base).rstrip('/')}/{key}")
94
+ p = Path(base) / key
95
+ return p.read_bytes() if p.is_file() else None
96
+
97
+
98
+ class ZarrArray:
99
+ """One zarr array (v2 or v3), local or remote. Uncompressed chunks are decoded here; compressed ones through
100
+ numcodecs (v2) when it is installed."""
101
+
102
+ def __init__(self, base, fetch=_get):
103
+ self.base, self.fetch = str(base).rstrip("/"), fetch
104
+ meta = _read(self.base, ".zarray", fetch)
105
+ if meta is not None:
106
+ m = json.loads(meta)
107
+ self.version = 2
108
+ self.shape, self.chunks = tuple(m["shape"]), tuple(m["chunks"])
109
+ self.dtype = m["dtype"]
110
+ self.fill = m.get("fill_value") or 0
111
+ self.order = m.get("order", "C")
112
+ self.sep = m.get("dimension_separator", ".")
113
+ self.compressor, self.filters = m.get("compressor"), m.get("filters")
114
+ else:
115
+ meta = _read(self.base, "zarr.json", fetch)
116
+ if meta is None:
117
+ raise VolumeError(f"{self.base} is not a zarr array (no .zarray or zarr.json)")
118
+ m = json.loads(meta)
119
+ if m.get("node_type") != "array":
120
+ raise VolumeError(f"{self.base} is a zarr group, not an array")
121
+ self.version = 3
122
+ self.shape = tuple(m["shape"])
123
+ self.chunks = tuple(m["chunk_grid"]["configuration"]["chunk_shape"])
124
+ self.dtype = {"uint8": "|u1", "uint16": "<u2"}.get(m["data_type"], m["data_type"])
125
+ self.fill = m.get("fill_value") or 0
126
+ self.order = "C"
127
+ enc = m.get("chunk_key_encoding", {})
128
+ self.sep = enc.get("configuration", {}).get("separator", "/")
129
+ self.prefix = "c" + self.sep if enc.get("name", "default") == "default" else ""
130
+ codecs = [c.get("name") for c in m.get("codecs", [])]
131
+ self.compressor = None if set(codecs) <= {"bytes", "transpose"} else codecs
132
+ self.filters = None
133
+ if len(self.shape) != 3:
134
+ raise VolumeError(f"{self.base} has {len(self.shape)} axes; a surface volume has 3 (layers, rows, columns)")
135
+ self.chunks_read = 0
136
+
137
+ def _key(self, idx):
138
+ key = self.sep.join(str(i) for i in idx)
139
+ return (self.prefix + key) if self.version == 3 else key
140
+
141
+ def _decode(self, raw):
142
+ import numpy as np
143
+ if self.compressor is not None or self.filters:
144
+ if self.version != 2:
145
+ raise VolumeError(f"{self.base}: zarr v3 codecs {self.compressor} need the zarr package; "
146
+ "read it with zarr and pass a .npy instead")
147
+ try:
148
+ import numcodecs
149
+ except ImportError:
150
+ raise VolumeError(f"{self.base} is compressed ({self.compressor.get('id')}); install numcodecs") \
151
+ from None
152
+ raw = numcodecs.get_codec(self.compressor).decode(raw)
153
+ for f in reversed(self.filters or []):
154
+ raw = numcodecs.get_codec(f).decode(raw)
155
+ a = np.frombuffer(raw, dtype=np.dtype(self.dtype))
156
+ n = int(np.prod(self.chunks))
157
+ if a.size != n:
158
+ raise VolumeError(f"{self.base}: a chunk holds {a.size} values, not {n}")
159
+ return a.reshape(self.chunks, order=self.order)
160
+
161
+ def read(self, z, y, x, workers=8):
162
+ """The box [z0, z1) x [y0, y1) x [x0, x1) as a numpy array; missing chunks are the fill value."""
163
+ import numpy as np
164
+ box = [z, y, x]
165
+ for (a, b), n in zip(box, self.shape):
166
+ if not 0 <= a < b <= n:
167
+ raise VolumeError(f"box {box} is outside the volume's shape {self.shape}")
168
+ out = np.full([b - a for a, b in box], self.fill, dtype=np.dtype(self.dtype))
169
+ ranges = [range(a // c, (b - 1) // c + 1) for (a, b), c in zip(box, self.chunks)]
170
+ keys = [(i, j, k) for i in ranges[0] for j in ranges[1] for k in ranges[2]]
171
+
172
+ def one(idx):
173
+ return idx, _read(self.base, self._key(idx), self.fetch)
174
+
175
+ with ThreadPoolExecutor(max_workers=workers) as pool_:
176
+ for idx, raw in pool_.map(one, keys):
177
+ if raw is None:
178
+ continue
179
+ self.chunks_read += 1
180
+ chunk = self._decode(raw)
181
+ src, dst = [], []
182
+ for (a, b), c, i in zip(box, self.chunks, idx):
183
+ lo, hi = max(a, i * c), min(b, (i + 1) * c)
184
+ src.append(slice(lo - i * c, hi - i * c))
185
+ dst.append(slice(lo - a, hi - a))
186
+ out[tuple(dst)] = chunk[tuple(src)]
187
+ return out
188
+
189
+
190
+ def open_zarr(path, fetch=_get):
191
+ """A zarr array, or level 0 of an OME-Zarr group (the first dataset of its multiscales)."""
192
+ path = str(path).rstrip("/")
193
+ try:
194
+ return ZarrArray(path, fetch)
195
+ except VolumeError as exc:
196
+ if "is not a zarr array" not in str(exc) and "is a zarr group" not in str(exc):
197
+ raise
198
+ attrs = _read(path, ".zattrs", fetch) or b"{}"
199
+ a = json.loads(attrs)
200
+ if "multiscales" not in a:
201
+ z3 = _read(path, "zarr.json", fetch)
202
+ a = (json.loads(z3).get("attributes", {}).get("ome", {}) if z3 else {}) or a
203
+ try:
204
+ level = a["multiscales"][0]["datasets"][0]["path"]
205
+ except (KeyError, IndexError, TypeError):
206
+ level = "0"
207
+ return ZarrArray(f"{path}/{level}", fetch)
208
+
209
+
210
+ # ---------------------------------------------------------------- whole files
211
+
212
+ MAX_FILE_BYTES = 2 << 30
213
+
214
+
215
+ def read_file(path, box=None):
216
+ """A .npy, .npz (array "volume") or multi-page .tif as a (layers, rows, columns) array; box (y, x, h, w) crops
217
+ rows and columns after reading (a .npy is memory-mapped, so only the box is read)."""
218
+ import numpy as np
219
+ p = Path(path)
220
+ suffix = p.suffix.lower()
221
+ if suffix == ".npy":
222
+ a = np.load(p, mmap_mode="r", allow_pickle=False)
223
+ elif suffix == ".npz":
224
+ with np.load(p, allow_pickle=False) as z:
225
+ if "volume" not in z:
226
+ raise VolumeError(f"{p}: an .npz needs an array named 'volume'; it has {list(z)}")
227
+ a = z["volume"]
228
+ elif suffix in (".tif", ".tiff"):
229
+ try:
230
+ import tifffile
231
+ except ImportError:
232
+ raise VolumeError("reading a .tif needs tifffile (pip install tifffile)") from None
233
+ a = tifffile.imread(str(p))
234
+ else:
235
+ raise VolumeError(f"{p}: give a .zarr, .npy, .npz or multi-page .tif surface volume")
236
+ if a.ndim != 3:
237
+ raise VolumeError(f"{p} has {a.ndim} axes; a surface volume has 3 (layers, rows, columns)")
238
+ if box is not None:
239
+ y, x, h, w = box
240
+ if not (0 <= y and 0 <= x and y + h <= a.shape[1] and x + w <= a.shape[2]):
241
+ raise VolumeError(f"box rows {y}..{y + h}, columns {x}..{x + w} is outside the {a.shape[1:]} volume")
242
+ a = a[:, y:y + h, x:x + w]
243
+ return np.ascontiguousarray(a)
244
+
245
+
246
+ def read_region(source, box, layers=None, fetch=_get):
247
+ """The region box (y, x, h, w) of a surface volume, all its layers (or layers=(z0, z1)), as a numpy array.
248
+ source: a zarr path or URL (array or OME-Zarr group), or a .npy, .npz or .tif file."""
249
+ s = str(source)
250
+ if s.rstrip("/").endswith(".zarr") or s.startswith(("http://", "https://")) or Path(s).is_dir():
251
+ arr = open_zarr(s, fetch)
252
+ z0, z1 = layers if layers else (0, arr.shape[0])
253
+ y, x, h, w = box
254
+ data = arr.read((z0, z1), (y, y + h), (x, x + w))
255
+ return data, {"source": s, "shape": list(arr.shape), "chunks_read": arr.chunks_read}
256
+ data = read_file(s, box)
257
+ if layers:
258
+ data = data[layers[0]:layers[1]]
259
+ return data, {"source": s}
260
+
261
+
262
+ __all__ = ["VolumeError", "pool_factor", "pool", "to_uint8", "ZarrArray", "open_zarr", "read_file", "read_region"]