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.
Files changed (68) hide show
  1. nuscope_tomo-0.3.1/LICENSE +21 -0
  2. nuscope_tomo-0.3.1/PKG-INFO +187 -0
  3. nuscope_tomo-0.3.1/README.md +138 -0
  4. nuscope_tomo-0.3.1/nuscope_tomo/__init__.py +7 -0
  5. nuscope_tomo-0.3.1/nuscope_tomo/advisor.py +192 -0
  6. nuscope_tomo-0.3.1/nuscope_tomo/ai/__init__.py +12 -0
  7. nuscope_tomo-0.3.1/nuscope_tomo/ai/n2v.py +109 -0
  8. nuscope_tomo-0.3.1/nuscope_tomo/ai/segment.py +161 -0
  9. nuscope_tomo-0.3.1/nuscope_tomo/ai/unet.py +79 -0
  10. nuscope_tomo-0.3.1/nuscope_tomo/analyze/__init__.py +8 -0
  11. nuscope_tomo-0.3.1/nuscope_tomo/analyze/confidence.py +208 -0
  12. nuscope_tomo-0.3.1/nuscope_tomo/analyze/materials.py +274 -0
  13. nuscope_tomo-0.3.1/nuscope_tomo/analyze/objects.py +133 -0
  14. nuscope_tomo-0.3.1/nuscope_tomo/analyze/phase.py +144 -0
  15. nuscope_tomo-0.3.1/nuscope_tomo/analyze/quality.py +135 -0
  16. nuscope_tomo-0.3.1/nuscope_tomo/autonomy/__init__.py +6 -0
  17. nuscope_tomo-0.3.1/nuscope_tomo/autonomy/agent.py +261 -0
  18. nuscope_tomo-0.3.1/nuscope_tomo/autonomy/instrument.py +252 -0
  19. nuscope_tomo-0.3.1/nuscope_tomo/autonomy/twin.py +116 -0
  20. nuscope_tomo-0.3.1/nuscope_tomo/chem/__init__.py +4 -0
  21. nuscope_tomo-0.3.1/nuscope_tomo/chem/eds.py +253 -0
  22. nuscope_tomo-0.3.1/nuscope_tomo/chem/simulate.py +55 -0
  23. nuscope_tomo-0.3.1/nuscope_tomo/cli.py +88 -0
  24. nuscope_tomo-0.3.1/nuscope_tomo/cohort.py +164 -0
  25. nuscope_tomo-0.3.1/nuscope_tomo/core/__init__.py +6 -0
  26. nuscope_tomo-0.3.1/nuscope_tomo/core/recipe.py +202 -0
  27. nuscope_tomo-0.3.1/nuscope_tomo/core/registry.py +66 -0
  28. nuscope_tomo-0.3.1/nuscope_tomo/core/volume.py +214 -0
  29. nuscope_tomo-0.3.1/nuscope_tomo/io/__init__.py +4 -0
  30. nuscope_tomo-0.3.1/nuscope_tomo/io/stack.py +139 -0
  31. nuscope_tomo-0.3.1/nuscope_tomo/live.py +221 -0
  32. nuscope_tomo-0.3.1/nuscope_tomo/mcp.py +129 -0
  33. nuscope_tomo-0.3.1/nuscope_tomo/preprocess/__init__.py +7 -0
  34. nuscope_tomo-0.3.1/nuscope_tomo/preprocess/_util.py +37 -0
  35. nuscope_tomo-0.3.1/nuscope_tomo/preprocess/align.py +186 -0
  36. nuscope_tomo-0.3.1/nuscope_tomo/preprocess/correct.py +114 -0
  37. nuscope_tomo-0.3.1/nuscope_tomo/preprocess/denoise.py +79 -0
  38. nuscope_tomo-0.3.1/nuscope_tomo/preprocess/geometry.py +125 -0
  39. nuscope_tomo-0.3.1/nuscope_tomo/segment/__init__.py +6 -0
  40. nuscope_tomo-0.3.1/nuscope_tomo/segment/classifier.py +208 -0
  41. nuscope_tomo-0.3.1/nuscope_tomo/segment/objects.py +125 -0
  42. nuscope_tomo-0.3.1/nuscope_tomo/segment/threshold.py +51 -0
  43. nuscope_tomo-0.3.1/nuscope_tomo/sparse/__init__.py +16 -0
  44. nuscope_tomo-0.3.1/nuscope_tomo/sparse/active.py +103 -0
  45. nuscope_tomo-0.3.1/nuscope_tomo/sparse/dkl.py +115 -0
  46. nuscope_tomo-0.3.1/nuscope_tomo/sparse/pansharpen.py +115 -0
  47. nuscope_tomo-0.3.1/nuscope_tomo/studio/__init__.py +1 -0
  48. nuscope_tomo-0.3.1/nuscope_tomo/studio/server.py +431 -0
  49. nuscope_tomo-0.3.1/nuscope_tomo/studio/static/app.js +488 -0
  50. nuscope_tomo-0.3.1/nuscope_tomo/studio/static/charts.js +408 -0
  51. nuscope_tomo-0.3.1/nuscope_tomo/studio/static/gl.js +286 -0
  52. nuscope_tomo-0.3.1/nuscope_tomo/studio/static/index.html +338 -0
  53. nuscope_tomo-0.3.1/nuscope_tomo/studio/static/pages.js +422 -0
  54. nuscope_tomo-0.3.1/nuscope_tomo/studio/static/shell.js +137 -0
  55. nuscope_tomo-0.3.1/nuscope_tomo/studio/static/style.css +324 -0
  56. nuscope_tomo-0.3.1/nuscope_tomo/viz/__init__.py +4 -0
  57. nuscope_tomo-0.3.1/nuscope_tomo/viz/figures.py +110 -0
  58. nuscope_tomo-0.3.1/nuscope_tomo/viz/render.py +341 -0
  59. nuscope_tomo-0.3.1/nuscope_tomo.egg-info/PKG-INFO +187 -0
  60. nuscope_tomo-0.3.1/nuscope_tomo.egg-info/SOURCES.txt +66 -0
  61. nuscope_tomo-0.3.1/nuscope_tomo.egg-info/dependency_links.txt +1 -0
  62. nuscope_tomo-0.3.1/nuscope_tomo.egg-info/entry_points.txt +8 -0
  63. nuscope_tomo-0.3.1/nuscope_tomo.egg-info/requires.txt +26 -0
  64. nuscope_tomo-0.3.1/nuscope_tomo.egg-info/top_level.txt +1 -0
  65. nuscope_tomo-0.3.1/pyproject.toml +71 -0
  66. nuscope_tomo-0.3.1/setup.cfg +4 -0
  67. nuscope_tomo-0.3.1/tests/test_mcp_plugin.py +53 -0
  68. 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