sigima.viz — Visualization Tools#

This module provides visualization utilities for Sigima objects, useful for:

  • Interactive testing and debugging

  • Data analysis in Jupyter notebooks

  • Quick visual inspection of processing results

Backend Selection#

The module automatically selects between PlotPy and Matplotlib backends based on availability and configuration settings.

The backend selection follows this priority:

  1. Environment variable SIGIMA_VIZ_BACKEND (if set)

  2. Configuration option sigima.config.options.viz_backend

  3. Auto-detection (PlotPy preferred, Matplotlib as fallback)

Backend selection logic:

  • "auto": Try PlotPy first, fall back to Matplotlib

  • "plotpy": Use PlotPy (raise ImportError if not available)

  • "matplotlib": Use Matplotlib (raise ImportError if not available)

Configuring the Backend

Using environment variable:

import os
os.environ["SIGIMA_VIZ_BACKEND"] = "matplotlib"  # Before importing sigima.viz

from sigima import viz
# Now uses Matplotlib backend

Using configuration option:

from sigima.config import options
options.viz_backend.set("plotpy")

from sigima import viz
# Now uses PlotPy backend

Module Attributes#

sigima.viz.BACKEND_NAME: str#

Name of the currently selected backend: "plotpy" or "matplotlib".

sigima.viz.BACKEND_SOURCE: str#

How the backend was selected: "env", "config", or "auto".

Quick Start#

from sigima import viz
import sigima.proc.signal as sips
from sigima.tests.data import get_test_signal

# Load a test signal
signal = get_test_signal("paracetamol.txt")

# Apply some processing
filtered = sips.moving_average(signal, n=10)

# View the results
viz.view_curves([signal, filtered], title="Signal Processing")

Viewing Functions#

These functions display Sigima objects (SignalObj and ImageObj) in interactive dialogs or plots.

sigima.viz.view_curves(data_or_objs: list[SignalObj | ndarray | tuple[ndarray, ndarray]] | SignalObj | ndarray | tuple[ndarray, ndarray], name: str | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, xunit: str | None = None, yunit: str | None = None, show_roi: bool = True, object_name: str = '') → None[source]#

Create a curve dialog and plot curves

Parameters:

  • data_or_objs – Single SignalObj or np.ndarray, or a list/tuple of these, or a list/tuple of (xdata, ydata) pairs

  • name – Name of the dialog, or None to use a default name

  • title – Title of the dialog, or None to use a default title

  • xlabel – Label for the x-axis, or None for no label

  • ylabel – Label for the y-axis, or None for no label

  • xunit – Unit for the x-axis, or None for no unit

  • yunit – Unit for the y-axis, or None for no unit

  • show_roi – Whether to show ROIs defined in SignalObj instances, default is True (ignored if data_or_objs is not a SignalObj)

  • object_name – Object name for the dialog (for screenshot functionality)

sigima.viz.view_images(data_or_objs: list[ImageObj | ndarray] | ImageObj | ndarray, name: str | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, zlabel: str | None = None, xunit: str | None = None, yunit: str | None = None, zunit: str | None = None, results: list[GeometryResult] | GeometryResult | None = None, show_roi: bool = True, object_name: str = '', **kwargs) → None[source]#

Create an image dialog and show images

Parameters:

  • data_or_objs – Single ImageObj or np.ndarray, or a list/tuple of these

  • name – Name of the dialog, or None to use a default name

  • title – Title of the dialog, or None to use a default title

  • xlabel – Label for the x-axis, or None for no label

  • ylabel – Label for the y-axis, or None for no label

  • zlabel – Label for the z-axis (color scale), or None for no label

  • xunit – Unit for the x-axis, or None for no unit

  • yunit – Unit for the y-axis, or None for no unit

  • zunit – Unit for the z-axis (color scale), or None for no unit

  • results – Single GeometryResult or list of these to overlay on images, or None if no overlay is needed.

  • show_roi – Whether to show ROIs defined in ImageObj instances, default is True (ignored if data_or_objs is not a ImageObj)

  • object_name – Object name for the dialog (for screenshot functionality)

  • **kwargs – Additional keyword arguments to pass to make.maskedimage()

sigima.viz.view_images_side_by_side(images: list[ImageItem | ndarray | ImageObj], titles: list[str] | None = None, share_axes: bool = True, rows: int | None = None, maximized: bool = False, title: str | None = None, results: list[GeometryResult] | GeometryResult | None = None, show_roi: bool = True, object_name: str = '', **kwargs) → None[source]#

Show sequence of images

Parameters:

  • images – List of ImageItem, np.ndarray, or ImageObj objects to display

  • titles – List of titles for each image

  • share_axes – Whether to share axes across plots, default is True

  • rows – Fixed number of rows in the grid, or None to compute automatically

  • maximized – Whether to show the dialog maximized, default is False

  • title – Title of the dialog, or None for a default title

  • results – Single GeometryResult or list of these to overlay on images, or None if no overlay is needed.

  • show_roi – Whether to show ROIs defined in ImageObj instances, default is True (ignored if images do not contain ImageObj instances)

  • object_name – Object name for the dialog widget (used for screenshot filename)

  • **kwargs – Additional keyword arguments to pass to make.maskedimage()

sigima.viz.view_curves_and_images(data_or_objs: list[SignalObj | ndarray | ImageObj], name: str | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, zlabel: str | None = None, xunit: str | None = None, yunit: str | None = None, zunit: str | None = None, object_name: str = '') → None[source]#

View signals, then images in two successive dialogs

Parameters:

  • data_or_objs – List of SignalObj, ImageObj, np.ndarray or a mix of these

  • name – Name of the dialog, or None to use a default name

  • title – Title of the dialog, or None to use a default title

  • xlabel – Label for the x-axis, or None for no label

  • ylabel – Label for the y-axis, or None for no label

  • zlabel – Label for the z-axis (color scale), or None for no label

  • xunit – Unit for the x-axis, or None for no unit

  • yunit – Unit for the y-axis, or None for no unit

  • zunit – Unit for the z-axis (color scale), or None for no unit

  • object_name – Object name for the dialog (for screenshot functionality)

Low-Level Viewing Functions#

These functions display plot items (curves, images) rather than Sigima objects.

sigima.viz.view_curve_items(items: list[CurveItem], name: str | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, xunit: str | None = None, yunit: str | None = None, add_legend: bool = True, datetime_format: str | None = None, object_name: str = '') → None[source]#

Create a curve dialog and plot items

Parameters:

  • items – List of CurveItem objects to plot

  • name – Name of the dialog, or None to use a default name

  • title – Title of the dialog, or None to use a default title

  • xlabel – Label for the x-axis, or None for no label

  • ylabel – Label for the y-axis, or None for no label

  • xunit – Unit for the x-axis, or None for no unit

  • yunit – Unit for the y-axis, or None for no unit

  • add_legend – Whether to add a legend to the plot, default is True

  • datetime_format – Datetime format for x-axis if x data is datetime, or None

  • object_name – Object name for the dialog (for screenshot functionality)

sigima.viz.view_image_items(items: list[ImageItem], name: str | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, zlabel: str | None = None, xunit: str | None = None, yunit: str | None = None, zunit: str | None = None, show_itemlist: bool = False, object_name: str = '') → None[source]#

Create an image dialog and show items

Parameters:

  • items – List of ImageItem objects to display

  • name – Name of the dialog, or None to use a default name

  • title – Title of the dialog, or None to use a default title

  • xlabel – Label for the x-axis, or None for no label

  • ylabel – Label for the y-axis, or None for no label

  • zlabel – Label for the z-axis (color scale), or None for no label

  • xunit – Unit for the x-axis, or None for no unit

  • yunit – Unit for the y-axis, or None for no unit

  • zunit – Unit for the z-axis (color scale), or None for no unit

  • show_itemlist – Whether to show the item list panel in the dialog, default is False

  • object_name – Object name for the dialog (for screenshot functionality)

Creation Functions#

These functions create plot items that can be passed to the low-level viewing functions.

Curve and Image Items#

sigima.viz.create_curve(x: ndarray, y: ndarray, title: str | None = None) → CurveItem[source]#

Create a curve item from x and y data

Parameters:

  • x – X data array

  • y – Y data array

  • title – Label for the curve, or None for no label

Returns:

A CurveItem representing the curve

sigima.viz.create_image(data: ndarray, title: str | None = None, interpolation: str = 'linear', colormap: str | None = None, alpha_function: str | None = None, xdata: list[float] | None = None, ydata: list[float] | None = None) → ImageItem[source]#

Create an image item from data

Parameters:

  • data – 2D array of image data

  • title – Title for the image

  • interpolation – Interpolation method for image display

  • colormap – Colormap for the image, or None for default

  • alpha_function – Alpha function for the image, or None for default

  • xdata – X coordinates for the image (optional)

  • ydata – Y coordinates for the image (optional)

Annotation Items#

sigima.viz.create_contour_shapes(coords: ndarray, shape: ContourShape) → list[AnnotatedShape][source]#

Create plotpy items for a specific contour shape.

Parameters:

  • coords – Coordinates of the contours

  • shape – ContourShape enum value

Returns:

List of plotpy items representing the detected contours

sigima.viz.create_circle(xc: float, yc: float, r: float, label: str | None = None) → AnnotatedCircle[source]#

Create an annotated circle item

Parameters:

  • xc – X-coordinate of the circle center

  • yc – Y-coordinate of the circle center

  • r – Radius of the circle

  • label – Label for the circle, or None for no label

Returns:

An AnnotatedCircle object representing the circle

sigima.viz.create_segment(x0: float, y0: float, x1: float, y1: float, label: str | None = None) → AnnotatedSegment[source]#

Create an annotated segment item

Parameters:

  • x0 – X-coordinate of the start point

  • y0 – Y-coordinate of the start point

  • x1 – X-coordinate of the end point

  • y1 – Y-coordinate of the end point

  • label – Label for the segment, or None for no label

Returns:

An AnnotatedSegment object representing the segment

sigima.viz.create_cursor(orientation: Literal['h', 'v', 'x'], position: float | tuple[float, float], label: str) → Marker[source]#

Create a horizontal or vertical cursor item

Parameters:

  • orientation – ‘h’ for horizontal cursor, ‘v’ for vertical cursor, ‘x’ for crosshair

  • position – Position of the cursor along the relevant axis, or (x, y) tuple for crosshair

  • label – Label format string for the cursor

Returns:

A Marker representing the cursor

sigima.viz.create_range(orientation: Literal['h', 'v'], pos_min: float, pos_max: float, title: str) → AnnotatedXRange | AnnotatedYRange[source]#

Create a horizontal or vertical range item

Parameters:

  • orientation – ‘h’ for horizontal range, ‘v’ for vertical range

  • pos_min – Minimum position of the range along the relevant axis

  • pos_max – Maximum position of the range along the relevant axis

  • title – Title for the range

Returns:

An AnnotatedXRange or AnnotatedYRange representing the range

sigima.viz.create_label(text: str) → LabelItem[source]#

Create a text label item

Parameters:

text – Text content of the label

Returns:

A LabelItem representing the text label

sigima.viz.create_marker(x: float, y: float, title: str | None = None) → Marker[source]#

Create a marker item

Parameters:

  • x – x coordinate

  • y – y coordinate

  • title – title of the marker

Returns:

A Marker representing the marker

Backend Differences#

The two backends have different capabilities:

Feature

PlotPy

Matplotlib

Interactive zoom/pan

✅ Full Qt tools

✅ Basic toolbar

ROI display

✅ Native support

✅ Patches overlay

Geometry results

✅ Shape annotations

✅ Markers/lines

Linked axes

✅ Native

✅ via sharex/sharey

Qt integration

✅ Native

⚠️ Requires Qt backend

Headless/CI

⚠️ Needs display

✅ Agg backend

For automated testing and CI environments, Matplotlib with the Agg backend is recommended. For interactive data exploration, PlotPy provides a richer experience.