Metadata-Version: 2.4
Name: nuscope-tomo
Version: 0.3.2
Summary: Open FIB-SEM slice-and-view tomography: alignment, artifact correction, ML segmentation, 3D quantification and correlative EDS chemistry, with a browser-based Studio.
Author-email: Roberto dos Reis <robertomsreis@gmail.com>
Maintainer: Roberto dos Reis (@rmsreis)
License-Expression: MIT
Project-URL: Homepage, https://github.com/NUANCE-IT/NUScope-TOMO
Project-URL: Issues, https://github.com/NUANCE-IT/NUScope-TOMO/issues
Project-URL: NUScope, https://nuance-it.github.io/NUScope/
Project-URL: Author, https://github.com/rmsreis
Keywords: FIB-SEM,slice and view,tomography,segmentation,EDS,microscopy,Avizo alternative,materials science
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: scikit-image>=0.24
Requires-Dist: scikit-learn>=1.4
Requires-Dist: dask[array]>=2024.1
Requires-Dist: zarr>=3.0
Requires-Dist: tifffile
Requires-Dist: imageio
Requires-Dist: imageio-ffmpeg
Requires-Dist: pywavelets
Requires-Dist: pandas
Requires-Dist: pyyaml
Requires-Dist: matplotlib
Requires-Dist: pyvista>=0.44
Requires-Dist: pyamg
Requires-Dist: fastapi
Requires-Dist: uvicorn[standard]
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: ai
Requires-Dist: torch>=2.2; extra == "ai"
Dynamic: license-file

# NUScope-TOMO

**Open FIB-SEM slice-and-view tomography — from raw slices to quantified, chemically
resolved 3D microstructure.**

Created by **Roberto dos Reis ([@rmsreis](https://github.com/rmsreis))** · NUANCE Center,
Northwestern University · [NUANCE-IT/NUScope-TOMO](https://github.com/NUANCE-IT/NUScope-TOMO)

NUScope-TOMO is an open alternative to **Thermo Fisher Avizo** for FIB-SEM in materials
science. It covers import, pre-processing (with a guided FIB-SEM wizard), AI segmentation,
quantification, triple-phase boundaries, pore/particle networks, transport simulation,
visualization/animation and recipes. It also adds correlative EDS chemistry. Everything is
available as code, as reproducible YAML recipes and in a browser-based UI.
[PLAN.md](PLAN.md) maps each Avizo capability to its module.

<p>
  <img src="docs/images/09_phases_3d.jpg" width="49%" alt="Phase surfaces with cut-away">
  <img src="docs/images/10_particles_3d.jpg" width="49%" alt="Particles coloured by size">
</p>

*FIB-SEM sample 335 (812 slices, 20 × 5 × 5 nm voxels) processed by `examples/fib_sem_335.yaml`
in under 5 minutes: dark phase with a grey-value cut-away (left) and 1 414 separated particles
coloured by equivalent diameter (right).*

<p>
  <img src="docs/images/14_transport_field.jpg" width="49%" alt="Simulated diffusion through the grey phase">
  <img src="docs/images/15_contact_network.jpg" width="49%" alt="Particle contact network">
</p>

*Materials analyses: steady-state diffusion through the matrix phase (left, tortuosity factor 1.4
along Z, 3.8–3.9 across) and the contact network of the dark-phase particles (right, mean
coordination 3.0).*

| Stage | What you get |
|---|---|
| **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 |
| **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 |
| **Segmentation** | Otsu / multi-Otsu / hysteresis, **random-forest classifier trained from a few scribbles** (41 multi-scale features), majority smoothing, watershed separation of touching particles |
| **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 |
| **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) |
| **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) |
| **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) |
| **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 |
| **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 |
| **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 |
| **Visualization** | GPU renders (volume, phase surfaces with cut-away, objects coloured by any measurement), turntable MP4s, figure panels with true aspect and scale bars |
| **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 |
| **Recipes** | YAML pipelines, `nuscope-tomo run`; every step logged with parameters, timings and library versions in `provenance.json` |

## Install

```bash
pip install nuscope-tomo            # or "nuscope-tomo[ai]" for Noise2Void / U-Net (PyTorch)
```

For development, in a clone: `uv pip install -e ".[dev]"`. With [NUScope](https://github.com/NUANCE-IT/NUScope)
installed, the same commands are also available as `nuscope tomo ...`. With
[NUANCE-MCP](https://github.com/NUANCE-IT/NUANCE-MCP) installed, NUScope-TOMO adds tools for tomography
projects (`tomo_project`, `tomo_table`, `tomo_volume`, `tomo_phase_fractions`, `tomo_ops`, `tomo_run`, `tomo_job`).

## Use

```bash
nuscope-tomo run examples/fib_sem_335.yaml          # full pipeline on a slice-and-view stack
nuscope-tomo studio projects/fib_sem_335            # open http://127.0.0.1:8765
nuscope-tomo ops                                    # list operations and parameters
nuscope-tomo watch /acq/folder -p projects/run --voxel 20 5 5 --model rf.pkl   # live mode
python examples/beyond_avizo.py                # data health, Noise2Void, U-Net, RVE
nuscope-tomo compare A=projects/a/run B=projects/b/run --out cohort
python examples/chemical_fusion.py             # sparse DKL vs pan-sharpening benchmark
python examples/self_driving.py agent          # autonomous run on the digital twin
python examples/showcase.py                    # figures, renders and animation
```

From Python:

```python
from nuscope_tomo import Volume
from nuscope_tomo.preprocess import auto_crop, align, destripe, denoise_nlm
from nuscope_tomo.segment import random_forest
from nuscope_tomo.analyze import measure_objects

vol = Volume.from_zarr("raw.zarr")
vol = denoise_nlm(destripe(align(auto_crop(vol))["volume"]))
phases = random_forest(vol, scribbles="annotations.json", classes=3)["volume"]
```

Remote use: run `nuscope-tomo studio --host 0.0.0.0` on the workstation that holds the data
and open it from any laptop. The browser only receives slices and a downsampled 3D preview.

## Design notes

- **Out-of-core first.** Volumes are Dask arrays over Zarr; slice-wise operations stream.
  Connected components, watershed and surface meshing run in memory, on a binned volume
  or an ROI for very large data.
- **Anisotropy everywhere.** FIB-SEM voxels are typically 5–10 nm in XY and 10–50 nm in
  Z. Distances, filters, surface areas and renders all use physical spacing.
- **Validated against ground truth.** `pytest` runs 26 tests on synthetic phantoms.
  They cover drift recovery, stripe removal, sphere volume, area and sphericity (within 1–2 %),
  percolation and tortuosity, random-forest accuracy, watershed splitting, TPB length on a
  straight triple line, transport through a straight channel (τ = 1, D_eff = ε), the neck of two
  fused spheres, slice-thickness detection, integral-range error prediction, Noise2Void,
  U-Net, live ingestion, the advisor, cohort statistics, sparse DKL, pan-sharpening, the
  AutoScript dry-run and safety guards, the agent on a twin, EDS registration and phase
  recovery, the recipe engine and the Studio API.
- **Honest alignment.** Correlation cannot separate stage drift from microstructure that is
  inclined to the milling axis, which is especially a problem with thick slices. `align`
  therefore detects stacks that are already registered and leaves them alone, and supports
  fiducial ROIs and a high-pass drift model.

## Project layout

```
nuscope_tomo/
  core/        Volume, operation registry, recipes + provenance
  io/          slice import/export
  preprocess/  geometry, alignment, artifact correction, denoising
  segment/     thresholds, random-forest classifier, object separation
  analyze/     object morphometry, phase metrics
  chem/        EDS chemical tomography (+ simulator)
  viz/         GPU rendering, animation, figures
  studio/      FastAPI server + WebGL2 front-end
  cli.py       `nuscope` command
examples/      recipe for the sample dataset, showcase script
tests/         ground-truth tests
```

See [PLAN.md](PLAN.md) for the Avizo feature map and roadmap: U-Net segmentation, Noise2Void,
3D multi-volume registration, permeability, native `.h5oina` / `.bcf` EDS readers.

## Licence

MIT, see [LICENSE](LICENSE). Copyright (c) 2026 Roberto dos Reis (@rmsreis).

## Citation

If NUScope-TOMO helps your research, please cite it using [CITATION.cff](CITATION.cff).
Author: Roberto dos Reis (@rmsreis).
