Workbench

Workbench handle — primary entry point for controlling a MITK Workbench instance.

class mitk_workbench_remote.workbench.WorkbenchInfo(name, api_version, mitk_version, url)

Bases: object

Metadata about a MITK Workbench instance.

Variables:

name – Human-readable server name.
api_version – REST API version string (e.g. "v1").
mitk_version – Underlying MITK framework version string.
url – Base URL of the Workbench REST server.

name: str

api_version: str

mitk_version: str

url: str

class mitk_workbench_remote.workbench.PositionBounds(min_position, max_position)

Bases: object

World-space axis-aligned bounding box of the scene.

Variables:

min_position – Minimum corner [x, y, z], or None if no geometry is loaded.
max_position – Maximum corner [x, y, z], or None if no geometry is loaded.

min_position: tuple[float, float, float] | None

max_position: tuple[float, float, float] | None

class mitk_workbench_remote.workbench.SelectedPosition(position, bounds)

Bases: object

Current crosshair position and scene bounds.

Variables:

position – Crosshair position in world coordinates [x, y, z].
bounds – Scene bounding box.

position: tuple[float, float, float]

bounds: PositionBounds

class mitk_workbench_remote.workbench.TimeBounds(min_timepoint_ms, max_timepoint_ms, steps)

Bases: object

Time geometry bounds.

Variables:

min_timepoint_ms – Start of the time range in milliseconds.
max_timepoint_ms – End of the time range in milliseconds.
steps – Total number of time steps.

min_timepoint_ms: float

max_timepoint_ms: float

steps: int

class mitk_workbench_remote.workbench.SelectedTime(timepoint_ms, timestep, bounds)

Bases: object

Current time navigation state.

Variables:

timepoint_ms – Selected time point in milliseconds.
timestep – Selected time step index (zero-based).
bounds – Time geometry bounds.

timepoint_ms: float

timestep: int

bounds: TimeBounds

class mitk_workbench_remote.workbench.ReinitMode(*values)

Bases: str, Enum

Controls automatic reinit behavior after show().

Variables:

ALL_VISIBLE – Global reinit – fit all views to all visible data.
NODE – Node reinit – fit views to the newly shown node only.
NONE – Skip reinit entirely.

ALL_VISIBLE = 'all'

NODE = 'node'

NONE = 'none'

class mitk_workbench_remote.workbench.RenderWindows(*values)

Bases: str, Enum

Which render windows to update.

Variables:

ALL – Update all render windows.
TWO_D – Update only 2-D render windows.
THREE_D – Update only the 3-D render window.

ALL = 'all'

TWO_D = '2d'

THREE_D = '3d'

class mitk_workbench_remote.workbench.ScreenshotFormat(*values)

Bases: str, Enum

Image encoding format for screenshots.

Variables:

PNG – Lossless PNG encoding.
JPEG – Lossy JPEG encoding.

PNG = 'png'

JPEG = 'jpeg'

class mitk_workbench_remote.workbench.Workbench(transport, *, process=None, stderr_log_path=None)

Bases: object

Handle to a running MITK Workbench instance.

Do not instantiate directly — use connect() or launch().

Parameters:

transport (RestTransport) – Configured REST transport for the target instance.
process (Popen[bytes] | None (default: None)) – Optional subprocess handle when the instance was started via launch().
stderr_log_path (str | None (default: None)) – Optional path to the temp file capturing the launched child’s stderr. Removed best-effort on shutdown().

property url: str: Base URL of the Workbench REST server.

property is_launched_remotely: bool: Returns if the workbench was launched remotely (true) or was just connected to but is independent (false).

property info: WorkbenchInfo

Metadata about the connected Workbench instance.

Fetched lazily from GET /api/v1/info on first access and cached thereafter.

property storage: DataStorage: The DataStorage for this Workbench instance. Lazy and cached.

property std_multi: StdMultiEditor

Handle to the StdMultiWidget editor. Lazy and cached.

The handle holds only the transport — every state read goes to the network. Use is_active on the returned handle (or editors()) to check whether the editor is currently open.

property mxn: MxNEditor: Handle to the MxN multi-widget editor. Lazy and cached.

editor(alias)

Return an editor handle by alias.

Accepts either a raw alias string ("stdmulti", "mxn") or an EditorAlias member. For the well-known aliases this returns the same instance as the named property (std_multi / mxn). Unknown aliases raise ValueError.

Return type:: EditorBase

editors()

List all known editors with their current activity state.

Sends GET /rendering/editors. Always live — the active state of an editor changes at runtime as the user opens or closes it.

Return type:: list[EditorDescriptor]

ping()

Check whether the Workbench is reachable.

Sends a GET /health request. Returns False for any failure — network errors, HTTP errors, or unexpected exceptions — without raising.

Return type:: bool
Returns:: True if the server responded with a 2xx status, False otherwise.

property is_connected: bool: Whether the Workbench is currently reachable. Alias for ping().

show(data, *, name=None, visible=True, opacity=None, color=None, parent=None, hide_others=False, reinit=ReinitMode.ALL_VISIBLE)

One-liner to load data into the Workbench and display it.

Creates a new node, uploads the data, sets display properties, and optionally reinitializes the render views.

Parameters:

data (Any) – Data to show. Accepts file paths (str / Path), Image, MultiLabelSegmentation, numpy arrays, or any type handled by the converter registry.
name (str | None (default: None)) – Node display name. Inferred from data when None.
visible (bool (default: True)) – Whether the node is visible after showing.
opacity (float | None (default: None)) – Node opacity (0.0 - 1.0). None keeps the server default.
color (tuple[float, float, float] | None (default: None)) – Node color as (r, g, b). None keeps the server default.
parent (DataNode | str | None (default: None)) – Parent node (instance or UID string). None for top-level.
hide_others (bool (default: False)) – When True, hide all existing nodes before showing.
reinit (ReinitMode (default: <ReinitMode.ALL_VISIBLE: 'all'>)) – Auto-reinit mode after showing the data.

Return type:

DataNode

Returns:

The newly created DataNode.

update(*, windows=RenderWindows.ALL)

Request all render windows to redraw.

Use after batching data or property changes to make them visible without per-change flicker.

Parameters:: windows (RenderWindows | str (default: <RenderWindows.ALL: 'all'>)) – Which render windows to update: "all" (default), "2d", or "3d".
Raises:: RenderingError – If the rendering framework reports a failure.
Return type:: None

reinit(nodes=None)

Fit render window cameras to the bounding geometry of nodes.

Three modes:

nodes=None — global reinit: fits all views to all visible data (equivalent to clicking the global reinit button in the Workbench).
single element list — fits views to that node’s geometry.
multi-element list — fits views to the combined bounding geometry.

Parameters:

nodes (list[DataNode | str] | None (default: None)) – Nodes to reinit to. Accepts DataNode instances or UID strings. None performs a global reinit.

Raises:

ValueError – If nodes is an empty list (use None for global reinit).
NodeNotFoundError – If any listed node does not exist.
ApiError – If a node has no data (code NO_DATA) or no usable geometry (code NO_GEOMETRY).
RenderingError – If the rendering framework reports a failure.

Return type:

None

get_position()

Get the current crosshair position and scene bounds.

Return type:: SelectedPosition
Returns:: A SelectedPosition with the crosshair coordinates and the world-space bounding box.
Raises:: RenderingError – If no render window is available.

set_position(position)

Move the crosshair to the given world position.

Parameters:

position (tuple[float, float, float] | list[float]) – Target position [x, y, z] in world coordinates.

Raises:

ValueError – If position does not have exactly 3 elements.
RenderingError – If no render window is available.

Return type:

None

get_time()

Get the current time navigation state.

Return type:: SelectedTime
Returns:: A SelectedTime with the active time point, step, and bounds.
Raises:: RenderingError – If no render window is available.

set_timepoint(timepoint_ms)

Set the active time point.

Parameters:: timepoint_ms (float) – Target time point in milliseconds.
Raises:: RenderingError – If no render window is available.
Return type:: None

set_timestep(timestep)

Set the active time step.

Parameters:: timestep (int) – Target time step index (zero-based).
Raises:: RenderingError – If no render window is available.
Return type:: None

get_timepoint()

Convenience: return the current time point in milliseconds.

Return type:: float

get_timestep()

Convenience: return the current time step index.

Return type:: int

screenshot(*, fmt=ScreenshotFormat.PNG, width=None, height=None, path=None)

Capture a screenshot of the active application window.

Parameters:

fmt (ScreenshotFormat | str (default: <ScreenshotFormat.PNG: 'png'>)) – Image encoding format ("png" or "jpeg").
width (int | None (default: None)) – Output width in pixels. Must be given together with height.
height (int | None (default: None)) – Output height in pixels. Must be given together with width.
path (str | Path | None (default: None)) – If given, save the screenshot to this file path.

Return type:

bytes

Returns:

Raw image bytes.

Raises:

ValueError – If only one of width / height is given.
RenderingError – If no render window is available.

shutdown()

Terminate the subprocess started by launch().

On Windows the MITK executable is often a batch-script wrapper, so the Popen handle points to cmd.exe — not the real MitkWorkbench.exe. Killing the wrapper (or its tree) may leave the actual Workbench running. We therefore look up the process that owns the REST port via netstat and kill that.

On Unix, sends SIGTERM to the subprocess and falls back to SIGKILL after 10 seconds.

Removes the launch stderr temp file (if any) best-effort and closes the underlying transport session.

Raises:

MitkError – If this instance was not created by launch(). Use property
is_launched_remotely to check this. –

Return type:

None

close()

Close the underlying transport session.

Return type:: None