Ink Lens 0.1.0
Browse files- CONNECT.md +108 -0
- LICENSE +201 -0
- NOTICE +29 -0
- README.md +105 -6
- app.py +373 -0
- bridge.py +116 -0
- connect.html +85 -0
- connect.json +64 -0
- engine.py +541 -0
- gate.py +138 -0
- inklens.py +627 -0
- kit/__init__.py +7 -0
- kit/auc.py +345 -0
- kit/fetch.py +126 -0
- kit/layers.py +147 -0
- kit/verify.py +191 -0
- requirements.txt +20 -0
- samples.json +55 -0
- vc3dout.py +417 -0
- 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:
|
| 5 |
-
colorTo:
|
| 6 |
sdk: gradio
|
| 7 |
-
sdk_version: 6.
|
| 8 |
-
python_version:
|
| 9 |
app_file: app.py
|
| 10 |
pinned: false
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11 |
---
|
| 12 |
|
| 13 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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 "zarr>=3" fsspec aiohttp
|
| 25 |
+
import zarr
|
| 26 |
+
|
| 27 |
+
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
|
| 28 |
+
a = root["0"] # 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'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 "vesuvius[volume-only]"
|
| 33 |
+
from vesuvius import Volume
|
| 34 |
+
|
| 35 |
+
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
|
| 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 = "https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHerc0841/segments/20260220213127-w00/mesh/20260220213127-on-20250821151531-9.366um.tifxyz"
|
| 50 |
+
meta = json.load(urllib.request.urlopen(T + "/meta.json")) # scale, bbox, format
|
| 51 |
+
get = lambda c: tifffile.imread(io.BytesIO(urllib.request.urlopen(f"{T}/{c}.tif").read()))
|
| 52 |
+
xyz = np.stack([get(c) for c in "xyz"], -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("SharpMeow/ink-lens")
|
| 62 |
+
result = client.predict(sample_id="0841-w00", size=640, reader="d9v2", windows=3, api_name="/lens_sample")</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("SharpMeow/ink-lens")
|
| 68 |
+
result = client.predict(api_name="/list_samples")</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 'Content-Type: application/json' \
|
| 72 |
+
-d '{"data": ["0841-w00", 640, "d9v2", 3]}' | python3 -c 'import json,sys; print(json.load(sys.stdin)["event_id"])')
|
| 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 |
+
"mcpServers": {
|
| 77 |
+
"ink-lens": {
|
| 78 |
+
"url": "https://sharpmeow-ink-lens.hf.space/gradio_api/mcp/sse"
|
| 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"]
|