segmentation-measurement

segmentation-measurement is a Python library for post-processing, measuring, and analyzing instance segmentations from microscopy images. It provides:

• Post-processing: filter small segments, remove small holes, compute ring-masks around segments.
• Intensity measurements: per-object mean, median, max, standard deviation, and percentile statistics.
• Morphology measurements: per-object area/volume, perimeter/surface area, sphericity, solidity, axis lengths, and equivalent diameter; supports anisotropic pixel/voxel sizes.
• Cell-nucleus measurements: per-cell nucleus count, cell-to-nucleus area/volume ratio, and optional cytoplasmic vs. nuclear intensity ratios from paired cell and nucleus segmentations.
• Threshold analysis: categorize objects into named groups based on any measurement column using automatic or manual thresholds.
• Clustering analysis: cluster objects using k-means, DBSCAN, HDBSCAN, or Mean Shift on any combination of measurement features, with an interactive 2-D feature-reduction scatter plot (UMAP, t-SNE, or PCA).
• Classification analysis: train a random forest or logistic regression classifier from interactive napari brush annotations and apply it to all segments, with optional export of the trained classifier.
• Batch processing across multiple segmentations: define named groups of layers in the napari plugin and run any measurement or analysis widget over every member of a group with a single click, with results written back per-layer.
• Napari plugin: interactive widgets for all of the above, with table visualization and export to CSV, TSV, and Excel.
• CLI: command-line interface for all functionality.

All functions support 2D and 3D inputs.

Installation

Install the core library with pip:

pip install segmentation-measurement

To also install the napari plugin and its dependencies:

pip install "segmentation-measurement[napari]"

To install from source:

git clone https://github.com/computational-cell-analytics/segmentation-measurement-tool
cd segmentation-measurement-tool
pip install -e .
# or with napari support:
pip install -e ".[napari]"

Requires Python 3.9 or later.

Napari Plugin

The segmentation-measurement napari plugin provides interactive widgets for post-processing segmentation label layers and for computing and exploring per-segment measurements – all without writing any Python code.

Installation

pip install "segmentation-measurement[napari]"

After installation the plugin is automatically discovered by napari.

Opening the Widgets

Open any widget from the napari menu:

Plugins → Segmentation Measurement → Postprocessing

Plugins → Segmentation Measurement → Intensity Measurement → Intensity Measurement

Plugins → Segmentation Measurement → Morphology Measurement → Morphology Measurement

Plugins → Segmentation Measurement → Threshold Analysis → Threshold Analysis

Plugins → Segmentation Measurement → Cell-Nucleus Measurement → Cell-Nucleus Measurement

Plugins → Segmentation Measurement → Clustering Analysis → Clustering Analysis

Plugins → Segmentation Measurement → Classification Analysis → Classification Analysis

Plugins → Segmentation Measurement → Table Manipulation → Table Manipulation

Plugins → Segmentation Measurement → Group Manager → Group Manager

All widgets appear as dockable panels that can be placed anywhere in the napari window.

Working with measurement tables

Measurement and analysis results are stored as the features table of the source Labels layer. napari ships a built-in Features Table dock (Layers → Visualize → Features table widget) that displays this table for the currently selected layer. Whenever a widget in this plugin writes to a layer's features (after a measurement, after applying a threshold/cluster/classifier, after loading or editing a table), the dock is opened automatically and the source layer is selected so the result is visible immediately. The dock supports sorting, in-place editing, copy/paste, CSV save, and bidirectional row ↔ viewer selection sync.

Working with groups (batch processing)

A group is a named bundle of layers that you batch over. Each group lists ordered layers under three roles:

• segmentation (required, ≥1 layer) — the primary label layers to process
• nucleus_segmentation (optional) — paired nucleus segmentations for the Cell-Nucleus widget
• intensity_image (optional) — paired intensity images for the Intensity widget and (optionally) the Cell-Nucleus widget

Within a group, layers across roles are paired by position: segmentation[i] is matched with nucleus_segmentation[i] and intensity_image[i]. An optional role's list must either be empty or have exactly the same length as the segmentation list.

Groups are defined in the Group Manager Widget. Once defined, every measurement and analysis widget exposes a Target combo at the top with two options:

• <single layer> (default) — original single-layer behaviour. Pick one segmentation (and optional pair partners) via the existing combos.
• a group name — operate on the group's members. Measurement widgets iterate over members and write results into each member's features. Analysis widgets concatenate features across members for joint computation, then split results back to each member's features and emit one output label layer per member named {output}_{layer} (or just {output} for a single-member group).

Renaming a layer that is referenced by a group automatically updates the group definition.

Postprocessing Widget

The Postprocessing widget applies one of three post-processing operations to an existing label layer and writes the result to a new layer or back to the same layer.

Layout

┌─────────────────────────────────┐
│ Input segmentation: [combo]     │
│ Output name:        [combo]     │
│ Method:             [combo]     │
│ ┌ Parameters ──────────────┐   │
│ │  <method-specific param> │   │
│ └──────────────────────────┘   │
│ [Run]                           │
└─────────────────────────────────┘

Controls

Input segmentation : Dropdown list of all Labels layers currently loaded in napari. Select the layer you want to process.

Output name : Dropdown showing existing Labels layers plus the default entry postprocessed. You can also type a new name directly. If the chosen name matches an existing layer the data of that layer is updated in place; otherwise a new Labels layer is added. Setting the output name equal to the input name processes the input layer in place.

Method : Choose one of the three post-processing operations (see below). The Parameters panel updates immediately to show the relevant controls.

Run : Apply the selected method with the current parameters.

Methods

Filter Small Segments

Removes segments whose pixel (2-D) or voxel (3-D) count is below the threshold. Removed segments become background (0).

• Min size – Minimum number of pixels/voxels a segment must have to be retained (default: 100).

Remove Small Holes

Fills enclosed background holes within segments when the hole size does not exceed the threshold. Other segments are never overwritten.

• Max hole size – Maximum hole size in pixels/voxels to fill (default: 50).

Ring Mask

Creates an annular ring of a fixed width around each segment. Rings are placed only on background pixels; overlapping rings resolve in favour of the smaller label ID. This is commonly used to create pseudo-cytoplasm masks around segmented nuclei.

• Ring width – Width of the ring in pixels/voxels (default: 5).
• Keep original – When checked (default), the original segment pixels are retained in the output alongside the ring pixels. Uncheck to produce a ring-only mask where the original segment interiors are set to 0.

Watershed

Refines a segmentation using the watershed algorithm. The selected input segmentation is used as seed markers; a separate heatmap image layer provides the topographic landscape. The algorithm floods from low heatmap values upward, so the heatmap should have low values at segment boundaries. If your heatmap instead has high values at object centres (e.g. a distance transform or foreground-probability map), negate it before passing it to the widget.

• Heatmap – Image layer used as the watershed landscape (low values flooded first).
• Mask (optional) – Label layer whose footprint restricts processing. Pixels outside the mask are set to 0 in the output. Select None to process all pixels (default).

Intensity Measurement Widget

The Intensity Measurement widget computes per-segment intensity statistics from a label layer and a co-registered intensity image.

Layout

┌─────────────────────────────────┐
│ Target:          [combo]        │
│ Segmentation:    [combo]        │
│ Intensity image: [combo]        │
│ [Measure intensities]           │
└─────────────────────────────────┘

Workflow

1. Pick a Target: <single layer> (default) for the original single-pair behaviour, or a previously defined group name to batch over its members. In group mode the Segmentation and Intensity image combos become read-only and show the first member; the group must define a non-empty intensity_image role.
2. Select a Segmentation layer (Labels) from the first dropdown.
3. Select an Intensity image layer (Image) from the second dropdown.
4. Click Measure intensities.

In group mode the measurement is run on every (segmentation[i], intensity_image[i]) pair in turn, writing results into each segmentation layer's features. See the Working with groups section for the broader pattern.

The result is merged into the segmentation layer's features table and the napari Features Table dock is opened automatically with the segmentation layer selected. Re-running the measurement on the same layer silently overwrites the existing intensity columns; running a different measurement (e.g. Morphology) on the same layer adds its columns alongside.

The columns added to layer.features are:

Saving the table

Use the Save as CSV button in the napari Features Table dock to export the features. For TSV / XLSX export, use the Save table button in the Table Manipulation Widget below.

Morphology Measurement Widget

The Morphology Measurement widget computes per-segment shape descriptors from a label layer. Physical pixel/voxel sizes can be specified per axis to obtain measurements in real-world units.

Layout (scrollable)

┌─────────────────────────────────┐
│ Target:       [combo]           │
│ Segmentation: [combo]           │
│ ┌ Physical pixel/voxel size ─┐ │
│ │ Y: [spinbox]               │ │
│ │ X: [spinbox]               │ │
│ └────────────────────────────┘ │
│ [Measure morphology]            │
└─────────────────────────────────┘

For 3-D data a third spinbox Z is added automatically.

Workflow

1. Pick a Target: <single layer> (default) for the original single-layer behaviour, or a previously defined group name to batch over its segmentation members. In group mode the Segmentation combo becomes read-only and shows the first member; the same scale settings apply to every member.
2. Select a Segmentation layer (Labels) from the dropdown. The scale spinboxes are pre-populated from the layer's scale attribute if it has been set; otherwise they default to 1.0.
3. Adjust the per-axis scale values if needed. For isotropic data a single value applies to all axes; for anisotropic data set each axis independently.
4. Click Measure morphology.

The result is merged into the segmentation layer's features table and the napari Features Table dock is opened automatically with the segmentation layer selected. Re-running the measurement on the same layer silently overwrites the morphology columns; running a different measurement on the same layer adds its columns alongside.

The columns added to layer.features (one row per segment) are:

2-D columns

3-D columns

Saving the table

Use the Save as CSV button in the napari Features Table dock, or the Save table button in the Table Manipulation Widget for TSV / XLSX output.

Threshold Analysis Widget

The Threshold Analysis widget categorizes segments into named groups based on one or more thresholds applied to any numeric column of the selected layer's features table.

Layout (scrollable)

┌──────────────────────────────────────┐
│ Target:       [combo]                │
│ Segmentation: [combo]                │
│ ┌ Column histogram ────────────────┐ │
│ │ Column: [combo]                  │ │
│ │  <histogram plot>                │ │
│ └──────────────────────────────────┘ │
│ ┌ Categorization ──────────────────┐ │
│ │ Number of categories: [spin]     │ │
│ │ Threshold 1: [spin]  ...         │ │
│ │ Name 1: [edit]  ...              │ │
│ │ [Suggest thresholds]             │ │
│ │ Output layer: [edit]             │ │
│ │ [Categorize]                     │ │
│ └──────────────────────────────────┘ │
└──────────────────────────────────────┘

Workflow

Step 1 – Select the segmentation layer or group

The widget operates on the features table of the selected Labels layer (populated by Intensity Measurement, Morphology Measurement, Cell-Nucleus Measurement, or by loading a CSV via the Table Manipulation Widget).

1. Run one of the measurement widgets first (or load a CSV).
2. Pick a Target: <single layer> (default) for the original single-layer behaviour, or a previously defined group name. In group mode the Segmentation combo becomes read-only. The histogram and threshold suggestion are computed on the concatenation of all members' features so a single set of thresholds can be applied consistently across the batch.
3. In single-layer mode, pick the layer from the Segmentation dropdown. The Column dropdown is filled with its numeric columns (excluding index and category_id).

Step 2 – Explore the histogram

The Column histogram section shows the distribution of the currently selected column. Threshold lines are drawn in red so you can evaluate the split visually before applying it.

Note: The histogram requires matplotlib. Install it with pip install matplotlib if it is not already available.

Step 3 – Set thresholds and categorize

1. Set Number of categories (2–10). The threshold and name fields update automatically.
2. Enter threshold values in the Threshold spin-boxes, or click Suggest thresholds to auto-populate them using equally-spaced quantiles of the selected column. The threshold lines on the histogram update in real time.
3. Optionally rename each category in the Name fields (defaults: category_1, category_2, …).
4. Enter an Output layer name (default: categories).
5. Click Categorize.

Two things happen:

• The source layer's features gains two new columns: category_id (integer, 1-based) and category_name (string). The Features Table dock is opened automatically with the source layer selected so you can inspect them.
• A new Labels layer is created (or updated) in napari where each segment is assigned its category ID as the label value. Use napari's built-in colormap controls to distinguish the categories visually.

In group mode every member's features receives the new columns and one output Labels layer is created per member named {output}_{layer_name} (or just {output} when the group has a single member).

How thresholds are applied

Segments with a value below the first threshold are assigned category 1, segments between the first and second threshold are assigned category 2, and so on. Thresholds need not be sorted; the widget sorts them internally.

Cell-Nucleus Measurement Widget

The Cell-Nucleus Measurement widget computes per-cell features that combine a cell segmentation with a nucleus segmentation. It reports the number of nuclei per cell, cell-to-nucleus area/volume ratios, and optionally cytoplasmic vs. nuclear intensity statistics.

Layout (scrollable)

┌─────────────────────────────────────┐
│ Target:                 [combo]     │
│ Cell segmentation:      [combo]     │
│ Nucleus segmentation:   [combo]     │
│ Intensity image (optional): [combo] │
│ ┌ Physical pixel/voxel size ──────┐ │
│ │ Y: [spinbox]                    │ │
│ │ X: [spinbox]                    │ │
│ └─────────────────────────────────┘ │
│ [Measure cell-nucleus]              │
└─────────────────────────────────────┘

For 3-D data a third spinbox Z is added automatically.

Workflow

1. Pick a Target: <single layer> (default) for the original per-pair behaviour, or a previously defined group name to batch over its members. In group mode the cell, nucleus, and intensity-image combos become read-only and show the first member; the group must define a non-empty nucleus_segmentation role, while intensity_image is optional and is used when present.
2. Select a Cell segmentation layer (Labels) from the first dropdown. The scale spinboxes are pre-populated from the layer's scale attribute if it has been set; otherwise they default to 1.0.
3. Select a Nucleus segmentation layer (Labels) from the second dropdown. This layer must have the same spatial dimensions as the cell segmentation.
4. Optionally select an Intensity image layer (Image) from the third dropdown. Choose (none) to skip intensity measurements.
5. Adjust the per-axis scale values if needed (same convention as the Morphology widget).
6. Click Measure cell-nucleus.

In group mode the measurement is run on every (segmentation[i], nucleus_segmentation[i], intensity_image[i] or None) triple in turn, writing results into each cell-segmentation layer's features.

The result is merged into the cell segmentation layer's features table and the napari Features Table dock is opened automatically with that layer selected. One row per cell.

Columns – without intensity image (2-D)

For 3-D data the columns are cell_volume, nucleus_volume, and volume_ratio instead.

Additional columns – with intensity image

When an intensity image is selected, columns are added for each statistic {stat} in mean, median, max, min, percentile_10, percentile_25, percentile_75, percentile_90:

Saving the table

Use the Save as CSV button in the napari Features Table dock, or the Save table button in the Table Manipulation Widget for TSV / XLSX output.

Clustering Analysis Widget

The Clustering Analysis widget groups segments into clusters based on all numeric columns in a previously computed measurement table. After clustering, a 2-D feature-reduction scatter plot visualises the result, and a new label layer is created where each segment is painted with its cluster ID. The scatter-plot colours and the label-layer colours are kept in sync.

Layout (scrollable)

┌──────────────────────────────────────┐
│ Target:       [combo]                │
│ Segmentation: [combo]                │
│ ┌ Feature reduction ───────────────┐ │
│ │ Method: [UMAP▾]  [Reduce]        │ │
│ │  <2-D scatter plot>              │ │
│ └──────────────────────────────────┘ │
│ ┌ Clustering ──────────────────────┐ │
│ │ Method: [K-Means▾]               │ │
│ │  <method-specific parameters>    │ │
│ │ Output layer: [edit]             │ │
│ │ [Cluster]                        │ │
│ └──────────────────────────────────┘ │
└──────────────────────────────────────┘

Workflow

Step 1 – Select the segmentation layer or group

The widget operates on the features table of the selected Labels layer. Run a measurement widget first (or load a CSV via the Table Manipulation widget), then either pick the layer from the Segmentation dropdown or pick a group from the Target dropdown.

In group mode the Segmentation combo becomes read-only. Features across the group's members are concatenated for joint clustering and the 2-D feature-reduction scatter plot, and one output Labels layer is created per member named {output}_{layer_name} (or just {output} for a single-member group). The same cluster colours are applied across all output layers so cluster IDs match visually.

Step 2 – Explore the feature space (optional)

1. Choose a Feature reduction method: UMAP (default), TSNE, or PCA.
2. Click Reduce to compute a 2-D embedding of the features and display an uncoloured scatter plot.

Note: UMAP requires the optional umap-learn package (pip install umap-learn). If it is not installed the widget falls back to PCA automatically. Changing the reduction method clears the cached embedding so the next Reduce or Cluster call recomputes it.

Step 3 – Cluster

1. Select a Clustering method from the dropdown (see table below).
2. Adjust the method-specific parameters shown below the dropdown.
3. Enter an Output layer name (default: clusters).
4. Click Cluster.

Three things happen simultaneously:

• The source layer's features gains a new cluster_id column (1-based; -1 for noise) and the napari Features Table dock is opened automatically with that layer selected.
• The scatter plot is redrawn with each point coloured by its cluster.
• A new Labels layer is created (or updated) where each segment is painted with its cluster_id. The layer colours are set to exactly match the scatter-plot colours.

If you re-run clustering, the existing cluster_id column is excluded from the feature set so it does not affect the new result.

Clustering methods and parameters

Cluster IDs and label values

Cluster IDs are 1-based: the first cluster found is 1, the second is 2, and so on. Segments that are classified as noise by DBSCAN or HDBSCAN receive cluster_id = -1 and remain as background (0) in the output label layer.

Color matching

The widget uses matplotlib's tab10 (or tab20 when there are more than 10 clusters) colormap to assign one colour per cluster. The same colour array is applied to the Labels layer via DirectLabelColormap, so the scatter-plot legend and the segmentation overlay always show identical colours.

Saving the table

Use the Save as CSV button in the napari Features Table dock, or the Save table button in the Table Manipulation Widget for TSV / XLSX output.

Classification Analysis Widget

The Classification Analysis widget lets you interactively annotate a small number of segments with class labels using napari's paint tools, train a random forest or logistic regression classifier on those annotations, and then apply it to every segment in the table. The result is written to a new label layer and two new columns in the measurement table. Trained classifiers can be exported to disk for batch use from the CLI.

Layout (scrollable)

┌──────────────────────────────────────┐
│ Target: [combo]                      │
│ ┌ Layers ──────────────────────────┐ │
│ │ Segmentation: [combo]            │ │
│ │ Annotation layer: [combo] [Create new] │
│ └──────────────────────────────────┘ │
│ ┌ Class names ─────────────────────┐ │
│ │  Label ID │ Class Name           │ │
│ │  <editable rows>                 │ │
│ └──────────────────────────────────┘ │
│ ┌ Classifier ──────────────────────┐ │
│ │ Method: [Random Forest▾]         │ │
│ │  <method-specific parameters>    │ │
│ │ Output layer: [edit]             │ │
│ │ [x] Live Update                  │ │
│ │ [Train & Apply]                  │ │
│ │ [Export classifier]              │ │
│ └──────────────────────────────────┘ │
└──────────────────────────────────────┘

Workflow

Step 1 – Select the segmentation layer or group

The widget operates on the features table of the selected Labels layer. Run a measurement widget first (or load a CSV via the Table Manipulation widget), then pick a Target: <single layer> (default) for the original single-layer behaviour, or a previously defined group name to classify across the group's segmentation members.

In group mode the Segmentation combo is restricted to the group's members so you can step through them one at a time to annotate each. The class-names table pools detected annotation IDs across every member of the group, so detected classes are not lost as you switch members. See Per-member annotation persistence below for how brushstrokes survive member switches.

Step 2 – Create an annotation layer

The Annotation layer combo defaults to (none) so per-member persistence cannot accidentally overwrite an unrelated label layer.

1. Click Create new next to the Annotation layer dropdown. A new, empty Labels layer called annotations is added to napari and automatically selected.
2. Alternatively, select an existing Labels layer from the Annotation layer dropdown if you already have annotations you want to use.

The active annotation layer is outlined by a thin frame in the image space. In group mode the frame follows the current member position in the grid.

Step 3 – Paint annotations

Use napari's built-in label painting tools to draw brushstrokes on the annotation layer.

• Each label value you paint (1, 2, 3, …) represents a different class.
• You can use napari's color picker and label selector to switch between classes.
• Paint at least a few representative segments from each class. You do not need to annotate every segment — the classifier will be applied to the rest automatically.

Step 4 – Review projected annotations

Whenever you finish painting, erasing, or changing labels in the annotation layer, the widget waits briefly and then automatically:

1. Reads the pixel-level brushstrokes from the annotation layer.
2. For each segment in the segmentation, takes the majority-vote annotation label across all annotated pixels that overlap that segment. Segments with no annotation overlap receive annotation 0 (unannotated).
3. Merges an annotation column into the source layer's features (overwriting any previous annotation values).
4. Populates the Class names table with all annotation label IDs detected.

Because the projection is based on the full current annotation layer, removed brushstrokes set the corresponding segment annotation back to 0, and repainting with another label updates the value in the table.

Step 5 – Name the classes (optional)

The Class names table lists each detected annotation label ID with an editable name field. Click a name cell and type to rename a class (e.g. change class_1 to mitotic, class_2 to interphase). These names are written to the classification_name output column.

Step 6 – Train and apply the classifier

1. Choose a Method (default: Random Forest) and adjust the parameters if needed (see table below).
2. Enter an Output layer name (default: classification).
3. Leave Live Update enabled to retrain and apply the classifier automatically after annotation edits. Disable it to enable the Train & Apply button and run the classifier manually.

Three things happen:

• A scikit-learn classifier is trained on all rows where annotation > 0, using all numeric measurement columns as features (excluding index, annotation, classification_id, classification_name, cluster_id, category_id, and category_name). Features are z-score standardised internally.
• The classifier is applied to every row in the layer's features (including unannotated ones). Results are merged back into the source layer's features as two new columns: classification_id (1-based integer) and classification_name (string). Manual Train & Apply also opens the Features Table dock with that layer selected; live updates keep the current layer selection unchanged.
• A new Labels layer is created (or updated) in napari where each segment is painted with its classification_id. Colours are keyed off the class ID itself (using tab10 for ≤10 classes and tab20 beyond that), so the same class always renders in the same colour even when other classes are absent from a particular layer.

If the classifier is re-run, existing classification_id and classification_name columns are excluded from the feature set so they do not affect the new result.

In group mode the classifier is trained on the concatenation of all members' features (using each member's projected annotation column) and then applied per-member. One output Labels layer is created per member named {output}_{layer_name} (or just {output} for a single-member group). Class colours are keyed off the class ID, so the same class always renders in the same colour across all member outputs even if a particular member only contains a subset of classes.

Per-member annotation persistence

In group mode the widget keeps a per-member cache of your brushstrokes so they survive switching between members:

• When you switch the Segmentation combo to a different member, the current annotation layer's contents are saved (sparse-compressed) for the previously-active member, and the cached annotations for the new member are loaded into the same annotation layer. If the new member has no cache yet, the layer is reset to zeros.
• Switching the Target combo back to <single layer> (or to another group) saves the current member's annotations first so they are available again when you re-enter the group.
• The cache is kept only as long as the widget is open and is keyed off the segmentation-layer name; renaming a member-layer mid-session decouples its cache.

The single-layer mode is unaffected: switching segmentation layers there does not alter the annotation layer.

Classification methods and parameters

Class IDs

Classification IDs are 1-based and match the annotation label values painted in the annotation layer. A segment that could not be classified (e.g. because all its feature values were NaN) receives classification_id = 0 and an empty classification_name.

Exporting the classifier

Click Export classifier to save the trained pipeline (StandardScaler + classifier) to a .joblib file. The exported file can be used with the analyze classify CLI command to apply it to new tables in batch.

Saving the table

Use the Save as CSV button in the napari Features Table dock, or the Save table button in the Table Manipulation Widget for TSV / XLSX output.

Group Manager Widget

The Group Manager is the single place where you define and edit the layer groups consumed by every measurement and analysis widget's Target combo. See Working with groups for the underlying data model and pairing semantics.

Layout (scrollable)

┌────────────────────────────────────────┐
│ ┌ Defined groups ────────────────────┐ │
│ │  exp_1  (3 seg, 3 nuc)             │ │
│ │  exp_2  (5 seg)                    │ │
│ │  ...                               │ │
│ │ [Delete selected]                  │ │
│ │ [Arrange selected as grid]         │ │
│ └────────────────────────────────────┘ │
│ ┌ Group editor ──────────────────────┐ │
│ │ Name: [edit]                       │ │
│ │ ┌ Segmentation layers (required)─┐ │ │
│ │ │  cells_01                      │ │ │
│ │ │  cells_02                      │ │ │
│ │ │ [Add selected][Remove][Up][Down] │ │
│ │ └────────────────────────────────┘ │ │
│ │ ┌ Nucleus layers (optional)──────┐ │ │
│ │ │  nuclei_01                     │ │ │
│ │ │  nuclei_02                     │ │ │
│ │ │ [Add selected][Remove][Up][Down] │ │
│ │ └────────────────────────────────┘ │ │
│ │ ┌ Intensity images (optional)────┐ │ │
│ │ │  raw_01                        │ │ │
│ │ │  raw_02                        │ │ │
│ │ │ [Add selected][Remove][Up][Down] │ │
│ │ └────────────────────────────────┘ │ │
│ │ ┌ Pairing preview ───────────────┐ │ │
│ │ │ Seg       Nucleus   Intensity  │ │ │
│ │ │ cells_01  nuclei_01 raw_01     │ │ │
│ │ │ cells_02  nuclei_02 raw_02     │ │ │
│ │ └────────────────────────────────┘ │ │
│ │ [Save]                             │ │
│ └────────────────────────────────────┘ │
└────────────────────────────────────────┘

Workflow

1. Select layers in napari's main layer list (you can multi-select with Ctrl/Shift).
2. In the Segmentation layers section click Add selected to add the selected Labels layers to the role. Layers are appended in napari layer-panel order; non-Labels layers in the selection are skipped, as are duplicates already in the list.
3. Optionally repeat for Nucleus layers (also Labels-only) and Intensity images (Image-only).
4. Reorder entries with Up / Down so each row of the Pairing preview at the bottom matches the segmentation–nucleus– image triple you actually want. Within a group, layers across roles are paired by position.
5. Optional roles must be either empty or have the same length as the segmentation list — saving with mismatched lengths is rejected.
6. Type a Name and click Save. If a group with that name already exists it is replaced.

Selecting a group in the top list loads its current members back into the editor for editing. Click Delete selected to remove the highlighted group.

Click Arrange selected as grid to lay out the highlighted group in the viewer. The grid has one cell per segmentation layer. Nucleus and intensity layers, when present, are translated to the same grid cell as their position-matched segmentation layer. For each grid cell, the intensity image is stacked below the nucleus segmentation, and the segmentation layer is stacked on top. Layers are linked by role (segmentations with segmentations, nucleus segmentations with nucleus segmentations, intensity images with intensity images) while spatial transforms remain independent so the grid positions are preserved.

Renaming a layer that a group references automatically updates the group's stored layer name. Removing a layer leaves the dangling reference in place; running a measurement or analysis widget that targets the group will raise an informative error if a member layer is missing.

Table Manipulation Widget

The Table Manipulation widget edits the features table of a Labels layer. It can load an external CSV / TSV / XLSX file (which must contain an index column) and merge it into the layer's features, drop a column from the layer's features, and save the layer's features to a CSV / TSV / XLSX file.

Layout

┌────────────────────────────────────────┐
│ Segmentation: [combo]                  │
│ ┌ Load table from file ──────────────┐ │
│ │ [Load file…]                       │ │
│ └────────────────────────────────────┘ │
│ ┌ Drop column ───────────────────────┐ │
│ │ Column: [combo]   [Drop]           │ │
│ └────────────────────────────────────┘ │
│ [Save table]                            │
└────────────────────────────────────────┘

Loading a table from file

Click Load file… to read a CSV, TSV, or XLSX file. The file must contain an index column whose values are the segment label IDs; loading is rejected otherwise. The columns of the loaded file are merged into the selected layer's features (outer join on index). Columns present in both the file and the existing features are overwritten with the values from the file. The Features Table dock is opened automatically after the merge.

Tip: Multiple measurement widgets writing to the same layer follow the same merge rules — running Intensity then Morphology on the same Labels layer leaves all columns from both measurements in the layer's features.

Dropping a column

Select a column from the Drop column dropdown and click Drop. The column is removed from the selected layer's features. The index column is the segment identifier and is never offered for dropping.

Saving the table

Click Save table to export the selected layer's features to a CSV, TSV, or XLSX file. This complements the napari Features Table dock's CSV-only save by also supporting TSV and Excel output.

Command Line Interface

The segmentation-measurement CLI provides utilities for post-processing segmentations, computing measurements, and analyzing results directly from the terminal without writing any Python code.

Installation

pip install segmentation-measurement

After installation the segmentation-measurement command is available in your shell.

Overview

The CLI exposes five top-level commands:

Run any command with --help to see its full usage:

segmentation-measurement --help
segmentation-measurement open --help
segmentation-measurement postprocess --help
segmentation-measurement measure morphology --help
segmentation-measurement analyze threshold --help

Open In Napari (open)

Open one or more segmentation files in napari, optionally with matched intensity images and nucleus segmentations. Paths may be single file paths or glob expressions. Recursive glob expressions using ** are supported.

segmentation-measurement open \
    --segmentations "data/**/cells*.tif" \
    --intensities "data/**/raw*.tif" \
    --nuclei "data/**/nuclei*.tif"

Segmentations and nuclei are opened as Labels layers. Intensities are opened as Image layers. When a glob expression is used, layer names are derived relative to the directory above the first wildcard component. For example, data/**/seg.tif creates names such as well_a/seg and well_b/seg, so files with the same basename in different subfolders remain distinguishable.

If multiple segmentations are opened, the default behavior is to create a group named opened_files and arrange the matched layers in a grid view. Use --no-grid to keep the group but skip grid arrangement, or --no-group to skip both grouping and grid arrangement.

Arguments

Examples

Open a single segmentation:

segmentation-measurement open --segmentations cells_01.tif

Open matched files as a grouped grid:

segmentation-measurement open \
    --segmentations "experiment/**/cells.tif" \
    --intensities "experiment/**/raw.tif" \
    --nuclei "experiment/**/nuclei.tif" \
    --group-name experiment

Open multiple segmentations without grouping:

segmentation-measurement open --segmentations "cells_*.tif" --no-group

Post-processing (postprocess)

The postprocess command provides three sub-commands that each read a segmentation TIFF, apply a transformation, and write the result to a new TIFF.

filter-small-segments

Remove segments whose size (in pixels for 2-D data, or voxels for 3-D data) is below a minimum threshold. Removed segments are replaced by the background label 0.

segmentation-measurement postprocess filter-small-segments \
    --input  segmentation.tif \
    --output filtered.tif \
    --min-size 200

Arguments

Example – keep only segments with at least 500 pixels:

segmentation-measurement postprocess filter-small-segments \
    --input nuclei.tif --output nuclei_filtered.tif --min-size 500

remove-small-holes

Fill enclosed background holes inside segments when the hole is smaller than or equal to the specified maximum size. Pixels belonging to other segments are never overwritten.

segmentation-measurement postprocess remove-small-holes \
    --input  segmentation.tif \
    --output filled.tif \
    --max-hole-size 50

Arguments

Example – fill holes up to 100 pixels:

segmentation-measurement postprocess remove-small-holes \
    --input cells.tif --output cells_filled.tif --max-hole-size 100

ring-mask

Compute a ring (annular hull) of a specified width around each segment. By default the original segment pixels are retained in the output alongside the ring pixels. Pass --remove-original to produce a ring-only mask (original segment interiors set to 0). This is useful for creating pseudo-cytoplasm masks from segmented nuclei.

Rings are placed only on background pixels; if rings from different segments overlap, the segment with the smaller label ID takes precedence.

segmentation-measurement postprocess ring-mask \
    --input  segmentation.tif \
    --output rings.tif \
    --ring-width 5

Arguments

Example – create 8-pixel-wide rings around nuclei (original segments kept):

segmentation-measurement postprocess ring-mask \
    --input nuclei.tif --output cytoplasm_rings.tif --ring-width 8

Example – ring-only mask (original segments removed):

segmentation-measurement postprocess ring-mask \
    --input nuclei.tif --output rings_only.tif --ring-width 8 --remove-original

watershed

Refine a segmentation using the watershed algorithm. The input segmentation is used as seed markers; the heatmap is the topographic landscape that the algorithm floods. Because skimage.segmentation.watershed floods from low values upward, the heatmap should have low values at desired segment boundaries and high values in the interior. If your heatmap has the opposite convention (e.g. a distance transform or foreground-probability map where high values indicate cell centres), pass the negated image.

An optional binary mask restricts processing to a subset of pixels; unmasked pixels are set to 0 in the output.

segmentation-measurement postprocess watershed \
    --input  seeds.tif \
    --heatmap landscape.tif \
    --output refined.tif

Arguments

Example – watershed refinement with a foreground-probability heatmap (negated so high-probability regions are flooded first):

# Negate the probability map beforehand, then run watershed
segmentation-measurement postprocess watershed \
    --input seeds.tif --heatmap neg_prob.tif --output refined.tif

Measurements (measure)

intensities

Compute per-segment intensity statistics from a segmentation label image and a co-registered intensity image. Both files must be TIFF and must have identical shapes.

segmentation-measurement measure intensities \
    --segmentation segmentation.tif \
    --intensity    fluorescence.tif \
    --output       measurements.csv

Arguments

Supported output formats

Output columns

Example – save results as an Excel file:

segmentation-measurement measure intensities \
    --segmentation cells.tif \
    --intensity    gfp_channel.tif \
    --output       intensity_stats.xlsx

morphology

Compute per-segment shape descriptors from a segmentation label image. Supports isotropic and anisotropic pixel/voxel sizes so that results are returned in physical units.

segmentation-measurement measure morphology \
    --segmentation segmentation.tif \
    --output       morphology.csv

Arguments

Scale argument

Pass a single value for isotropic spacing, or one value per spatial dimension for anisotropic spacing. Dimension order is (Y, X) for 2-D and (Z, Y, X) for 3-D.

# isotropic: 0.5 µm per pixel
--scale 0.5

# anisotropic 2-D: 0.5 µm in Y, 0.25 µm in X
--scale 0.5 0.25

# anisotropic 3-D: 2.0 µm in Z, 0.5 µm in Y and X
--scale 2.0 0.5 0.5

Output columns – 2-D

Output columns – 3-D

Examples

# 2-D, pixel units
segmentation-measurement measure morphology \
    --segmentation cells.tif --output morphology.csv

# 2-D, anisotropic scale
segmentation-measurement measure morphology \
    --segmentation cells.tif --output morphology.csv --scale 0.5 0.25

# 3-D, anisotropic scale (Z=2 µm, Y=X=0.5 µm)
segmentation-measurement measure morphology \
    --segmentation nuclei_3d.tif --output morphology_3d.csv --scale 2.0 0.5 0.5

cell-nucleus

Compute per-cell measurements that combine a cell segmentation with a nucleus segmentation. For each cell, the command reports how many nuclei it contains, the cell and nucleus area/volume in physical units, and their ratio. When an optional intensity image is supplied, it also reports intensity statistics for the cytoplasmic region (cell minus nucleus) and the nuclear region, together with their ratios.

segmentation-measurement measure cell-nucleus \
    --cell-segmentation   cells.tif \
    --nucleus-segmentation nuclei.tif \
    --output              cell_nucleus.csv

Arguments

Scale argument

Identical to the morphology sub-command: pass a single value for isotropic spacing, or one value per spatial dimension for anisotropic spacing in (Y, X) / (Z, Y, X) order.

Output columns – without intensity image (2-D)

For 3-D data the columns are cell_volume, nucleus_volume, and volume_ratio instead.

Additional columns – with intensity image

When --intensity is given, the following columns are added for each statistic {stat} in mean, median, max, min, percentile_10, percentile_25, percentile_75, percentile_90:

Supported output formats – same as intensities (.csv, .tsv, .xlsx).

Examples

# Basic measurements, pixel units
segmentation-measurement measure cell-nucleus \
    --cell-segmentation cells.tif \
    --nucleus-segmentation nuclei.tif \
    --output cell_nucleus.csv

# With physical scale (0.5 µm/px, isotropic)
segmentation-measurement measure cell-nucleus \
    --cell-segmentation cells.tif \
    --nucleus-segmentation nuclei.tif \
    --output cell_nucleus.csv \
    --scale 0.5

# With intensity ratios
segmentation-measurement measure cell-nucleus \
    --cell-segmentation cells.tif \
    --nucleus-segmentation nuclei.tif \
    --intensity gfp_channel.tif \
    --output cell_nucleus_intensity.csv

# Anisotropic 3-D (Z=2 µm, Y=X=0.5 µm) with intensity
segmentation-measurement measure cell-nucleus \
    --cell-segmentation cells_3d.tif \
    --nucleus-segmentation nuclei_3d.tif \
    --intensity gfp_3d.tif \
    --output cell_nucleus_3d.csv \
    --scale 2.0 0.5 0.5

Table manipulation (table)

The table command operates on saved measurement tables (CSV / TSV / XLSX).

merge

Merge one or more saved measurement tables on a shared key column (index by default) and optionally drop columns from the merged result. The merge is an outer join: label IDs that appear in only some inputs are kept, with NaNs in the missing columns. Non-key columns must be disjoint between input tables — drop conflicts beforehand or via --drop-columns.

When only one input is given the command becomes a column-drop utility, useful for cleaning up an existing table. The index column is the segment identifier and is always preserved — passing it to --drop-columns raises an error.

segmentation-measurement table merge \
    --inputs intensity.csv morphology.csv \
    --output combined.csv

Arguments

Example — merge intensity and morphology tables and drop a column:

segmentation-measurement table merge \
    --inputs intensity.csv morphology.csv \
    --output combined.csv \
    --drop-columns std_intensity

Example — drop a column from a single existing table:

segmentation-measurement table merge \
    --inputs combined.csv \
    --output trimmed.csv \
    --drop-columns std_intensity max_intensity

Analysis (analyze)

cluster

Cluster segments using their measurement features. All numeric columns are used as features (excluding index, cluster_id, category_id, and category_name). Features are z-score standardised before clustering.

The output table is the input table with an added cluster_id column. Cluster IDs are 1-based (1, 2, 3, …). Noise points — segments that no cluster claims, as produced by DBSCAN and HDBSCAN — are assigned cluster_id = -1.

segmentation-measurement analyze cluster \
    --table      measurements.csv \
    --method     kmeans \
    --n-clusters 4 \
    --output     clustered.csv

Arguments

Output

The output table is the input table with one additional column:

When --output-segmentation is specified, each segment pixel is set to the cluster_id of that segment (background and noise segments remain 0).

Method defaults

Examples

# K-Means with 5 clusters
segmentation-measurement analyze cluster \
    --table morphology.csv --method kmeans --n-clusters 5 --output clustered.csv

# DBSCAN – also write a cluster segmentation TIFF
segmentation-measurement analyze cluster \
    --table intensity.csv \
    --method dbscan --eps 1.0 --min-samples 3 \
    --output clustered.csv \
    --segmentation cells.tif \
    --output-segmentation clusters.tif

# HDBSCAN
segmentation-measurement analyze cluster \
    --table morphology.csv --method hdbscan --min-cluster-size 10 --output clustered.csv

# Mean Shift with automatic bandwidth
segmentation-measurement analyze cluster \
    --table intensity.csv --method mean_shift --output clustered.csv

threshold

Categorize segments into N named groups based on N-1 thresholds applied to one column of a measurement table. Thresholds can be provided explicitly or suggested automatically from the data distribution.

segmentation-measurement analyze threshold \
    --table      measurements.csv \
    --column     mean_intensity \
    --n-categories 3 \
    --output     categorized.csv

Arguments

Output

The output table is the input table with two additional columns:

Segments with a value below the first threshold are category 1; segments between the first and second threshold are category 2; and so on.

Examples

# Auto-suggest thresholds for 3 categories
segmentation-measurement analyze threshold \
    --table intensity.csv \
    --column mean_intensity \
    --n-categories 3 \
    --output categorized.csv

# Explicit thresholds with custom names
segmentation-measurement analyze threshold \
    --table morphology.csv \
    --column area \
    --n-categories 3 \
    --thresholds 500 1500 \
    --category-names small medium large \
    --output categorized.csv

# Also write a category segmentation TIFF
segmentation-measurement analyze threshold \
    --table intensity.csv \
    --column mean_intensity \
    --n-categories 2 \
    --thresholds 100 \
    --output categorized.csv \
    --segmentation cells.tif \
    --output-segmentation categories.tif

train-classifier

Train a random forest or logistic regression classifier from one or more annotated measurement tables and save the fitted pipeline to a .joblib file.

An annotated table is a measurement table that contains an integer annotation column (or whichever column name you specify with --annotation-column). Rows with a value of 0 in that column are treated as unannotated and excluded from training. Annotated rows are typically exported from the Classification Analysis napari widget, but you can also create the column manually.

All numeric columns are used as features (excluding index, annotation, classification_id, classification_name, cluster_id, category_id, and category_name). Features are z-score standardised inside the saved pipeline so no separate pre-processing step is needed when applying the classifier.

segmentation-measurement analyze train-classifier \
    --tables  annotated.csv \
    --method  random_forest \
    --output  classifier.joblib

Arguments

Examples

# Train a random forest from a single annotated CSV
segmentation-measurement analyze train-classifier \
    --tables annotated.csv \
    --output classifier.joblib

# Train from two experiments combined, with 200 trees
segmentation-measurement analyze train-classifier \
    --tables experiment1.csv experiment2.csv \
    --n-estimators 200 \
    --output classifier.joblib

# Train a logistic regression classifier
segmentation-measurement analyze train-classifier \
    --tables annotated.csv \
    --method logistic_regression \
    --c 0.1 \
    --output classifier.joblib

classify

Apply a previously trained classifier (saved with train-classifier or exported from the napari widget) to a measurement table. The output table gains two new columns: classification_id (1-based integer) and classification_name (string).

segmentation-measurement analyze classify \
    --table      measurements.csv \
    --classifier classifier.joblib \
    --output     classified.csv

Arguments

Output columns

Examples

# Apply classifier and save results as CSV
segmentation-measurement analyze classify \
    --table new_measurements.csv \
    --classifier classifier.joblib \
    --output classified.csv

# Apply and assign human-readable names to classes
segmentation-measurement analyze classify \
    --table new_measurements.csv \
    --classifier classifier.joblib \
    --class-names mitotic interphase apoptotic \
    --output classified.csv

# Also write a classification segmentation TIFF
segmentation-measurement analyze classify \
    --table new_measurements.csv \
    --classifier classifier.joblib \
    --output classified.csv \
    --segmentation cells.tif \
    --output-segmentation classified_seg.tif