DataNode

class mitk_workbench_remote.node.PropertyScope(*values)

Bases: str, Enum

Valid scopes for node property operations.

Variables:

ALL – Include both node-scope and data-scope properties (read-only).
NODE – Node-level display properties (e.g. visible, opacity, color).
DATA – Data-level properties embedded in the data object.

ALL = 'all'

NODE = 'node'

DATA = 'data'

class mitk_workbench_remote.node.DataRepresentation(*values)

Bases: str, Enum

Return type selection for DataNode.get_data().

Variables:

AUTO – Return mitk.Image if the mitk package is importable, otherwise fall back to Image.
REMOTE – Always return the remote Python type (Image or MultiLabelSegmentation).
MITK – Always return mitk.Image; raises ImportError if the mitk package is absent.

AUTO = 'auto'

REMOTE = 'remote'

MITK = 'mitk'

class mitk_workbench_remote.node.DataNode(uid, *, name, data_type, path, parent_uid, transport)

Bases: object

A single node in the MITK DataStorage.

Wrapper that represents one node with property shortcuts (name, visible, opacity, color), data access (get_data, set_data), child management, and batch property updates.

Do not construct directly — obtain instances from DataStorage.

Display-only caches (_name, _path, _parent_uid) are seeded from the node dict at construction and refreshed by refresh(). Property getters for name, visible, opacity, and color always make a live REST call.

Parameters:

uid (str) – Immutable node identifier.
name (str) – Initial display name (cached; used by __repr__).
data_type (str | None) – MITK data type string (e.g. "Image"), updated by refresh().
path (str) – Full storage path (e.g. "/CT_Scan/seg"), updated by refresh().
parent_uid (str | None) – UID of the parent node, or None for top-level nodes.
transport (RestTransport) – Transport used for all HTTP calls.

property uid: str: Immutable node identifier.

property data_type: str | None: MITK data type string (e.g. "Image"). Updated by refresh().

property path: str: Full storage path (e.g. "/CT_Scan/seg"). Updated by refresh().

property transport: RestTransport

REST transport used for all HTTP calls. Read-only.

Exposed so callers can verify two handles share the same Workbench instance (node.transport is other.transport) without reaching into private state.

property name: str: Node display name. Always fetches from the server.

property visible: bool: Node visibility flag. Always fetches from the server.

property opacity: float: Node opacity (0.0 - 1.0). Always fetches from the server.

property color: tuple[float, float, float]: Node color as an (r, g, b) tuple. Always fetches from the server.

update_properties(*, scope=PropertyScope.NODE, context=None, **kwargs)

Update multiple properties in a single PATCH request.

Property values are serialized using the same rules as set_property(). Pass color as a (r, g, b) tuple; all other built-in properties accept plain Python values.

Parameters:

scope (PropertyScope (default: <PropertyScope.NODE: 'node'>)) – Property scope (NODE or DATA).
context (str | None (default: None)) – Optional renderer context identifier. Only relevant for scope NODE; ignored at data scope.
**kwargs (Any) – Property key-value pairs to update.

Return type:

None

get_properties(*, scope=PropertyScope.ALL, context=None)

Fetch all properties for this node.

Parameters:

scope (PropertyScope (default: <PropertyScope.ALL: 'all'>)) – Property scope filter.
context (str | None (default: None)) – Optional renderer context identifier.

Return type:

dict[str, Any]

Returns:

Mapping of property name to deserialized value.

get_property(key, *, scope=PropertyScope.ALL, context=None)

Fetch a single property by key.

Parameters:

key (str) – Property name (e.g. "name", "visible").
scope (PropertyScope (default: <PropertyScope.ALL: 'all'>)) – Property scope filter.
context (str | None (default: None)) – Optional renderer context identifier.

Return type:

Any

Returns:

Deserialized property value.

Raises:

NodeNotFoundError – If the node or property does not exist.

set_property(key, value, *, scope=PropertyScope.NODE, context=None)

Set a single property by key.

Pass color as a (r, g, b) tuple. Unknown complex types can be round-tripped by passing the raw wire dict (any dict that has a "type" key is passed through unchanged).

Parameters:

key (str) – Property name.
value (Any) – New value. Built-in types are serialized automatically; raw dicts with a "type" key are forwarded as-is.
scope (PropertyScope (default: <PropertyScope.NODE: 'node'>)) – Property scope (NODE or DATA).
context (str | None (default: None)) – Optional renderer context identifier. Only relevant for scope NODE; ignored at data scope.

Return type:

None

remove_property(key, *, scope=PropertyScope.NODE)

Remove a property by key.

Parameters:

key (str) – Property name to remove.
scope (PropertyScope (default: <PropertyScope.NODE: 'node'>)) – Property scope (NODE or DATA).

Return type:

None

property children: list[DataNode]: Child nodes of this node. Always fetches from the server.

remove(*, recursive=False)

Remove this node from the DataStorage.

Parameters:: recursive (bool (default: False)) – When True, also remove all child nodes.
Raises:: NodeNotFoundError – If the node no longer exists.
Return type:: None

refresh()

Refresh cached properties from the server.

Updates data_type, path, and the display caches for _name and _parent_uid.

Raises:: NodeNotFoundError – If the node no longer exists.
Return type:: None

get_data(*, include_properties=False, as_type=DataRepresentation.AUTO)

Download this node’s data and return a typed Python object.

The returned type depends on the node’s data_type and the as_type parameter:

"Image" with as_type=AUTO – returns mitk.Image if the mitk package is importable, otherwise Image.
"Image" with as_type=REMOTE – always returns Image.
"Image" with as_type=MITK – always returns mitk.Image; raises ImportError if the mitk package is absent.
"MultiLabelSegmentation" with as_type=AUTO – returns mitk.MultiLabelSegmentation if the mitk package is importable, otherwise MultiLabelSegmentation.
"MultiLabelSegmentation" with as_type=REMOTE – always returns MultiLabelSegmentation.
"MultiLabelSegmentation" with as_type=MITK – always returns mitk.MultiLabelSegmentation; raises ImportError if the mitk package is absent.

The transfer mode (direct or file-reference) is negotiated automatically based on the transport’s transfer_mode.

Parameters:

include_properties (bool (default: False)) – If True, also fetch data-scope properties and store them in the returned object’s properties. For mitk.Image results, scalar properties (str/bool/int/float/ 3-tuple) are applied via mitk.Image.set_property; exotic types that cannot be auto-wrapped are logged at WARNING and skipped.
as_type (DataRepresentation (default: <DataRepresentation.AUTO: 'auto'>)) – Controls the Python type of the returned image object. Defaults to DataRepresentation.AUTO.

Return type:

Any

Returns:

A typed Python object matching the node’s data type.

Raises:

UnsupportedDataTypeError – If the data type cannot be represented in Python. Use save_data() to download raw bytes instead.
ImportError – If as_type=MITK and the mitk package is not installed.

save_data(path)

Download this node’s data and save the raw bytes to a file.

This works for any data type, including types that cannot be represented in Python (e.g. Surface, PointSet). The file is saved in NRRD format as delivered by the server.

Parameters:: path (str | Path) – Destination file path. Parent directory must exist.
Return type:: Path
Returns:: The resolved Path that was written.

set_data(data, *, include_properties=False)

Upload data to this node.

Accepts an Image, a numpy ndarray, or any type handled by the converter registry (e.g. SimpleITK.Image, mlarray.MLArray, mitk.Image, mitk.MultiLabelSegmentation). The transfer mode is chosen automatically.

After a successful upload, data_type is updated locally to reflect the uploaded type without requiring an explicit refresh() call.

Property behavior for mitk.* types: When data is a mitk.Image or mitk.MultiLabelSegmentation, MITK’s NRRD serialization embeds the full C++ property list in the uploaded bytes. Data-scope properties are therefore always transferred, regardless of include_properties. This differs from Image and MultiLabelSegmentation where include_properties=False (the default) leaves existing server-side properties untouched.

Parameters:

data (Any) – Pixel data or a convertible object.
include_properties (bool (default: False)) – If True, also upload the data’s properties as data-scope properties. Has no additional effect for mitk.Image or mitk.MultiLabelSegmentation because properties are already embedded in the NRRD bytes.

Raises:

UnsupportedDataTypeError – If the node’s data type does not match the data being uploaded.
TypeError – If no converter is registered for data’s type.

Return type:

None

reinit()

Fit render window cameras to this node’s geometry.

Convenience wrapper around POST /rendering/reinit for a single node. Equivalent to workbench.reinit([self]).

Raises:

ApiError – If this 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