nuscope-tomo 0.3.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- nuscope_tomo-0.3.1/LICENSE +21 -0
- nuscope_tomo-0.3.1/PKG-INFO +187 -0
- nuscope_tomo-0.3.1/README.md +138 -0
- nuscope_tomo-0.3.1/nuscope_tomo/__init__.py +7 -0
- nuscope_tomo-0.3.1/nuscope_tomo/advisor.py +192 -0
- nuscope_tomo-0.3.1/nuscope_tomo/ai/__init__.py +12 -0
- nuscope_tomo-0.3.1/nuscope_tomo/ai/n2v.py +109 -0
- nuscope_tomo-0.3.1/nuscope_tomo/ai/segment.py +161 -0
- nuscope_tomo-0.3.1/nuscope_tomo/ai/unet.py +79 -0
- nuscope_tomo-0.3.1/nuscope_tomo/analyze/__init__.py +8 -0
- nuscope_tomo-0.3.1/nuscope_tomo/analyze/confidence.py +208 -0
- nuscope_tomo-0.3.1/nuscope_tomo/analyze/materials.py +274 -0
- nuscope_tomo-0.3.1/nuscope_tomo/analyze/objects.py +133 -0
- nuscope_tomo-0.3.1/nuscope_tomo/analyze/phase.py +144 -0
- nuscope_tomo-0.3.1/nuscope_tomo/analyze/quality.py +135 -0
- nuscope_tomo-0.3.1/nuscope_tomo/autonomy/__init__.py +6 -0
- nuscope_tomo-0.3.1/nuscope_tomo/autonomy/agent.py +261 -0
- nuscope_tomo-0.3.1/nuscope_tomo/autonomy/instrument.py +252 -0
- nuscope_tomo-0.3.1/nuscope_tomo/autonomy/twin.py +116 -0
- nuscope_tomo-0.3.1/nuscope_tomo/chem/__init__.py +4 -0
- nuscope_tomo-0.3.1/nuscope_tomo/chem/eds.py +253 -0
- nuscope_tomo-0.3.1/nuscope_tomo/chem/simulate.py +55 -0
- nuscope_tomo-0.3.1/nuscope_tomo/cli.py +88 -0
- nuscope_tomo-0.3.1/nuscope_tomo/cohort.py +164 -0
- nuscope_tomo-0.3.1/nuscope_tomo/core/__init__.py +6 -0
- nuscope_tomo-0.3.1/nuscope_tomo/core/recipe.py +202 -0
- nuscope_tomo-0.3.1/nuscope_tomo/core/registry.py +66 -0
- nuscope_tomo-0.3.1/nuscope_tomo/core/volume.py +214 -0
- nuscope_tomo-0.3.1/nuscope_tomo/io/__init__.py +4 -0
- nuscope_tomo-0.3.1/nuscope_tomo/io/stack.py +139 -0
- nuscope_tomo-0.3.1/nuscope_tomo/live.py +221 -0
- nuscope_tomo-0.3.1/nuscope_tomo/mcp.py +129 -0
- nuscope_tomo-0.3.1/nuscope_tomo/preprocess/__init__.py +7 -0
- nuscope_tomo-0.3.1/nuscope_tomo/preprocess/_util.py +37 -0
- nuscope_tomo-0.3.1/nuscope_tomo/preprocess/align.py +186 -0
- nuscope_tomo-0.3.1/nuscope_tomo/preprocess/correct.py +114 -0
- nuscope_tomo-0.3.1/nuscope_tomo/preprocess/denoise.py +79 -0
- nuscope_tomo-0.3.1/nuscope_tomo/preprocess/geometry.py +125 -0
- nuscope_tomo-0.3.1/nuscope_tomo/segment/__init__.py +6 -0
- nuscope_tomo-0.3.1/nuscope_tomo/segment/classifier.py +208 -0
- nuscope_tomo-0.3.1/nuscope_tomo/segment/objects.py +125 -0
- nuscope_tomo-0.3.1/nuscope_tomo/segment/threshold.py +51 -0
- nuscope_tomo-0.3.1/nuscope_tomo/sparse/__init__.py +16 -0
- nuscope_tomo-0.3.1/nuscope_tomo/sparse/active.py +103 -0
- nuscope_tomo-0.3.1/nuscope_tomo/sparse/dkl.py +115 -0
- nuscope_tomo-0.3.1/nuscope_tomo/sparse/pansharpen.py +115 -0
- nuscope_tomo-0.3.1/nuscope_tomo/studio/__init__.py +1 -0
- nuscope_tomo-0.3.1/nuscope_tomo/studio/server.py +431 -0
- nuscope_tomo-0.3.1/nuscope_tomo/studio/static/app.js +488 -0
- nuscope_tomo-0.3.1/nuscope_tomo/studio/static/charts.js +408 -0
- nuscope_tomo-0.3.1/nuscope_tomo/studio/static/gl.js +286 -0
- nuscope_tomo-0.3.1/nuscope_tomo/studio/static/index.html +338 -0
- nuscope_tomo-0.3.1/nuscope_tomo/studio/static/pages.js +422 -0
- nuscope_tomo-0.3.1/nuscope_tomo/studio/static/shell.js +137 -0
- nuscope_tomo-0.3.1/nuscope_tomo/studio/static/style.css +324 -0
- nuscope_tomo-0.3.1/nuscope_tomo/viz/__init__.py +4 -0
- nuscope_tomo-0.3.1/nuscope_tomo/viz/figures.py +110 -0
- nuscope_tomo-0.3.1/nuscope_tomo/viz/render.py +341 -0
- nuscope_tomo-0.3.1/nuscope_tomo.egg-info/PKG-INFO +187 -0
- nuscope_tomo-0.3.1/nuscope_tomo.egg-info/SOURCES.txt +66 -0
- nuscope_tomo-0.3.1/nuscope_tomo.egg-info/dependency_links.txt +1 -0
- nuscope_tomo-0.3.1/nuscope_tomo.egg-info/entry_points.txt +8 -0
- nuscope_tomo-0.3.1/nuscope_tomo.egg-info/requires.txt +26 -0
- nuscope_tomo-0.3.1/nuscope_tomo.egg-info/top_level.txt +1 -0
- nuscope_tomo-0.3.1/pyproject.toml +71 -0
- nuscope_tomo-0.3.1/setup.cfg +4 -0
- nuscope_tomo-0.3.1/tests/test_mcp_plugin.py +53 -0
- nuscope_tomo-0.3.1/tests/test_pipeline.py +407 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Roberto dos Reis (@rmsreis)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: nuscope-tomo
|
|
3
|
+
Version: 0.3.1
|
|
4
|
+
Summary: Open FIB-SEM slice-and-view tomography: alignment, artifact correction, ML segmentation, 3D quantification and correlative EDS chemistry, with a browser-based Studio.
|
|
5
|
+
Author-email: Roberto dos Reis <robertomsreis@gmail.com>
|
|
6
|
+
Maintainer: Roberto dos Reis (@rmsreis)
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
Project-URL: Homepage, https://github.com/NUANCE-IT/NUScope-TOMO
|
|
9
|
+
Project-URL: Issues, https://github.com/NUANCE-IT/NUScope-TOMO/issues
|
|
10
|
+
Project-URL: NUScope, https://nuance-it.github.io/NUScope/
|
|
11
|
+
Project-URL: Author, https://github.com/rmsreis
|
|
12
|
+
Keywords: FIB-SEM,slice and view,tomography,segmentation,EDS,microscopy,Avizo alternative,materials science
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: Image Processing
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
Requires-Dist: numpy>=1.26
|
|
25
|
+
Requires-Dist: scipy>=1.11
|
|
26
|
+
Requires-Dist: scikit-image>=0.24
|
|
27
|
+
Requires-Dist: scikit-learn>=1.4
|
|
28
|
+
Requires-Dist: dask[array]>=2024.1
|
|
29
|
+
Requires-Dist: zarr>=3.0
|
|
30
|
+
Requires-Dist: tifffile
|
|
31
|
+
Requires-Dist: imageio
|
|
32
|
+
Requires-Dist: imageio-ffmpeg
|
|
33
|
+
Requires-Dist: pywavelets
|
|
34
|
+
Requires-Dist: pandas
|
|
35
|
+
Requires-Dist: pyyaml
|
|
36
|
+
Requires-Dist: matplotlib
|
|
37
|
+
Requires-Dist: pyvista>=0.44
|
|
38
|
+
Requires-Dist: pyamg
|
|
39
|
+
Requires-Dist: fastapi
|
|
40
|
+
Requires-Dist: uvicorn[standard]
|
|
41
|
+
Provides-Extra: dev
|
|
42
|
+
Requires-Dist: pytest; extra == "dev"
|
|
43
|
+
Requires-Dist: httpx; extra == "dev"
|
|
44
|
+
Requires-Dist: build; extra == "dev"
|
|
45
|
+
Requires-Dist: twine; extra == "dev"
|
|
46
|
+
Provides-Extra: ai
|
|
47
|
+
Requires-Dist: torch>=2.2; extra == "ai"
|
|
48
|
+
Dynamic: license-file
|
|
49
|
+
|
|
50
|
+
# NUScope-TOMO
|
|
51
|
+
|
|
52
|
+
**Open FIB-SEM slice-and-view tomography — from raw slices to quantified, chemically
|
|
53
|
+
resolved 3D microstructure.**
|
|
54
|
+
|
|
55
|
+
Created by **Roberto dos Reis ([@rmsreis](https://github.com/rmsreis))** · NUANCE Center,
|
|
56
|
+
Northwestern University · [NUANCE-IT/NUScope-TOMO](https://github.com/NUANCE-IT/NUScope-TOMO)
|
|
57
|
+
|
|
58
|
+
NUScope-TOMO is an open alternative to **Thermo Fisher Avizo** for FIB-SEM in materials
|
|
59
|
+
science. It covers import, pre-processing (with a guided FIB-SEM wizard), AI segmentation,
|
|
60
|
+
quantification, triple-phase boundaries, pore/particle networks, transport simulation,
|
|
61
|
+
visualization/animation and recipes. It also adds correlative EDS chemistry. Everything is
|
|
62
|
+
available as code, as reproducible YAML recipes and in a browser-based UI.
|
|
63
|
+
[PLAN.md](PLAN.md) maps each Avizo capability to its module.
|
|
64
|
+
|
|
65
|
+
<p>
|
|
66
|
+
<img src="docs/images/09_phases_3d.jpg" width="49%" alt="Phase surfaces with cut-away">
|
|
67
|
+
<img src="docs/images/10_particles_3d.jpg" width="49%" alt="Particles coloured by size">
|
|
68
|
+
</p>
|
|
69
|
+
|
|
70
|
+
*FIB-SEM sample 335 (812 slices, 20 × 5 × 5 nm voxels) processed by `examples/fib_sem_335.yaml`
|
|
71
|
+
in under 5 minutes: dark phase with a grey-value cut-away (left) and 1 414 separated particles
|
|
72
|
+
coloured by equivalent diameter (right).*
|
|
73
|
+
|
|
74
|
+
<p>
|
|
75
|
+
<img src="docs/images/14_transport_field.jpg" width="49%" alt="Simulated diffusion through the grey phase">
|
|
76
|
+
<img src="docs/images/15_contact_network.jpg" width="49%" alt="Particle contact network">
|
|
77
|
+
</p>
|
|
78
|
+
|
|
79
|
+
*Materials analyses: steady-state diffusion through the matrix phase (left, tortuosity factor 1.4
|
|
80
|
+
along Z, 3.8–3.9 across) and the contact network of the dark-phase particles (right, mean
|
|
81
|
+
coordination 3.0).*
|
|
82
|
+
|
|
83
|
+
| Stage | What you get |
|
|
84
|
+
|---|---|
|
|
85
|
+
| **Import** | TIFF/PNG folders (natural sort), multipage TIFF, Thermo Fisher pixel-size tags, streamed into chunked Zarr v3, so stacks larger than RAM are fine |
|
|
86
|
+
| **Pre-processing** | block-face auto-crop (Pt cap / trench / padding), multi-baseline drift solve with already-registered detection, wavelet–FFT curtain removal, shading flattening, slice brightness normalisation, NLM / TV / anisotropic 3D denoising, binning, isotropic resampling, 52° tilt calibration |
|
|
87
|
+
| **Segmentation** | Otsu / multi-Otsu / hysteresis, **random-forest classifier trained from a few scribbles** (41 multi-scale features), majority smoothing, watershed separation of touching particles |
|
|
88
|
+
| **Quantification** | per object: volume, surface area, equivalent diameter, sphericity, solidity, Feret, ellipsoid axes, elongation/flatness, orientation, nearest neighbour, intensity/element means. Per phase: volume fraction, specific surface, interface density, Euler number, percolation, geodesic tortuosity, continuous size distribution |
|
|
89
|
+
| **Materials analyses** | triple-phase boundary length density (total / active), steady-state diffusion & conduction solver (D_eff/D₀, tortuosity factor, MacMullin number; Avizo XLab counterpart), pore- and particle-network model (throat/contact sizes, coordination numbers) |
|
|
90
|
+
| **Beyond Avizo** | **data-health inspector** (per-slice SNR, sharpness, curtaining, drift, blank/duplicate slices, automatic slice-thickness check), **uncertainty on every number** (integral-range sampling error, ±1-voxel segmentation sensitivity, representative-volume size), **live acquisition mode** (`nuscope-tomo watch`: analyse while the FIB mills, tells you when precision is reached), **self-supervised Noise2Void** denoising and a **2.5D U-Net** trained from scribbles (Apple MPS / CUDA). See [docs/IDEAS.md](docs/IDEAS.md) |
|
|
91
|
+
| **Acquisition & experiment design** | **acquisition advisor** (pixel size, slice thickness from feature sizes and an empirical "would coarser sampling change the answer?" test; depth / field of view for a target precision), **cohort comparison** (`nuscope-tomo compare`: sampling-aware statistics, Holm correction, minimum detectable difference, volume needed to detect it) |
|
|
92
|
+
| **Sparse & fused chemistry** | context-driven sparse EDS by **deep kernel learning** (after Kalinin, Ziatdinov et al.) with SE and BSE context; **coupled-NMF pan-sharpening** of a coarse EDS map with physically linked high-resolution channels (BSE, Castaing's rule; after Borodinov, Kalinin, Ovchinnikova et al., npj Comput. Mater. 2019); benchmark with SE-invisible chemistry |
|
|
93
|
+
| **Self-driving slice-and-view** | agent that refocuses, corrects drift, adapts dwell and slice thickness, takes sparse EDS and stops at the requested precision; **Thermo Fisher AutoScript** backend (dry-run by default, arming phrase, safety limits; not yet run on hardware), digital twin built from your own data, shadow mode that records the AutoScript calls an autonomous run would issue |
|
|
94
|
+
| **Chemistry (EDS)** | element-map stacks → registration to SE → 3D composition → unsupervised chemical phases (k-means / GMM / NMF) → composition per SE phase or object; forward simulator for validation |
|
|
95
|
+
| **Visualization** | GPU renders (volume, phase surfaces with cut-away, objects coloured by any measurement), turntable MP4s, figure panels with true aspect and scale bars |
|
|
96
|
+
| **Studio** | NUScope-TOMO Studio, a browser application: project home with pipeline status and key results; viewer (linked XY/XZ/YZ + WebGL 3D, layouts, voxel/phase readout, keyboard shortcuts); FIB-SEM Wizard; scribble annotation → random forest or U-Net; Measure, Confidence, Chemistry and Acquire workspaces with interactive charts; self-driving twin runs with live charts and a stop button; ⌘K search over pages, data and operations; light and dark themes. Every action is recorded as a recipe |
|
|
97
|
+
| **Recipes** | YAML pipelines, `nuscope-tomo run`; every step logged with parameters, timings and library versions in `provenance.json` |
|
|
98
|
+
|
|
99
|
+
## Install
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
pip install nuscope-tomo # or "nuscope-tomo[ai]" for Noise2Void / U-Net (PyTorch)
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
For development, in a clone: `uv pip install -e ".[dev]"`. With [NUScope](https://github.com/NUANCE-IT/NUScope)
|
|
106
|
+
installed, the same commands are also available as `nuscope tomo ...`. With
|
|
107
|
+
[NUANCE-MCP](https://github.com/NUANCE-IT/NUANCE-MCP) installed, NUScope-TOMO adds tools for tomography
|
|
108
|
+
projects (`tomo_project`, `tomo_table`, `tomo_volume`, `tomo_ops`, `tomo_run`, `tomo_job`).
|
|
109
|
+
|
|
110
|
+
## Use
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
nuscope-tomo run examples/fib_sem_335.yaml # full pipeline on a slice-and-view stack
|
|
114
|
+
nuscope-tomo studio projects/fib_sem_335 # open http://127.0.0.1:8765
|
|
115
|
+
nuscope-tomo ops # list operations and parameters
|
|
116
|
+
nuscope-tomo watch /acq/folder -p projects/run --voxel 20 5 5 --model rf.pkl # live mode
|
|
117
|
+
python examples/beyond_avizo.py # data health, Noise2Void, U-Net, RVE
|
|
118
|
+
nuscope-tomo compare A=projects/a/run B=projects/b/run --out cohort
|
|
119
|
+
python examples/chemical_fusion.py # sparse DKL vs pan-sharpening benchmark
|
|
120
|
+
python examples/self_driving.py agent # autonomous run on the digital twin
|
|
121
|
+
python examples/showcase.py # figures, renders and animation
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
From Python:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
from nuscope_tomo import Volume
|
|
128
|
+
from nuscope_tomo.preprocess import auto_crop, align, destripe, denoise_nlm
|
|
129
|
+
from nuscope_tomo.segment import random_forest
|
|
130
|
+
from nuscope_tomo.analyze import measure_objects
|
|
131
|
+
|
|
132
|
+
vol = Volume.from_zarr("raw.zarr")
|
|
133
|
+
vol = denoise_nlm(destripe(align(auto_crop(vol))["volume"]))
|
|
134
|
+
phases = random_forest(vol, scribbles="annotations.json", classes=3)["volume"]
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Remote use: run `nuscope-tomo studio --host 0.0.0.0` on the workstation that holds the data
|
|
138
|
+
and open it from any laptop. The browser only receives slices and a downsampled 3D preview.
|
|
139
|
+
|
|
140
|
+
## Design notes
|
|
141
|
+
|
|
142
|
+
- **Out-of-core first.** Volumes are Dask arrays over Zarr; slice-wise operations stream.
|
|
143
|
+
Connected components, watershed and surface meshing run in memory, on a binned volume
|
|
144
|
+
or an ROI for very large data.
|
|
145
|
+
- **Anisotropy everywhere.** FIB-SEM voxels are typically 5–10 nm in XY and 10–50 nm in
|
|
146
|
+
Z. Distances, filters, surface areas and renders all use physical spacing.
|
|
147
|
+
- **Validated against ground truth.** `pytest` runs 26 tests on synthetic phantoms.
|
|
148
|
+
They cover drift recovery, stripe removal, sphere volume, area and sphericity (within 1–2 %),
|
|
149
|
+
percolation and tortuosity, random-forest accuracy, watershed splitting, TPB length on a
|
|
150
|
+
straight triple line, transport through a straight channel (τ = 1, D_eff = ε), the neck of two
|
|
151
|
+
fused spheres, slice-thickness detection, integral-range error prediction, Noise2Void,
|
|
152
|
+
U-Net, live ingestion, the advisor, cohort statistics, sparse DKL, pan-sharpening, the
|
|
153
|
+
AutoScript dry-run and safety guards, the agent on a twin, EDS registration and phase
|
|
154
|
+
recovery, the recipe engine and the Studio API.
|
|
155
|
+
- **Honest alignment.** Correlation cannot separate stage drift from microstructure that is
|
|
156
|
+
inclined to the milling axis, which is especially a problem with thick slices. `align`
|
|
157
|
+
therefore detects stacks that are already registered and leaves them alone, and supports
|
|
158
|
+
fiducial ROIs and a high-pass drift model.
|
|
159
|
+
|
|
160
|
+
## Project layout
|
|
161
|
+
|
|
162
|
+
```
|
|
163
|
+
nuscope_tomo/
|
|
164
|
+
core/ Volume, operation registry, recipes + provenance
|
|
165
|
+
io/ slice import/export
|
|
166
|
+
preprocess/ geometry, alignment, artifact correction, denoising
|
|
167
|
+
segment/ thresholds, random-forest classifier, object separation
|
|
168
|
+
analyze/ object morphometry, phase metrics
|
|
169
|
+
chem/ EDS chemical tomography (+ simulator)
|
|
170
|
+
viz/ GPU rendering, animation, figures
|
|
171
|
+
studio/ FastAPI server + WebGL2 front-end
|
|
172
|
+
cli.py `nuscope` command
|
|
173
|
+
examples/ recipe for the sample dataset, showcase script
|
|
174
|
+
tests/ ground-truth tests
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
See [PLAN.md](PLAN.md) for the Avizo feature map and roadmap: U-Net segmentation, Noise2Void,
|
|
178
|
+
3D multi-volume registration, permeability, native `.h5oina` / `.bcf` EDS readers.
|
|
179
|
+
|
|
180
|
+
## Licence
|
|
181
|
+
|
|
182
|
+
MIT, see [LICENSE](LICENSE). Copyright (c) 2026 Roberto dos Reis (@rmsreis).
|
|
183
|
+
|
|
184
|
+
## Citation
|
|
185
|
+
|
|
186
|
+
If NUScope-TOMO helps your research, please cite it using [CITATION.cff](CITATION.cff).
|
|
187
|
+
Author: Roberto dos Reis (@rmsreis).
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# NUScope-TOMO
|
|
2
|
+
|
|
3
|
+
**Open FIB-SEM slice-and-view tomography — from raw slices to quantified, chemically
|
|
4
|
+
resolved 3D microstructure.**
|
|
5
|
+
|
|
6
|
+
Created by **Roberto dos Reis ([@rmsreis](https://github.com/rmsreis))** · NUANCE Center,
|
|
7
|
+
Northwestern University · [NUANCE-IT/NUScope-TOMO](https://github.com/NUANCE-IT/NUScope-TOMO)
|
|
8
|
+
|
|
9
|
+
NUScope-TOMO is an open alternative to **Thermo Fisher Avizo** for FIB-SEM in materials
|
|
10
|
+
science. It covers import, pre-processing (with a guided FIB-SEM wizard), AI segmentation,
|
|
11
|
+
quantification, triple-phase boundaries, pore/particle networks, transport simulation,
|
|
12
|
+
visualization/animation and recipes. It also adds correlative EDS chemistry. Everything is
|
|
13
|
+
available as code, as reproducible YAML recipes and in a browser-based UI.
|
|
14
|
+
[PLAN.md](PLAN.md) maps each Avizo capability to its module.
|
|
15
|
+
|
|
16
|
+
<p>
|
|
17
|
+
<img src="docs/images/09_phases_3d.jpg" width="49%" alt="Phase surfaces with cut-away">
|
|
18
|
+
<img src="docs/images/10_particles_3d.jpg" width="49%" alt="Particles coloured by size">
|
|
19
|
+
</p>
|
|
20
|
+
|
|
21
|
+
*FIB-SEM sample 335 (812 slices, 20 × 5 × 5 nm voxels) processed by `examples/fib_sem_335.yaml`
|
|
22
|
+
in under 5 minutes: dark phase with a grey-value cut-away (left) and 1 414 separated particles
|
|
23
|
+
coloured by equivalent diameter (right).*
|
|
24
|
+
|
|
25
|
+
<p>
|
|
26
|
+
<img src="docs/images/14_transport_field.jpg" width="49%" alt="Simulated diffusion through the grey phase">
|
|
27
|
+
<img src="docs/images/15_contact_network.jpg" width="49%" alt="Particle contact network">
|
|
28
|
+
</p>
|
|
29
|
+
|
|
30
|
+
*Materials analyses: steady-state diffusion through the matrix phase (left, tortuosity factor 1.4
|
|
31
|
+
along Z, 3.8–3.9 across) and the contact network of the dark-phase particles (right, mean
|
|
32
|
+
coordination 3.0).*
|
|
33
|
+
|
|
34
|
+
| Stage | What you get |
|
|
35
|
+
|---|---|
|
|
36
|
+
| **Import** | TIFF/PNG folders (natural sort), multipage TIFF, Thermo Fisher pixel-size tags, streamed into chunked Zarr v3, so stacks larger than RAM are fine |
|
|
37
|
+
| **Pre-processing** | block-face auto-crop (Pt cap / trench / padding), multi-baseline drift solve with already-registered detection, wavelet–FFT curtain removal, shading flattening, slice brightness normalisation, NLM / TV / anisotropic 3D denoising, binning, isotropic resampling, 52° tilt calibration |
|
|
38
|
+
| **Segmentation** | Otsu / multi-Otsu / hysteresis, **random-forest classifier trained from a few scribbles** (41 multi-scale features), majority smoothing, watershed separation of touching particles |
|
|
39
|
+
| **Quantification** | per object: volume, surface area, equivalent diameter, sphericity, solidity, Feret, ellipsoid axes, elongation/flatness, orientation, nearest neighbour, intensity/element means. Per phase: volume fraction, specific surface, interface density, Euler number, percolation, geodesic tortuosity, continuous size distribution |
|
|
40
|
+
| **Materials analyses** | triple-phase boundary length density (total / active), steady-state diffusion & conduction solver (D_eff/D₀, tortuosity factor, MacMullin number; Avizo XLab counterpart), pore- and particle-network model (throat/contact sizes, coordination numbers) |
|
|
41
|
+
| **Beyond Avizo** | **data-health inspector** (per-slice SNR, sharpness, curtaining, drift, blank/duplicate slices, automatic slice-thickness check), **uncertainty on every number** (integral-range sampling error, ±1-voxel segmentation sensitivity, representative-volume size), **live acquisition mode** (`nuscope-tomo watch`: analyse while the FIB mills, tells you when precision is reached), **self-supervised Noise2Void** denoising and a **2.5D U-Net** trained from scribbles (Apple MPS / CUDA). See [docs/IDEAS.md](docs/IDEAS.md) |
|
|
42
|
+
| **Acquisition & experiment design** | **acquisition advisor** (pixel size, slice thickness from feature sizes and an empirical "would coarser sampling change the answer?" test; depth / field of view for a target precision), **cohort comparison** (`nuscope-tomo compare`: sampling-aware statistics, Holm correction, minimum detectable difference, volume needed to detect it) |
|
|
43
|
+
| **Sparse & fused chemistry** | context-driven sparse EDS by **deep kernel learning** (after Kalinin, Ziatdinov et al.) with SE and BSE context; **coupled-NMF pan-sharpening** of a coarse EDS map with physically linked high-resolution channels (BSE, Castaing's rule; after Borodinov, Kalinin, Ovchinnikova et al., npj Comput. Mater. 2019); benchmark with SE-invisible chemistry |
|
|
44
|
+
| **Self-driving slice-and-view** | agent that refocuses, corrects drift, adapts dwell and slice thickness, takes sparse EDS and stops at the requested precision; **Thermo Fisher AutoScript** backend (dry-run by default, arming phrase, safety limits; not yet run on hardware), digital twin built from your own data, shadow mode that records the AutoScript calls an autonomous run would issue |
|
|
45
|
+
| **Chemistry (EDS)** | element-map stacks → registration to SE → 3D composition → unsupervised chemical phases (k-means / GMM / NMF) → composition per SE phase or object; forward simulator for validation |
|
|
46
|
+
| **Visualization** | GPU renders (volume, phase surfaces with cut-away, objects coloured by any measurement), turntable MP4s, figure panels with true aspect and scale bars |
|
|
47
|
+
| **Studio** | NUScope-TOMO Studio, a browser application: project home with pipeline status and key results; viewer (linked XY/XZ/YZ + WebGL 3D, layouts, voxel/phase readout, keyboard shortcuts); FIB-SEM Wizard; scribble annotation → random forest or U-Net; Measure, Confidence, Chemistry and Acquire workspaces with interactive charts; self-driving twin runs with live charts and a stop button; ⌘K search over pages, data and operations; light and dark themes. Every action is recorded as a recipe |
|
|
48
|
+
| **Recipes** | YAML pipelines, `nuscope-tomo run`; every step logged with parameters, timings and library versions in `provenance.json` |
|
|
49
|
+
|
|
50
|
+
## Install
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
pip install nuscope-tomo # or "nuscope-tomo[ai]" for Noise2Void / U-Net (PyTorch)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
For development, in a clone: `uv pip install -e ".[dev]"`. With [NUScope](https://github.com/NUANCE-IT/NUScope)
|
|
57
|
+
installed, the same commands are also available as `nuscope tomo ...`. With
|
|
58
|
+
[NUANCE-MCP](https://github.com/NUANCE-IT/NUANCE-MCP) installed, NUScope-TOMO adds tools for tomography
|
|
59
|
+
projects (`tomo_project`, `tomo_table`, `tomo_volume`, `tomo_ops`, `tomo_run`, `tomo_job`).
|
|
60
|
+
|
|
61
|
+
## Use
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
nuscope-tomo run examples/fib_sem_335.yaml # full pipeline on a slice-and-view stack
|
|
65
|
+
nuscope-tomo studio projects/fib_sem_335 # open http://127.0.0.1:8765
|
|
66
|
+
nuscope-tomo ops # list operations and parameters
|
|
67
|
+
nuscope-tomo watch /acq/folder -p projects/run --voxel 20 5 5 --model rf.pkl # live mode
|
|
68
|
+
python examples/beyond_avizo.py # data health, Noise2Void, U-Net, RVE
|
|
69
|
+
nuscope-tomo compare A=projects/a/run B=projects/b/run --out cohort
|
|
70
|
+
python examples/chemical_fusion.py # sparse DKL vs pan-sharpening benchmark
|
|
71
|
+
python examples/self_driving.py agent # autonomous run on the digital twin
|
|
72
|
+
python examples/showcase.py # figures, renders and animation
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
From Python:
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
from nuscope_tomo import Volume
|
|
79
|
+
from nuscope_tomo.preprocess import auto_crop, align, destripe, denoise_nlm
|
|
80
|
+
from nuscope_tomo.segment import random_forest
|
|
81
|
+
from nuscope_tomo.analyze import measure_objects
|
|
82
|
+
|
|
83
|
+
vol = Volume.from_zarr("raw.zarr")
|
|
84
|
+
vol = denoise_nlm(destripe(align(auto_crop(vol))["volume"]))
|
|
85
|
+
phases = random_forest(vol, scribbles="annotations.json", classes=3)["volume"]
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Remote use: run `nuscope-tomo studio --host 0.0.0.0` on the workstation that holds the data
|
|
89
|
+
and open it from any laptop. The browser only receives slices and a downsampled 3D preview.
|
|
90
|
+
|
|
91
|
+
## Design notes
|
|
92
|
+
|
|
93
|
+
- **Out-of-core first.** Volumes are Dask arrays over Zarr; slice-wise operations stream.
|
|
94
|
+
Connected components, watershed and surface meshing run in memory, on a binned volume
|
|
95
|
+
or an ROI for very large data.
|
|
96
|
+
- **Anisotropy everywhere.** FIB-SEM voxels are typically 5–10 nm in XY and 10–50 nm in
|
|
97
|
+
Z. Distances, filters, surface areas and renders all use physical spacing.
|
|
98
|
+
- **Validated against ground truth.** `pytest` runs 26 tests on synthetic phantoms.
|
|
99
|
+
They cover drift recovery, stripe removal, sphere volume, area and sphericity (within 1–2 %),
|
|
100
|
+
percolation and tortuosity, random-forest accuracy, watershed splitting, TPB length on a
|
|
101
|
+
straight triple line, transport through a straight channel (τ = 1, D_eff = ε), the neck of two
|
|
102
|
+
fused spheres, slice-thickness detection, integral-range error prediction, Noise2Void,
|
|
103
|
+
U-Net, live ingestion, the advisor, cohort statistics, sparse DKL, pan-sharpening, the
|
|
104
|
+
AutoScript dry-run and safety guards, the agent on a twin, EDS registration and phase
|
|
105
|
+
recovery, the recipe engine and the Studio API.
|
|
106
|
+
- **Honest alignment.** Correlation cannot separate stage drift from microstructure that is
|
|
107
|
+
inclined to the milling axis, which is especially a problem with thick slices. `align`
|
|
108
|
+
therefore detects stacks that are already registered and leaves them alone, and supports
|
|
109
|
+
fiducial ROIs and a high-pass drift model.
|
|
110
|
+
|
|
111
|
+
## Project layout
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
nuscope_tomo/
|
|
115
|
+
core/ Volume, operation registry, recipes + provenance
|
|
116
|
+
io/ slice import/export
|
|
117
|
+
preprocess/ geometry, alignment, artifact correction, denoising
|
|
118
|
+
segment/ thresholds, random-forest classifier, object separation
|
|
119
|
+
analyze/ object morphometry, phase metrics
|
|
120
|
+
chem/ EDS chemical tomography (+ simulator)
|
|
121
|
+
viz/ GPU rendering, animation, figures
|
|
122
|
+
studio/ FastAPI server + WebGL2 front-end
|
|
123
|
+
cli.py `nuscope` command
|
|
124
|
+
examples/ recipe for the sample dataset, showcase script
|
|
125
|
+
tests/ ground-truth tests
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
See [PLAN.md](PLAN.md) for the Avizo feature map and roadmap: U-Net segmentation, Noise2Void,
|
|
129
|
+
3D multi-volume registration, permeability, native `.h5oina` / `.bcf` EDS readers.
|
|
130
|
+
|
|
131
|
+
## Licence
|
|
132
|
+
|
|
133
|
+
MIT, see [LICENSE](LICENSE). Copyright (c) 2026 Roberto dos Reis (@rmsreis).
|
|
134
|
+
|
|
135
|
+
## Citation
|
|
136
|
+
|
|
137
|
+
If NUScope-TOMO helps your research, please cite it using [CITATION.cff](CITATION.cff).
|
|
138
|
+
Author: Roberto dos Reis (@rmsreis).
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
"""NUScope-TOMO: open FIB-SEM slice-and-view tomography — reconstruction,
|
|
2
|
+
segmentation, quantification and correlative EDS chemistry."""
|
|
3
|
+
__version__ = "0.3.1"
|
|
4
|
+
|
|
5
|
+
from .core.volume import Volume, VoxelSize # noqa: E402
|
|
6
|
+
|
|
7
|
+
__all__ = ["Volume", "VoxelSize", "__version__"]
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
"""Acquisition advisor: recommend pixel size, slice thickness, field of view
|
|
2
|
+
and milling depth from the first slices of a run (not available in Avizo).
|
|
3
|
+
|
|
4
|
+
Two complementary answers:
|
|
5
|
+
|
|
6
|
+
1. **Feature-scale rule.** Chord lengths of each phase give the size of the
|
|
7
|
+
smallest features; a feature should span ≥ ``px_per_feature`` pixels in
|
|
8
|
+
XY and ≥ ``slices_per_feature`` slices in Z to be measured reliably.
|
|
9
|
+
2. **Empirical coarsening test.** The data already acquired is re-sampled
|
|
10
|
+
as if it had been taken with larger pixels (block majority) or thicker
|
|
11
|
+
slices (every k-th plane). The coarsest sampling whose volume fractions,
|
|
12
|
+
specific surface and mean chord stay within ``tolerance`` of the
|
|
13
|
+
reference is the cheapest acquisition that would have given the same
|
|
14
|
+
answer — with the imaging-time saving it implies.
|
|
15
|
+
|
|
16
|
+
Volume: the integral range of each phase gives the representative volume
|
|
17
|
+
for a target precision, turned into a required depth for the current field
|
|
18
|
+
of view (or a field of view for a fixed depth).
|
|
19
|
+
"""
|
|
20
|
+
from __future__ import annotations
|
|
21
|
+
|
|
22
|
+
from typing import Optional, Sequence
|
|
23
|
+
|
|
24
|
+
import numpy as np
|
|
25
|
+
import pandas as pd
|
|
26
|
+
|
|
27
|
+
from .analyze.confidence import integral_range_cov
|
|
28
|
+
from .analyze.phase import _area
|
|
29
|
+
from .core.registry import op
|
|
30
|
+
from .core.volume import Volume
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
# ------------------------------------------------------------------ chords
|
|
34
|
+
def chord_lengths(mask: np.ndarray, axis: int, spacing_nm: float) -> np.ndarray:
|
|
35
|
+
"""Lengths (nm) of runs of True along ``axis``, excluding runs cut by the edge."""
|
|
36
|
+
m = np.moveaxis(mask, axis, -1).reshape(-1, mask.shape[axis]).astype(np.int8)
|
|
37
|
+
pad = np.pad(m, ((0, 0), (1, 1)))
|
|
38
|
+
d = np.diff(pad, axis=1)
|
|
39
|
+
starts = np.argwhere(d == 1)
|
|
40
|
+
ends = np.argwhere(d == -1)
|
|
41
|
+
L = ends[:, 1] - starts[:, 1]
|
|
42
|
+
inner = (starts[:, 1] > 0) & (ends[:, 1] < m.shape[1])
|
|
43
|
+
return L[inner] * spacing_nm
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def _block_mode(lab: np.ndarray, f: int) -> np.ndarray:
|
|
47
|
+
"""Majority label in f×f blocks in XY (what a larger pixel would record)."""
|
|
48
|
+
z, h, w = lab.shape
|
|
49
|
+
h2, w2 = h // f * f, w // f * f
|
|
50
|
+
lab = lab[:, :h2, :w2]
|
|
51
|
+
classes = np.unique(lab)
|
|
52
|
+
votes = np.stack([(lab == c).reshape(z, h2 // f, f, w2 // f, f).sum((2, 4))
|
|
53
|
+
for c in classes])
|
|
54
|
+
return classes[np.argmax(votes, 0)].astype(lab.dtype)
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def _metrics(lab: np.ndarray, sp, phases) -> dict:
|
|
58
|
+
out = {}
|
|
59
|
+
vol = lab.size * np.prod(sp)
|
|
60
|
+
for c in phases:
|
|
61
|
+
m = lab == c
|
|
62
|
+
out[f"fraction_{c}"] = float(m.mean())
|
|
63
|
+
out[f"sv_{c}"] = _area(m, sp) / vol * 1e3
|
|
64
|
+
ch = np.concatenate([chord_lengths(m, ax, sp[ax]) for ax in (1, 2)])
|
|
65
|
+
out[f"chord_{c}"] = float(ch.mean()) if ch.size else np.nan
|
|
66
|
+
return out
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
# ------------------------------------------------------------------ advisor
|
|
70
|
+
@op("advise.acquisition", inputs=("labels",))
|
|
71
|
+
def advise(labels: Volume, phases: Optional[Sequence[int]] = None,
|
|
72
|
+
tolerance: float = 0.05, target_rel_error: float = 0.05,
|
|
73
|
+
px_per_feature: float = 4.0, slices_per_feature: float = 3.0,
|
|
74
|
+
xy_factors: Sequence[int] = (1, 2, 3, 4), z_factors: Sequence[int] = (1, 2, 3, 4),
|
|
75
|
+
max_voxels: int = 60_000_000) -> dict:
|
|
76
|
+
"""Recommend pixel size, slice thickness and volume from (early) segmented slices."""
|
|
77
|
+
lab = labels.numpy()
|
|
78
|
+
sp = labels.voxel_size.as_tuple()
|
|
79
|
+
full_shape = lab.shape
|
|
80
|
+
if lab.size > max_voxels: # crop the field of view centrally: keep resolution on every axis
|
|
81
|
+
f = np.sqrt(max_voxels / lab.size)
|
|
82
|
+
h, w = int(lab.shape[1] * f), int(lab.shape[2] * f)
|
|
83
|
+
y0, x0 = (lab.shape[1] - h) // 2, (lab.shape[2] - w) // 2
|
|
84
|
+
lab_s = lab[:, y0:y0 + h, x0:x0 + w]
|
|
85
|
+
else:
|
|
86
|
+
lab_s = lab
|
|
87
|
+
names = labels.meta.get("classes", {})
|
|
88
|
+
phases = list(phases or [int(c) for c in np.unique(lab) if c != 0 and (lab == c).mean() > 0.01])
|
|
89
|
+
|
|
90
|
+
# 1. feature-scale rule
|
|
91
|
+
rows = []
|
|
92
|
+
for c in phases:
|
|
93
|
+
m = lab == c
|
|
94
|
+
cxy = np.concatenate([chord_lengths(m, ax, sp[ax]) for ax in (1, 2)])
|
|
95
|
+
cz = chord_lengths(m, 0, sp[0]) if lab.shape[0] > 4 else np.array([])
|
|
96
|
+
cz_mean = float(cz.mean()) if cz.size else np.nan
|
|
97
|
+
d10 = float(np.percentile(cxy, 10)) if cxy.size else np.nan
|
|
98
|
+
rows.append({"phase": c, "name": names.get(str(c), str(c)),
|
|
99
|
+
"chord_xy_mean_nm": float(cxy.mean()) if cxy.size else np.nan,
|
|
100
|
+
"chord_xy_p10_nm": d10,
|
|
101
|
+
"chord_z_mean_nm": cz_mean,
|
|
102
|
+
"pixel_max_nm": d10 / px_per_feature,
|
|
103
|
+
"slice_max_nm": d10 / slices_per_feature})
|
|
104
|
+
scale = pd.DataFrame(rows)
|
|
105
|
+
|
|
106
|
+
# 2. empirical coarsening test
|
|
107
|
+
ref = _metrics(lab_s, sp, phases)
|
|
108
|
+
tests = []
|
|
109
|
+
for fxy in xy_factors:
|
|
110
|
+
lxy = _block_mode(lab_s, fxy) if fxy > 1 else lab_s
|
|
111
|
+
for fz in z_factors:
|
|
112
|
+
l2 = lxy[::fz]
|
|
113
|
+
if l2.shape[0] < 3:
|
|
114
|
+
continue
|
|
115
|
+
sp2 = (sp[0] * fz, sp[1] * fxy, sp[2] * fxy)
|
|
116
|
+
met = _metrics(l2, sp2, phases)
|
|
117
|
+
dev = {k: abs(met[k] - ref[k]) / max(abs(ref[k]), 1e-9) for k in ref}
|
|
118
|
+
tests.append({"pixel_nm": sp2[1], "slice_nm": sp2[0], "xy_factor": fxy,
|
|
119
|
+
"z_factor": fz, "max_rel_change": max(dev.values()),
|
|
120
|
+
"worst_metric": max(dev, key=dev.get),
|
|
121
|
+
"imaging_time_factor": 1 / (fxy * fxy * fz),
|
|
122
|
+
"milling_time_factor": 1 / fz, **{f"d_{k}": v for k, v in dev.items()}})
|
|
123
|
+
tests = pd.DataFrame(tests)
|
|
124
|
+
ok = tests[tests.max_rel_change <= tolerance]
|
|
125
|
+
best = ok.sort_values(["imaging_time_factor", "max_rel_change"]).iloc[0] if len(ok) else \
|
|
126
|
+
tests.sort_values("max_rel_change").iloc[0]
|
|
127
|
+
|
|
128
|
+
# 3. how much volume is needed
|
|
129
|
+
V = lab.size * np.prod(sp) / 1e9
|
|
130
|
+
area_um2 = lab.shape[1] * sp[1] * lab.shape[2] * sp[2] / 1e6
|
|
131
|
+
vol_rows = []
|
|
132
|
+
for c in phases:
|
|
133
|
+
m = lab == c
|
|
134
|
+
p = float(m.mean())
|
|
135
|
+
A3 = integral_range_cov(m[:, ::2, ::2] if m.size > 2e7 else m,
|
|
136
|
+
(sp[0], sp[1] * (2 if m.size > 2e7 else 1),
|
|
137
|
+
sp[2] * (2 if m.size > 2e7 else 1)))
|
|
138
|
+
v_need = 4 * (1 - p) * A3 / (target_rel_error ** 2 * p) if np.isfinite(A3) else np.nan
|
|
139
|
+
vol_rows.append({"phase": c, "name": names.get(str(c), str(c)), "fraction": p,
|
|
140
|
+
"integral_range_um3": A3, "volume_needed_um3": v_need,
|
|
141
|
+
"depth_needed_um_at_current_fov": v_need / area_um2,
|
|
142
|
+
"cube_edge_um": v_need ** (1 / 3),
|
|
143
|
+
"rel_error_now": 2 * np.sqrt(p * (1 - p) * A3 / V) / p})
|
|
144
|
+
volume = pd.DataFrame(vol_rows)
|
|
145
|
+
# an integral-range estimate needs a depth of several feature lengths
|
|
146
|
+
depth_nm = lab.shape[0] * sp[0]
|
|
147
|
+
# (z chords in a shallow volume are biased short, so use the in-plane feature length)
|
|
148
|
+
reliable = bool(depth_nm >= 10 * np.nanmax(scale.chord_xy_mean_nm.fillna(0).to_numpy(),
|
|
149
|
+
initial=0))
|
|
150
|
+
|
|
151
|
+
rec = {
|
|
152
|
+
"current_pixel_nm": sp[1], "current_slice_nm": labels.voxel_size.z,
|
|
153
|
+
"recommended_pixel_nm": float(best.pixel_nm),
|
|
154
|
+
"recommended_slice_nm": float(best.slice_nm),
|
|
155
|
+
"imaging_speedup": float(1 / best.imaging_time_factor),
|
|
156
|
+
"milling_speedup": float(1 / best.milling_time_factor),
|
|
157
|
+
"max_change_at_recommendation": float(best.max_rel_change),
|
|
158
|
+
"feature_rule_pixel_nm": float(scale.pixel_max_nm.min()),
|
|
159
|
+
"feature_rule_slice_nm": float(scale.slice_max_nm.min()),
|
|
160
|
+
"depth_needed_um": float(volume.depth_needed_um_at_current_fov.max()),
|
|
161
|
+
"fov_area_um2": area_um2, "volume_now_um3": V,
|
|
162
|
+
"target_rel_error": target_rel_error, "tolerance": tolerance,
|
|
163
|
+
"depth_analysed_um": depth_nm / 1e3, "volume_estimate_reliable": reliable,
|
|
164
|
+
"shape_analysed": "x".join(map(str, full_shape)),
|
|
165
|
+
}
|
|
166
|
+
rec["advice"] = _advice_text(rec, volume)
|
|
167
|
+
return {"recommendation": pd.DataFrame([rec]), "feature_scale": scale,
|
|
168
|
+
"coarsening": tests, "volume": volume}
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
def _advice_text(r: dict, volume: pd.DataFrame) -> str:
|
|
172
|
+
parts = []
|
|
173
|
+
if r["recommended_pixel_nm"] > r["current_pixel_nm"] or \
|
|
174
|
+
r["recommended_slice_nm"] > r["current_slice_nm"]:
|
|
175
|
+
parts.append(f"Sampling: {r['recommended_pixel_nm']:.0f} nm pixels and "
|
|
176
|
+
f"{r['recommended_slice_nm']:.0f} nm slices give the same fractions, "
|
|
177
|
+
f"surfaces and feature sizes within {100 * r['max_change_at_recommendation']:.1f} %, "
|
|
178
|
+
f"{r['imaging_speedup']:.0f}x less imaging and {r['milling_speedup']:.0f}x fewer slices.")
|
|
179
|
+
else:
|
|
180
|
+
parts.append("Sampling: the current pixel size and slice thickness are needed; coarser "
|
|
181
|
+
f"sampling changes results by more than {100 * r['tolerance']:.0f} %.")
|
|
182
|
+
worst = volume.sort_values("depth_needed_um_at_current_fov").iloc[-1]
|
|
183
|
+
pre = "" if r["volume_estimate_reliable"] else \
|
|
184
|
+
f"(preliminary: only {r['depth_analysed_um']:.1f} µm milled so far) "
|
|
185
|
+
parts.append(f"Volume {pre}: for ±{100 * r['target_rel_error']:.0f} % on every phase fraction, mill "
|
|
186
|
+
f"≈ {worst.depth_needed_um_at_current_fov:.0f} µm at this field of view "
|
|
187
|
+
f"({r['fov_area_um2']:.0f} µm²), or widen the field to a ≈ {worst.cube_edge_um:.0f} µm "
|
|
188
|
+
f"cube; limiting phase: {worst['name']}.")
|
|
189
|
+
return " ".join(parts)
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
__all__ = ["advise", "chord_lengths"]
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
"""Deep learning (optional dependency: ``pip install torch``).
|
|
2
|
+
|
|
3
|
+
* ``denoise_n2v`` — Noise2Void self-supervised denoising, trained on the
|
|
4
|
+
dataset itself (no clean images needed).
|
|
5
|
+
* ``unet_segment`` — 2D U-Net trained from sparse scribbles (masked loss),
|
|
6
|
+
the same annotations the random forest uses.
|
|
7
|
+
|
|
8
|
+
Runs on Apple Silicon (MPS), CUDA or CPU.
|
|
9
|
+
"""
|
|
10
|
+
from .unet import UNet2D, device # noqa: F401
|
|
11
|
+
from .n2v import denoise_n2v, train_n2v # noqa: F401
|
|
12
|
+
from .segment import train_unet, unet_segment # noqa: F401
|