Visualize per-label feature measurements on label images in napari. Color each label by any numeric or categorical feature column, with support for both continuous colormaps (with adjustable contrast limits) and qualitative colormaps for categorical data.
Feature data can be loaded from a CSV file or read directly from
layer.features — enabling visualization of measurements stored in OME-Zarrs
via plugins such as the napari OME-Zarr navigator.
pip install napari-feature-visualization
Open the widget via Plugins → Feature Visualization.
The widget has two modes, selected with the radio buttons at the top:
- Layer Properties — reads feature columns directly from the active Labels
layer's
.featuresDataFrame. No file is needed; the features travel with the layer. - CSV File — loads a CSV from disk. Click Browse… to pick the file. The CSV must have one row per label and at least one column whose values match the label IDs in the image.
Click a Labels layer in the napari layer list. The widget automatically tracks the active layer — the layer name shown below the radio buttons updates as you switch between layers. If the active layer is not a Labels layer or has no feature columns the dropdowns will be empty.
| Dropdown | Purpose |
|---|---|
| Feature | The column to visualize (any numeric or string column) |
| Label column | The column whose integer values match the label IDs in the image |
The Label column defaults to the first column named label, Label, or
index if one exists.
For continuous features all napari colormaps are available. The default is
viridis.
For categorical (non-numeric) features only qualitative colormaps wide
enough to cover the number of unique categories are shown. The default is
tab10 (up to 10 categories). When the number of categories exceeds all
available qualitative colormaps the napari label_colormap is used as
fallback.
The range slider sets the lower and upper contrast limits. Values below the lower limit map to the first colormap color; values above the upper limit map to the last. The limits default to the 1st and 99th percentiles of the feature values.
The Show colorbar checkbox renders a labeled gradient bar below the slider.
- Click Apply Feature Colormap to color the layer once.
- Check Live update to automatically re-apply whenever you change the feature, colormap, or contrast limits.
Labels whose feature value is NaN / None are rendered transparent.
Background (label 0) is always black.
Contributions are welcome. The project uses pixi for environment management.
git clone https://github.com/fractal-napari-plugins-collection/napari-feature-visualization
cd napari-feature-visualization
pixi install
pixi run test # run the test suite
pixi run napari # launch napari with the plugin installed
Linting and formatting use ruff:
pixi run lint # check
pixi run format # auto-format
pixi run check # lint + test in one step
Please ensure the test coverage does not decrease before opening a pull request.
Releases are driven by git tags. The version is managed automatically by setuptools-scm — there is no version number to edit manually.
- Make sure
mainis clean and all tests pass. - Create and push a version tag:
git tag v<major>.<minor>.<patch> git push origin v<major>.<minor>.<patch> - The GitHub Actions workflow detects the tag and automatically:
- Builds the source distribution and wheel (
python -m build) - Uploads to PyPI via Twine (requires the
TWINE_API_KEYsecret to be set in the repository settings)
- Builds the source distribution and wheel (
There is no separate changelog file — use the GitHub Releases page to document what changed.
Distributed under the terms of the BSD-3 license.
File an issue on GitHub with a detailed description.