Tutorial: segment a DM4 image

This tutorial runs SegSpy as a library on a single DM4 image and prints a summary of the detected particles. It is the example shipped in the repository:

"""Minimal example: use SegSpy as a library (no CLI) on a DM4 image.

Run with the path to any HyperSpy-readable EM image::

    python examples/segment_dm4.py /path/to/image.dm4
"""
import sys

import hyperspy.api as hs

from SegSpy import SegConfig, SegmentationRegistry, get_scale_nm, measure_morphology


def main(path: str) -> None:
    signal = hs.load(path)
    if isinstance(signal, list):
        signal = signal[0]

    config = SegConfig.from_signal(signal, min_area=100, use_grabcut_refinement=False)
    scale_nm = get_scale_nm(signal)

    backend = SegmentationRegistry.get(config.backend)
    mask = backend.segment(signal, config)
    objects = backend.extract_objects(signal, mask, config)

    for obj in objects:
        measure_morphology(obj, scale_nm=scale_nm)

    print(f"{len(objects)} particle(s) found in {path}")
    for obj in objects[:5]:
        m = obj.metrics
        print(
            f"  #{obj.particle_id}: area={m['area_px']:.0f}px "
            f"equiv_diam={m['equivalent_diameter_nm']:.1f}nm "
            f"roundness={m['roundness']:.2f} solidity={m['solidity']:.2f}"
        )
    if len(objects) > 5:
        print(f"  ... ({len(objects) - 5} more)")


if __name__ == "__main__":
    if len(sys.argv) != 2:
        print(f"usage: {sys.argv[0]} <image>", file=sys.stderr)
        sys.exit(2)
    main(sys.argv[1])

Run it

python examples/segment_dm4.py /path/to/image.dm4

You’ll see a per-particle summary like:

12 particle(s) found in /path/to/image.dm4
  #1: area=312px equiv_diam=18.4nm roundness=0.71 solidity=0.94
  #2: area=205px equiv_diam=15.1nm roundness=0.83 solidity=0.97
  ...

Reading the metrics

measure_morphology writes these keys into each object’s metrics dict (length metrics are reported in pixels _px and nanometres _nm):

Key	Meaning
area_px	Contour area (px)
equivalent_diameter_px / equivalent_diameter_nm	Diameter of the equal-area circle
feret_min_px / feret_max_px / feret_max_nm	Min/max caliper (Feret) diameters
perimeter_px	Contour perimeter (px)
aspect_ratio	feret_max / feret_min
convexity	Convex-hull perimeter / contour perimeter
roundness	4·area / (π·feret_max²) (1 = circular)
solidity	area / convex-hull area (1 = convex)
centroid_yx	Moment-based centroid in (row, col)

To export every particle to CSV instead of printing, use the CLI, which writes the same metrics to <stem>_particles.csv.