Data and actions

InputSpec

InputSpec dataclass

InputSpec(key, label, required=True)

Describe one named data input exposed to the web client.

to_dict

to_dict()

Return a JSON-serializable representation.

Action parameters

ParameterSpec dataclass

ParameterSpec(
    name,
    type,
    default,
    label=None,
    description=None,
    minimum=None,
    maximum=None,
    step=None,
    options=(),
    unit=None,
    placeholder=None,
    annotation_type=None,
)

Describe and validate one browser-editable action parameter.

validate

validate(value)

Validate and normalize one value received from the browser.

to_dict

to_dict()

Return the browser-safe parameter descriptor.

BoolParameter

BoolParameter(
    name, *, default=False, label=None, description=None
)

Bases: ParameterSpec

Boolean action parameter.

IntParameter

IntParameter(
    name,
    *,
    default,
    label=None,
    description=None,
    minimum=None,
    maximum=None,
    step=None,
    unit=None
)

Bases: ParameterSpec

Integer action parameter.

FloatParameter

FloatParameter(
    name,
    *,
    default,
    label=None,
    description=None,
    minimum=None,
    maximum=None,
    step=None,
    unit=None
)

Bases: ParameterSpec

Floating-point action parameter.

StringParameter

StringParameter(
    name,
    *,
    default="",
    label=None,
    description=None,
    placeholder=None
)

Bases: ParameterSpec

Text action parameter.

ChoiceParameter

ChoiceParameter(
    name,
    *,
    options,
    default=None,
    label=None,
    description=None
)

Bases: ParameterSpec

Action parameter restricted to a finite set of string values.

AnnotationParameter

AnnotationParameter(
    name, *, annotation_type, label=None, description=None
)

Bases: ParameterSpec

Action parameter the user fills in by drawing in the viewer.

The callback receives an Annotation, not an id: the browser sends the id and it is exchanged for the object when the action runs.

WebAppDataModel

WebAppDataModel

WebAppDataModel(webapp, session=None)

A DataModel that mirrors the imfusion.DataModel API and syncs with the web client.

This class provides the same interface as imfusion.DataModel: - add(data, name='') - Add data to the model - remove(data) - Remove data from the model (by reference or index) - clear() - Remove all data - get(name) - Get data by name - contains(data) - Check if data is in the model - index(data) - Get index of data - size (property) - Number of items - getitem(index) - Get data by index - len() - Get number of items - iter() - Iterate over items

When data is modified, the changes are automatically synced to the web client.

Example

webapp = ImFusionWebApp() webapp.initial_data.add(my_image, "CT Scan") webapp.initial_data.remove(0) webapp.initial_data.clear()

Initialize the WebAppDataModel.

Parameters:

Name	Type	Description	Default
webapp	ImFusionWebApp	The ImFusionWebApp instance this data model belongs to	required
session	Optional[Session]	Optional Session instance (used for per-session isolation)	None

size property

size

Return the total amount of data in the model.

add_change_listener

add_change_listener(callback)

Subscribe to model mutations without coupling the transport to features.

add_data_invalidation_listener

add_data_invalidation_listener(callback)

Subscribe to a dataset's client-side copy being destroyed.

The callback receives the data about to be invalidated, or None when the whole model is going. Distinct from :meth:add_change_listener because it fires before the message reaches the browser: anything the client keys by dataset, such as annotations, has to be torn down first or the Web SDK is left holding a freed pointer.

__len__

__len__()

Return the number of items in the model.

__getitem__

__getitem__(index)

Get data by index.

Supports: - Single index: data_model[0] - Slice: data_model[0:3] - List of indices: data_model[[0, 2, 4]]

__iter__

__iter__()

Iterate over all data items.

add

add(data, name='', source_path=None)

Add data to the model.

Parameters:

Name	Type	Description	Default
data	Any	The data to add (e.g., SharedImageSet)	required
name	str	Optional name for the data	''
source_path	Optional[str]	Where the data was loaded from, for apps that export references to their inputs	None

Returns:

Type	Description
Any	The added data (same reference, unlike imfusion.DataModel which copies)

update

update(index)

Sync updated data at the given index back to the client.

Call this after modifying data in-place to push the changes to the web client's visualization.

Parameters:

Name	Type	Description	Default
index	int	Index of the data that was modified	required

Example

imageset = app.data_model[0]

... modify imageset ...

app.data_model.update(0) # Sync changes to client

update_metadata

update_metadata(index)

Sync a metadata-only change at index without resending pixels.

The caller asserts that the pixels are untouched; they are never inspected, because comparing them would cost as much as sending them.

Returns True when the change travelled as metadata, and False when it had to fall back to a full transfer.

Example

imageset.modality = imfusion.Data.Modality.LABEL app.data_model.update_metadata(app.data_model.index(imageset))

replace

replace(index, data, name=None)

Replace data at an existing index and refresh the client in place.

remove

remove(data_or_index)

Remove data from the model.

Parameters:

Name	Type	Description	Default
data_or_index	Union[Any, int]	Either the data object to remove, or its index	required

clear

clear()

Remove all data from the model.

get

get(name)

Get data by name.

Parameters:

Name	Type	Description	Default
name	str	The name of the data to find	required

Returns:

Type	Description
Optional[Any]	The data if found, None otherwise

contains

contains(data)

Check if data is in the model.

index

index(data)

Return index of data.

Parameters:

Name	Type	Description	Default
data	Any	The data to find	required

Returns:

Type	Description
int	The index of the data

Raises:

Type	Description
ValueError	If data is not in the model

get_name

get_name(data_or_index)

Get the name of a data item.

Parameters:

Name	Type	Description	Default
data_or_index	Union[Any, int]	Either the data object or its index	required

Returns:

Type	Description
str	The name of the data

get_source_path

get_source_path(data_or_index)

Where a data item was loaded from, or None when that is unknown.

Known for data the server loaded itself, through app.open() or seeded into initial_data. Always None for anything the browser supplied, including sample datasets, because a browser does not expose a real filesystem path.

set_name

set_name(data_or_index, name)

Set the name of a data item.

Parameters:

Name	Type	Description	Default
data_or_index	Union[Any, int]	Either the data object or its index	required
name	str	The new name	required

Annotations

See the annotations guide for how these fit together.

AnnotationType

Bases: str, Enum

Annotation shapes the browser can place.

Values are the Web SDK's own literals and are passed through to annotationModel.add() unchanged, so supporting a new shape is an entry here and nothing else. The Python SDK also defines CIRCLE and POLY_LINE, which the Web SDK does not bind yet; see docs/guides/annotations.md.

Annotation

Annotation(
    model, annotation_type, data, annotation_id=None
)

One annotation, created through :meth:WebAnnotationModel.create_annotation.

Points are world coordinates, matching the Web SDK. Use :meth:points_in to express them in a dataset's own frame, which is what you want whenever the value has to outlive a change to that dataset's transform.

data property

data

The dataset this annotation belongs to.

points property writable

points

Control points in world coordinates.

max_points property

max_points

Points this shape holds, as reported by the SDK.

None until the browser has created the annotation, because the value is read from its state rather than hardcoded per type.

length property

length

Distance between the endpoints of a :attr:AnnotationType.LINE.

angle property

angle

Angle in degrees at the vertex of an :attr:AnnotationType.ANGLE.

The middle control point is taken as the vertex.

name property writable

name

Identifier shown in lists; the SDK generates one when left empty.

label property writable

label

Text drawn next to the annotation in the viewer.

complete property

complete

True once the user has finished placing this annotation.

editing property

editing

True while the browser is waiting for the user to place points.

error property

error

Why placement failed, or an empty string.

Set when the browser cannot create the shape — typically an annotation type its Web SDK build does not support. Populated asynchronously, so it is empty immediately after :meth:start_editing.

points_in

points_in(data=None)

Return the points in data's own coordinate frame.

Defaults to the annotation's parent dataset. World coordinates are only meaningful while the dataset's transform stays put, so anything that survives a registration or a reslice should be stored in this frame.

start_editing

start_editing()

Ask the browser to let the user place this annotation.

on_editing_finished

on_editing_finished(callback)

Register a callback for when the user finishes placing the annotation.

on_points_changed

on_points_changed(callback)

Register a callback for every change to the annotation's points.

remove

remove()

Remove this annotation from its model.

WebAnnotationModel

WebAnnotationModel(host, session)

Browser-session equivalent of imfusion.AnnotationModel.

create_annotation

create_annotation(annotation_type, data=None)

Create an annotation belonging to data.

Nothing reaches the browser yet: the Web SDK's add() immediately arms interactive placement, so creation is deferred until :meth:Annotation.start_editing or until points are assigned.

data defaults to the session's selection, because the Web SDK requires a parent dataset even though the Python SDK does not.

annotations

annotations()

Every annotation in this session.

data_annotations

data_annotations(data)

Annotations belonging to data.

remove

remove(annotation)

Remove one annotation from the model and the browser.

clear

clear()

Remove every annotation.

on_annotation_added

on_annotation_added(callback)

Register a callback for annotations the user starts in the browser.

Called with the new annotation, which has no points yet: the browser reports it as soon as the user picks a tool. Register :meth:Annotation.on_editing_finished on it to hear the geometry.

Unlike the annotation's own callbacks, which mirror the Python SDK's no-argument signature, this one has no SDK counterpart and always passes the annotation — there is no other way to reach it.