Editors

Handles for the StdMultiWidget and MxN render-window editors, including the typed MxN layout surface. Workbench.std_multi and Workbench.mxn return the editor handles below; every state read goes to the network.

Shared handles

Editor and render-window primitives shared by all editor types.

Public types:: WindowKind, ViewDirection, StandardView, EditorAlias — vocabulary. EditorDescriptor, EditorInfo — discovery payloads. WindowSummary, MxNWindowSummary — per-window summaries. Camera — camera GET + PUT body. SliceBounds, SelectedSlice — per-window slice state. EditorBase, RenderWindow — base classes for editors.

class mitk_workbench_remote.editors._base.WindowKind(*values)

Bases: str, Enum

Render-window kind (drives which sub-resources apply).

TWO_D = '2d'

THREE_D = '3d'

class mitk_workbench_remote.editors._base.ViewDirection(*values)

Bases: str, Enum

Anatomical plane / view direction.

Mirrors mitk.mxn.layout.ViewDirection value-for-value so that the editors module remains usable without the optional mitk package installed.

AXIAL = 'axial'

SAGITTAL = 'sagittal'

CORONAL = 'coronal'

ORIGINAL = 'original'

class mitk_workbench_remote.editors._base.StandardView(*values)

Bases: str, Enum

Standard camera orientations accepted by the camera PUT endpoint.

ANTERIOR = 'anterior'

POSTERIOR = 'posterior'

LEFT = 'left'

RIGHT = 'right'

CRANIAL = 'cranial'

CAUDAL = 'caudal'

class mitk_workbench_remote.editors._base.EditorAlias(*values)

Bases: str, Enum

Stable short aliases for the built-in MITK editors.

STD_MULTI = 'stdmulti'

MXN = 'mxn'

class mitk_workbench_remote.editors._base.EditorDescriptor(alias, plugin_id, active)

Bases: object

Editor list entry returned by GET /rendering/editors.

Variables:

alias – Stable short alias used in URL paths.
plugin_id – Berry editor plugin id.
active – True if an editor instance is currently open.

alias: str

plugin_id: str

active: bool

class mitk_workbench_remote.editors._base.EditorInfo(alias, plugin_id, active, windows)

Bases: object

Editor metadata returned by GET /rendering/editors/{alias}.

Variables:

alias – Stable short alias used in URL paths.
plugin_id – Berry editor plugin id.
active – True if an editor instance is currently open.
windows – Current window identifiers (URL segments for sub-resources). Empty when the editor is inactive.

alias: str

plugin_id: str

active: bool

windows: tuple[str, ...]

class mitk_workbench_remote.editors._base.WindowSummary(id, kind, view_direction, has_camera, has_selected_slice)

Bases: object

Per-window summary common to every editor type.

The contract guarantees view_direction is present iff kind == WindowKind.TWO_D; the StdMulti 3D window omits it.

Variables:

id – Render window id (URL segment for sub-resources).
kind – Window kind (2D vs. 3D).
view_direction – Anatomical plane the slot renders. None for 3D.
has_camera – Whether the camera sub-resource applies.
has_selected_slice – Whether the selected-slice sub-resource applies.

id: str

kind: WindowKind

view_direction: ViewDirection | None

has_camera: bool

has_selected_slice: bool

class mitk_workbench_remote.editors._base.MxNWindowSummary(id, kind, view_direction, has_camera, has_selected_slice, display_name, links, has_selected_position)

Bases: WindowSummary

MxN cell summary — extends WindowSummary with layout fields.

Variables:

display_name – Optional human-readable label from the layout document. None when the cell has no display name.
links – Per-cell synchronisation links from the layout document (at minimum {"selection": <group>} under v2).
has_selected_position – Always True under v2 (per-cell selected position is a v2 capability, distinct from the global resource).

display_name: str | None

links: Mapping[str, str]

has_selected_position: bool

class mitk_workbench_remote.editors._base.SliceBounds(steps, min_position, max_position)

Bases: object

Bounds of a slice navigator.

Variables:

steps – Total step count.
min_position – World position of the first slice. None when no geometry is loaded.
max_position – World position of the last slice. None when no geometry is loaded.

steps: int

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

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

class mitk_workbench_remote.editors._base.SelectedSlice(step, position, bounds)

Bases: object

Selected-slice state for a 2D window.

Variables:

step – Current step index.
position – World position on the live slice plane.
bounds – Navigator bounds.

step: int

position: tuple[float, float, float]

bounds: SliceBounds

class mitk_workbench_remote.editors._base.Camera(kind=None, position=None, focal_point=None, view_up=None, parallel_scale=None, perspective_angle=None, standard_view=None)

Bases: object

Render-window camera state.

Used both as a GET response (full state, with kind set and the irrelevant axis nulled out) and as a PUT body (any subset of fields; None fields are omitted from the wire payload). 2D windows carry parallel_scale; the 3D window carries perspective_angle.

kind is local-only metadata: the contract response carries no kind field. RenderWindow.get_camera() populates it from the surrounding window’s known kind.

Variables:

kind – Local-only window kind label; ignored on PUT.
position – Camera origin in world coordinates.
focal_point – Point the camera looks at, in world coordinates.
view_up – View-up vector in world coordinates.
parallel_scale – Orthographic zoom (2D windows only).
perspective_angle – Vertical FOV in degrees (3D window only).
standard_view – Symbolic camera orientation. Cannot be combined with explicit pose fields (position / focal_point / view_up) on PUT — server rejects with 400.

kind: WindowKind | None = None

position: tuple[float, float, float] | None = None

focal_point: tuple[float, float, float] | None = None

view_up: tuple[float, float, float] | None = None

parallel_scale: float | None = None

perspective_angle: float | None = None

standard_view: StandardView | str | None = None

to_payload()

Build the JSON body for a camera PUT — drops None fields.

Return type:: dict[str, Any]

replace(**fields)

Return a new Camera with the given fields overridden.

Return type:: Camera

diff(other)

Return a Camera carrying only fields that differ from other.

kind is preserved from self (it is local metadata, never diffed). A field is “different” iff it is non-None on self and not equal to the value on other. When self.kind is set, the scalar that does not apply to that kind (perspective_angle for 2D, parallel_scale for 3D) is dropped from the result so to_payload() cannot produce a body the server rejects.

Return type:: Camera

class mitk_workbench_remote.editors._base.EditorBase(transport)

Bases: object

Common behaviour for editor handles.

Subclasses set the ALIAS class variable to the editor’s URL alias (e.g. "stdmulti" or "mxn"). Editor handles hold only the transport — every state read goes to the network.

ALIAS: ClassVar[str] = ''

property alias: str: Editor alias (URL segment).

get_info()

Fetch the editor’s metadata (always live).

Returns a degraded EditorInfo with active=False and empty windows when the editor exists but no instance is open (server signals EDITOR_NOT_ACTIVE). A missing Qt render-window bridge (RENDER_WINDOW_NOT_AVAILABLE) is a deployment-level problem and still surfaces as RenderingError.

Return type:: EditorInfo

property is_active: bool: Whether an editor instance is currently open. Always live.

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

Capture a screenshot of the editor canvas.

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.

list_windows()

List the editor’s render windows. Always live.

Return type:: list[RenderWindow]

get_window(window_id)

Get a render-window handle by its id (no network call).

Return type:: RenderWindow

class mitk_workbench_remote.editors._base.RenderWindow(transport, editor_alias, window_id, *, kind=None)

Bases: object

Handle to a single render window of an editor.

Parameters:

transport (RestTransport) – Configured REST transport.
editor_alias (str) – Editor alias the window belongs to.
window_id (str) – Render-window id (URL segment).
kind (WindowKind | None (default: None)) – Optional eager WindowKind populated by the editor’s window listing. Cached because the kind of a window is an immutable identity field. Falls back to a network call when None.

Note

view_direction is intentionally NOT cached: MxN cells can be re-bound to a different anatomical plane at runtime. Reading view_direction always issues a fresh GET against the per-window summary so callers see the live server state.

property id: str: Render-window id (URL segment for sub-resources).

property editor_alias: str: Alias of the editor this window belongs to.

property kind: WindowKind: Window kind. Immutable identity field — cached after first resolution. Resolved via GET .../windows/{id} on first access when not pre-populated by the editor’s window listing.

property view_direction: ViewDirection | None: View direction. None for 3D windows. Always live — MxN cells can be re-bound to a different anatomical plane at runtime, so this is not cached.

get_summary()

Fetch the per-window summary from the server (always live).

Return type:: WindowSummary

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

Capture a screenshot of this single render window.

Return type:: bytes

get_camera()

Fetch the current camera state.

Return type:: Camera

set_camera(camera=None, /, **fields)

Update the camera state.

Two call shapes:

Value form: set_camera(Camera(parallel_scale=120)) — sends the camera’s non-None fields.
Kwargs form: set_camera(parallel_scale=120, standard_view="anterior") — equivalent to building a one-off Camera.

Mixing the two raises TypeError.

Return type:: None

get_selected_slice()

Fetch the selected-slice state.

Raises:: UnsupportedOperationError – For the StdMulti 3D window.
Return type:: SelectedSlice

set_selected_slice(step)

Step the slice navigator to a target index.

step is not range-checked — out-of-range values are clamped or snapped by MITK.

Raises:: UnsupportedOperationError – For the StdMulti 3D window.
Return type:: None

set_node_visible(node, visible)

Set this node’s per-window visibility property.

Return type:: None

is_node_visible(node)

Read this node’s per-window visibility property.

Return type:: bool

set_node_layer(node, layer)

Set this node’s per-window layer (stack order) property.

Return type:: None

get_node_layer(node)

Read this node’s per-window layer (stack order) property.

Return type:: int

StdMultiWidget editor

StdMultiWidget editor handle.

Wraps GET /rendering/editors/stdmulti and its sub-resources.

class mitk_workbench_remote.editors.std_multi.StdMultiEditor(transport)

Bases: EditorBase

Handle to the StdMultiWidget editor (axial / sagittal / coronal / 3d).

ALIAS: ClassVar[str] = 'stdmulti'

property axial: RenderWindow: The axial 2D window.

property sagittal: RenderWindow: The sagittal 2D window.

property coronal: RenderWindow: The coronal 2D window.

property three_d: RenderWindow: The 3D window. Equivalent to editor["3d"] ("3d" is not a valid Python identifier, hence the spelled-out alias).

MxN editor and layout

MxN multi-widget editor handle and per-cell render-window handle.

Wraps GET /rendering/editors/mxn and its sub-resources, plus the layout endpoint (GET/PUT /rendering/editors/mxn/layout).

Layout I/O comes in two flavours:

Raw-dict (always available): MxNEditor.get_layout_json() and set_layout(dict) move the wire JSON unchanged. No DSL dependency.
Typed (requires the optional mitk package): MxNEditor.get_layout(), set_layout(MxNLayoutDocument), MxNEditor.update_layout(), MxNEditor.apply_grid(), MxNEditor.apply_preset() use the mitk.mxn.layout DSL for typed construction, validation, and bulk transforms.

class mitk_workbench_remote.editors.mxn.MxNRenderWindow(transport, editor_alias, window_id, *, kind=None)

Bases: RenderWindow

Handle to a single MxN cell.

Adds the per-cell selected-position primitive and overrides get_summary() to return the richer MxNWindowSummary.

kind is resolved via the inherited base-class accessor: cached when eagerly populated by MxNEditor.list_windows(), otherwise fetched lazily through get_summary(). No client-side assumption about which cell kinds the active schema supports.

get_summary()

Fetch the per-cell summary (always live).

Return type:: MxNWindowSummary

get_selected_position()

Fetch this cell’s 3D world anchor and scene bounds.

Return type:: SelectedPosition

set_selected_position(position)

Set this cell’s 3D world anchor.

Distinct from the global /rendering/selected-position resource: whether the change propagates to other cells or to the global anchor depends on the workbench’s interactive coupling toolbar state, which is intentionally not exposed via REST.

Parameters:: position (tuple[float, float, float] | Sequence[float]) – Target world position [x, y, z].
Raises:: ValueError – If position does not have exactly 3 elements.
Return type:: None

class mitk_workbench_remote.editors.mxn.MxNEditor(transport)

Bases: EditorBase

Handle to the MxN multi-widget editor.

Cell ids are the canonical fully-qualified form <editor_name>__<bare> (e.g. "mxn__widget0"). The same string appears in the URL, the layout document, and the engine — no prefix translation happens at any boundary.

ALIAS: ClassVar[str] = 'mxn'

list_windows()

List the editor’s cells (in pre-order traversal of the layout).

Return type:: list[MxNRenderWindow]

get_window(window_id)

Get a render-window handle by its id (no network call).

Return type:: MxNRenderWindow

get_layout_json()

Fetch the current layout document as a raw dict.

Returns the JSON body unchanged — no DSL parsing — so callers can round-trip the layout byte-for-byte without a mitk install.

Return type:: dict[str, Any]

get_layout()

Fetch the current layout, parsed into a typed MxNLayoutDocument. Requires the optional mitk package.

Return type:: MxNLayoutDocument

set_layout(layout)

Apply a layout document to the editor.

Accepts:

MxNLayoutDocument — sent as-is (trusted; the DSL validates on construction). Requires the optional mitk package.
Mapping (raw dict) — sent as-is, no client-side validation. Always available; the server enforces the schema and surfaces 400 INVALID_REQUEST on a malformed body.
JSON str or pathlib.Path — parsed via MxNLayoutDocument.from_json() and validated client-side before PUT (catches typos / missing groups before a wasted round-trip). Requires the optional mitk package.

Returns the freshly-serialized layout returned by the server in the PUT response (same shape as get_layout_json()).

All existing cells are torn down and rebuilt from the document — any cell handle a caller cached prior to the call is invalid afterwards.

Return type:: dict[str, Any]

update_layout(transform)

GET the layout, apply transform, validate, PUT it back.

transform receives the freshly-fetched typed MxNLayoutDocument and returns a new one (DSL operations are immutable). The returned document is validated client-side before PUT; the parsed PUT response is returned to the caller.

Idiomatic use:

from mitk.mxn.layout import MxNWindowSelector, ViewDirection

def link_axials(doc):
    return (
        MxNWindowSelector(doc)
        .by_view(ViewDirection.AXIAL)
        .link_to("axial_group")
    )

wb.mxn.update_layout(link_axials)

Return type:: MxNLayoutDocument

apply_grid(rows, cols, *, view_directions=None, group='main')

Apply a fresh rows x cols grid layout.

Returns the freshly-serialized layout from the PUT response, parsed back into a typed MxNLayoutDocument.

Return type:: MxNLayoutDocument

apply_preset(name)

Apply a named preset from mitk.mxn.layout.PRESETS.

Returns the freshly-serialized layout from the PUT response, parsed back into a typed MxNLayoutDocument.

Return type:: MxNLayoutDocument