image_viewer

image_viewer

image_viewer(
    image_path: str,
    data,
    overlay: str = None,
    flip_y: bool = True,
    overlay_category: list = None,
    markers: list = None,
    channel_names="default",
    x_coordinate: str = "X_centroid",
    y_coordinate: str = "Y_centroid",
    point_size: int = 10,
    point_color=None,
    subset: str = None,
    imageid: str = "imageid",
    seg_mask: str = None,
    umap_settings: dict = None,
    sdataTable: str = None,
    **kwargs
)

Open the raw image in napari with cells overlaid and a linked UMAP.

Loads the image as a lazy pyramid, adds one napari layer per channel, and scatters the cells on top at their real coordinates. When the object has a UMAP embedding, a dock widget shows it alongside: click legend entries to toggle categories, lasso a region to select those cells, and save the selection into a new obs column from the widget's UI.

The function blocks until the napari window is closed, and then returns the (possibly edited) object together with the viewer.

This function keeps scimap's snake_case parameters

Unlike the rest of scimappro, image_viewer uses x_coordinate, y_coordinate, imageid, seg_mask, and so on, matching scimap so that viewer calls port across unchanged. data and sdataTable follow the scimappro convention.

Parameters:

Name	Type	Description	Default
image_path	(str, required)	Path to the OME-TIFF, TIFF, or Zarr image.	required
data	(AnnData | SpatialData | str, required)	The cell table. An AnnData, a path to an .h5ad file, a SpatialData object, or a path to a .zarr SpatialData store.	required
overlay	str	Column in obs whose categories are drawn as separate point layers — usually 'phenotype'.	None
flip_y	bool	Flip the y axis so the points line up with the image.	True
overlay_category	list	Draw only these categories of overlay.	None
markers	list	Channels to add as image layers. All of them when None.	None
channel_names	list | str	Names for the image channels. 'default' uses var_names.	'default'
x_coordinate	str	Column in obs holding x positions.	'X_centroid'
y_coordinate	str	Column in obs holding y positions.	'Y_centroid'
point_size	int	Size of the overlaid cell markers.	10
point_color	str | dict	One colour for all points, or a {category: colour} mapping.	None
subset	str | list	Restrict to these values of imageid. Set this whenever the object holds more than one image, since the viewer shows one image at a time.	None
imageid	str	Column in obs holding image identifiers.	'imageid'
seg_mask	str	Path to a segmentation mask to add as a napari labels layer.	None
umap_settings	dict	Options for the docked UMAP widget.	None
sdataTable	str	Which SpatialData table to use. Edits made in the viewer land in that table and the SpatialData itself is returned.	None
**kwargs	dict	Forwarded to napari.Viewer.add_image.	{}

Returns:

Name	Type	Description
data	AnnData | SpatialData	The object, carrying any obs columns saved from the viewer.
viewer	Viewer	The napari viewer, so you can keep scripting against it.

Example

adata, viewer = sp.pl.image_viewer(
    "registration/image.tif",
    adata,
    overlay="phenotype",
    subset="sample_1",
    point_size=8,
)

# A selection saved from the widget shows up as a new obs column.
adata.obs["lasso_selection"].value_counts()