view_habitat_napari

Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

view_habitat_napari(images: ndarray | Sequence[ndarray], labels: ndarray, *, opacity: float = 1.0, title: str = 'HABIT habitat', show: bool = True, viewer: Any | None = None, image_names: Sequence[str] | None = None, spacing: Sequence[float] | None = None, direction: Sequence[float] | None = None, display_convention: Literal['radiological', 'neurological', 'native'] = 'radiological') → Any[source]

Open (or populate) a napari viewer with image layer(s) + habitat labels.

Habitat IDs are added as a napari labels layer so background 0 stays transparent and discrete colours stay categorical. Each greyscale anatomy volume is an image layer underneath (multi-sequence studies can pass several arrays).

Volumes are oriented using direction and display_convention (same policy as plot_habitat_overlay() for in-plane A-P / L-R). Image and habitat layers share the same flip + scale so they stay aligned. When direction is omitted for 3D data, LPS identity is assumed (not RAS). Axial z is not flipped by default so slider indices match file order.

Parameters:

  • images – Greyscale source volume (2D or 3D; NumPy (z, y, x) order matches ImageVolume.data / SimpleITK array convention), or a sequence of such volumes sharing the same spatial shape as labels.

  • labels – Integer habitat map with the same spatial shape as each image. Background should be 0; habitats are >= 1.

  • opacity – Labels-layer opacity in (0, 1]. Default 1.0 paints habitat colours opaquely on the anatomy (same policy as plot_habitat_overlay()). Pass a value in (0, 1) only for an explicit blend.

  • title – Window title (ASCII-sanitised for journal-safe defaults).

  • show – When True (default), show the Qt window and block until the user closes it (via napari.run()). Pass False for headless / unit tests (napari.Viewer(show=False)) — then the caller owns lifetime and should call viewer.close().

  • viewer – Existing napari Viewer to reuse, or None to create one.

  • image_names – Optional display names for image layers (e.g. file stems). Defaults to "image" / "image_1", "image_2", …

  • spacing – Optional SimpleITK-order spacing (x, y[, z]) from ImageVolume.spacing. Converted to napari scale=(z, y, x) so anisotropic voxels display correctly.

  • direction – Optional SimpleITK direction cosines (9 floats for 3D). Same layout as ImageVolume.direction. Controls anterior/posterior and left/right in-plane flips.

  • display_convention – "radiological" (default), "neurological", or "native". See habit.viz.orientation.

Returns:

The napari Viewer instance. With show=True this returns only after the event loop exits (window closed); with show=False it returns immediately and the caller should viewer.close().

Raises: