Getting Started

Prerequisites

  • Python 3.11+

  • A running MITK Workbench instance with the REST API enabled. In the Workbench, go to Window > Preferences > REST API, check Enable and Auto-start, then restart.

Installation

Base install (numpy, requests, pynrrd):

pip install mitk-workbench-remote

With optional SimpleITK and mlarray converters:

pip install mitk-workbench-remote[all]

[all] (SimpleITK + mlarray) installs on all supported Python versions. The MITK interop and layout DSL require the layout (or mitk) extra and Python 3.12 — the mitk-python wheels are 3.12-only. Install everything on 3.12 with pip install "mitk-workbench-remote[all,layout]".

Connecting to a Workbench

import mitk_workbench_remote as mw

wb = mw.connect("http://localhost:8080")

# Verify the connection
print(wb.ping())       # True
print(wb.info.name)    # "MITK Workbench REST API"
print(wb.info.mitk_version)

connect() does not make any HTTP calls — the connection is established lazily on first use. Use wb.ping() to check reachability.

Showing Data

wb.show() is the primary one-liner for displaying data in the Workbench. It accepts numpy arrays, Image objects, file paths, and any type handled by the converter registry (SimpleITK, mlarray).

import numpy as np

# Show a numpy array
arr = np.random.random((64, 64, 64)).astype(np.float32)
node = wb.show(arr, name="Random Volume")

# Show with visual properties
wb.show(arr, name="Red Volume", color=(1.0, 0.0, 0.0), opacity=0.5)

# Show a file from disk (no deserialization needed)
wb.show("scan.nrrd")

Browsing the DataStorage

# Iterate over all nodes
for node in wb.storage:
    print(f"{node.uid}  {node.name}  ({node.data_type})")

# Get a node by UID
node = wb.storage["node_1"]

# Filter by data type
images = wb.storage.list(data_type="Image")

# Count nodes
print(len(wb.storage))

In Jupyter notebooks, wb.storage renders as an interactive HTML table.

Downloading and Uploading Data

# Download image data
node = wb.storage["node_1"]
image = node.get_data()  # returns mw.Image
print(image.shape, image.spacing)

# Access the numpy array
arr = image.array

# Upload modified data
node.set_data(mw.Image(arr * 2, spacing=image.spacing))

For data types that cannot be loaded into Python (e.g. Surface, PointSet), use node.save_data("output.nrrd") to save raw bytes to disk.

Working with Segmentations

Multi-label segmentations are first-class objects with group and label management. See the MultiLabel Segmentation notebook for a full walkthrough.

seg = node.get_data()  # returns MultiLabelSegmentation
for group in seg.groups:
    for label in seg.get_group_labels(group):
        print(f"{label.value}: {label.name}")

Configuring Logging

mitk-workbench-remote uses Python’s standard logging module. By default all output is suppressed. Enable it to see HTTP requests, transfer mode negotiation, and other internals:

import logging

# Enable all debug output
logging.basicConfig(level=logging.DEBUG)

# Or target just the transport layer
logging.getLogger("mitk_workbench_remote.transport").setLevel(logging.DEBUG)

Next Steps