Workflows

Workflow

Workflow

Workflow(app, steps=None)

Manage a sequence of steps for one session controller.

run_current_step

run_current_step(action=None)

Run a manually triggered processing step or custom step action.

WorkflowStep

WorkflowStep

WorkflowStep(title, step_id=None, depends_on=None)

Bases: ABC

Base class for workflow state and presentation.

completed property writable

completed

Whether the step reports itself as finished.

clone

clone()

Return an unbound copy of this step, ready to bind to a new workflow.

Relies on subclasses resetting mutable fields to fresh objects (not mutating in place) in reset_state/reset_workflow_state.

on_data_model_changed

on_data_model_changed()

React to session data changes while this step is active.

reset_workflow_state

reset_workflow_state()

Reset state and any history retained across step navigation.

StepUIType

StepUIType

Bases: str, Enum

Built-in steps

Step	Purpose
MessageStep	Show instructional text
InputSelectionStep	Load datasets and assign them to named roles
ParameterStep	Collect typed parameter values
ProcessingStep	Run a callback and publish results
BrushStep	Edit a label map with the smart brush
AnnotationStep	Collect points, lines, boxes, or angles from the user
ValidationStep	Accept or reject a result before continuing
ExportStep	Export session data in chosen formats
CustomStep	Compose custom panel content from UI elements

MessageStep

MessageStep(title, message, step_id=None, depends_on=None)

Bases: WorkflowStep

InputSelectionStep

InputSelectionStep(
    title="Select Inputs",
    inputs=None,
    allow_upload=True,
    allow_sample_datasets=None,
    message="Load datasets, then assign each input role.",
    step_id=None,
    depends_on=None,
)

Bases: WorkflowStep

ParameterStep

ParameterStep(
    title="Configure",
    parameters=None,
    step_id=None,
    depends_on=None,
)

Bases: WorkflowStep

Collect browser-editable values using the same typed parameters as actions.

ProcessingStep

ProcessingStep(
    title="Processing",
    callback=None,
    inputs_from=None,
    parameters_from=None,
    auto_proceed=False,
    auto_run=True,
    run_label="Run",
    step_id=None,
    depends_on=None,
)

Bases: WorkflowStep

Run an action-style callback automatically or from an explicit button.

run

run()

Execute the processing callback once for the current inputs.

BrushStep

BrushStep(
    title="Edit Label Map",
    message="Start the brush, paint in the viewer, then stop it to save your edits.",
    image_from=None,
    label_map_from=None,
    image_role=None,
    label_map_role=None,
    radius_mm=10.0,
    adaptiveness=0.5,
    allow_radius_change=True,
    allow_adaptiveness_change=True,
    labels=(1,),
    label_map_name="Label Map",
    step_id=None,
    depends_on=None,
)

Bases: WorkflowStep

Create or edit a label map with the browser's smart brush.

AnnotationStep

AnnotationStep(
    title="Place Annotation",
    message="Press Place, then draw the annotation in the viewer.",
    annotation_type=AnnotationType.RECTANGLE,
    image_from=None,
    image_role=None,
    image_roles=None,
    labels=None,
    count=1,
    color=None,
    required=True,
    keep_annotations=True,
    views=None,
    show_measurements=False,
    on_finished=None,
    step_id=None,
    depends_on=None,
)

Bases: WorkflowStep

Ask the user to place annotations, then hand the geometry to Python.

One annotation is collected per entry in labels (or per count) for each role in image_roles. Placement is armed explicitly, by a button in the panel, so the first click on the canvas cannot become an annotation while the user is still navigating to the anatomy.

Parameters:

Name	Type	Description	Default
title	str	Step title shown in the workflow panel.	'Place Annotation'
message	str	Instruction shown above the placement controls.	'Press Place, then draw the annotation in the viewer.'
annotation_type	AnnotationType	Shape the user places.	RECTANGLE
image_from	Optional[str]	Step id providing the dataset to annotate, either an InputSelectionStep or a ProcessingStep. Without it the current selection is used, which must match the roles.	None
image_role	Optional[str]	Input role in image_from to annotate, when that step offers several.	None
image_roles	Optional[Sequence[str]]	Annotate one dataset per role, for example a fixed and a moving image. Each role names an input role in image_from, and keys :attr:annotations. Mutually exclusive with image_role.	None
labels	Optional[Sequence[str]]	One prompt per annotation, drawn next to it in the viewer and shown in the panel. Its length sets how many are collected.	None
count	int	How many annotations to collect, when they need no labels.	1
color	Optional[Sequence[float]]	Fixed RGB or RGBA colour. Roles get distinct colours by default.	None
required	bool	Whether the step blocks until every annotation is placed.	True
keep_annotations	bool	Leave the annotations in the viewer after the step. They are reused if the user comes back. Turn this off for geometry that stops being meaningful later, such as a landmark on an image a later step registers, because an annotation does not follow its dataset's transform.	True
views	Optional[Sequence[ViewType]]	Views the user may annotate in. Defaults to the slice views, plus the 3D view for point and box annotations.	None
show_measurements	bool	Show a line's length and an angle's angle.	False
on_finished	Optional[Callable[..., Any]]	Called once every annotation is placed, with no arguments or with the step, whichever the callback declares.	None
step_id	Optional[str]	Explicit id, for other steps to reference.	None
depends_on	Optional[List[str]]	Extra step ids that invalidate this one; image_from is added automatically.	None

annotations property

annotations

Collected annotations, keyed by role and ordered by label.

points property

points

Every annotation's world points, flattened in role then label order.

complete property

complete

Whether every requested annotation has been placed.

clear

clear()

Remove the collected annotations from the viewer.

Worth calling once the geometry has been consumed: an annotation does not follow its dataset's transform, so after a registration moves the image the annotation sits visibly detached from what it marked.

ValidationStep

ValidationStep(
    title="Review Result",
    message="Is this result acceptable?",
    step_id=None,
    depends_on=None,
)

Bases: WorkflowStep

ExportStep

ExportStep(
    title="Export",
    message="Export your results",
    formats=None,
    step_id=None,
    depends_on=None,
    require_export_before_finish=True,
)

Bases: WorkflowStep

CustomStep

CustomStep(
    title="Custom",
    body=None,
    step_id=None,
    depends_on=None,
    require_completion=False,
    completion_message="Complete this step before continuing",
)

Bases: WorkflowStep

Step whose contents are described with :mod:~imfusion_webappkit.ui_elements.

Pass a static body for a fixed layout, or subclass and override :meth:body to rebuild the elements from the current session state every time the browser refreshes. Subclasses handle button presses by overriding :meth:on_action.

Parameters:

Name	Type	Description	Default
title	str	Step title shown in the workflow panel.	'Custom'
body	Optional[Sequence[UIElement]]	Elements displayed for the step.	None
step_id	Optional[str]	Stable identifier. Defaults to title.	None
depends_on	Optional[List[str]]	Identifiers of steps that invalidate this one.	None
require_completion	bool	Block Next until the step sets :attr:~WorkflowStep.completed.	False
completion_message	str	Reason shown while completion is still required.	'Complete this step before continuing'

values property

values

Current values of every :class:Fields parameter, including defaults.

body

body()

Return the elements to display. Override for dynamic content.

on_action

on_action(action)

Handle a button press. Override to react to :class:Button elements.

run_action

run_action(action)

Validate and dispatch one button press or field submission.

UI elements

UIElement

Bases: ABC

Base class for the elements a custom step can display.

to_dict abstractmethod

to_dict()

Return the browser-safe element descriptor.

Text

Text(content)

Bases: UIElement

Markdown paragraph.

Parameters:

Name	Type	Description	Default
content	str	Markdown source. Raw HTML is not rendered.	required

Alert

Alert(content, level='info')

Bases: UIElement

Short highlighted message.

Parameters:

Name	Type	Description	Default
content	str	Plain text shown in the callout.	required
level	str	One of info, success, warning, or danger.	'info'

Metric dataclass

Metric(label, value, unit=None)

One labelled value in a :class:Metrics element.

Metrics

Metrics(items)

Bases: UIElement

Grid of labelled values such as scores, counts, or volumes.

Values are displayed exactly as provided, so round or format them before passing them in.

Parameters:

Name	Type	Description	Default
items	Union[Mapping[str, Any], Sequence[Metric]]	Either a mapping of label to value, or a sequence of :class:Metric instances when units are needed.	required

Table

Table(rows, columns=None, caption=None)

Bases: UIElement

Small tabular result.

Parameters:

Name	Type	Description	Default
rows	Sequence[Union[Mapping[str, CellValue], Sequence[CellValue]]]	Either mappings keyed by column name, or sequences of cells that match columns.	required
columns	Optional[Sequence[str]]	Column headers. Required for sequence rows; derived from the first mapping row otherwise.	None
caption	Optional[str]	Optional description shown below the table.	None

Series dataclass

Series(label, values, x=None)

One named sequence of values in a :class:Chart.

Parameters:

Name	Type	Description	Default
label	str	Name shown in the chart legend.	required
values	Sequence[float]	Value of each point.	required
x	Optional[Sequence[Position]]	Optional position or category name of each point. Positions must be either all numbers or all strings, and default to the point index.	None

Chart

Chart(
    variant,
    series,
    x_label=None,
    y_label=None,
    caption=None,
)

Bases: UIElement

Plot of one or more numeric series, drawn to the width of the panel.

Charts summarize a result; they are not a substitute for the viewer. Use string positions for categories such as label names, and numeric positions for measured quantities such as histogram bins.

Parameters:

Name	Type	Description	Default
variant	str	One of line, bar, or scatter.	required
series	Union[Series, Sequence[Series], Mapping[str, Sequence[float]]]	A single :class:Series, several of them, or a mapping of label to values.	required
x_label	Optional[str]	Optional name of the horizontal axis.	None
y_label	Optional[str]	Optional name of the vertical axis.	None
caption	Optional[str]	Optional description shown below the chart.	None

Image

Image(source, caption=None, alt=None)

Bases: UIElement

Raster image such as a rendered plot or an external screenshot.

The encoded image is part of every workflow state update, so keep it small. Images belong to a step's description of its result; data that has a position in space belongs in the session data model instead, where the viewer can display it.

Parameters:

Name	Type	Description	Default
source	Union[bytes, bytearray, memoryview, str, Path]	PNG, JPEG, or WebP data, or the path of such a file.	required
caption	Optional[str]	Optional description shown below the image.	None
alt	Optional[str]	Alternative text for assistive technologies. Defaults to the caption.	None

Fields

Fields(parameters, *, submit_action=None)

Bases: UIElement

Editable values using the same typed parameters as actions.

Values are validated by the server and are available as step.values, keyed by parameter name.

Parameters:

Name	Type	Description	Default
parameters	Sequence[ParameterDefinition]	Parameter descriptors such as :class:~imfusion_webappkit.parameter_spec.FloatParameter.	required
submit_action	Optional[str]	Action to dispatch, as if a :class:Button with this action had been pressed, when the visitor presses Enter in a single-line field. Lets a composer such as a chat message submit without a separate button.	None

Button

Button(
    action,
    label=None,
    *,
    style="default",
    job=False,
    disabled=False
)

Bases: UIElement

Button that calls the step's on_action hook.

Parameters:

Name	Type	Description	Default
action	str	Identifier passed to on_action.	required
label	Optional[str]	Button text. Defaults to a title-cased action.	None
style	str	One of default, primary, or danger.	'default'
job	bool	Run the handler as a correlated job so it reports progress and can be cancelled. Required for handlers that do more than update step state, because other work stays blocked while they run.	False
disabled	bool	Show the button but reject presses, in the browser and on the server.	False

AnnotationField

AnnotationField(
    annotations,
    *,
    label=None,
    place_action=None,
    clear_action=None,
    prompts=None,
    show_measurements=False
)

Bases: UIElement

Live state of annotations the step is collecting, with its own controls.

For steps that mix annotation placement with other input — measure a distance in a field, then place a box using it — where :class:~imfusion_webappkit.workflow.AnnotationStep does not apply. The step drives app.annotation_model from on_action and this element shows the result.

Parameters:

Name	Type	Description	Default
annotations	Sequence[Any]	The annotations to display, in the order the user places them. Usually step.my_annotations.	required
label	Optional[str]	Optional heading above the list.	None
place_action	Optional[str]	Action dispatched by the Place button; omit for a read-only readout.	None
clear_action	Optional[str]	Action dispatched by the Clear button.	None
prompts	Optional[Sequence[str]]	Optional per-annotation prompt, shown instead of the annotation's own label.	None
show_measurements	bool	Show a line's length and an angle's angle.	False