bioimageflow_core

The worker-safe core package. Installed in all environments (main process and workers). It declares NumPy for shared-memory array helpers and avoids orchestrator-only dependencies such as pandas and pydantic.

Types

BioImageFlow worker-safe type system.

class bioimageflow_core.types.Semantic

Bases: str, Enum

What the pixel values represent.

BINARY = 'binary'

LABEL = 'label'

INTENSITY = 'intensity'

PROBABILITY = 'probability'

DISPLACEMENT = 'displacement'

FEATURE = 'feature'

__new__(value)

bioimageflow_core.types.SCALAR_IMAGE_SEMANTICS = frozenset({Semantic.BINARY, Semantic.INTENSITY, Semantic.LABEL, Semantic.PROBABILITY})

Semantic values for scalar raster images.

Use this group for tools that consume displayable scalar images without requiring a specific pixel meaning, such as visualization and montage tools. It intentionally excludes vector fields and feature images.

class bioimageflow_core.types.Layout

Bases: str, Enum

Axis ordering of the image data.

PLANAR = 'YX'

PLANAR_CHANNEL = 'CYX'

PLANAR_TIME = 'TYX'

PLANAR_TIME_CHANNEL = 'TCYX'

VOLUMETRIC = 'ZYX'

VOLUMETRIC_CHANNEL = 'CZYX'

VOLUMETRIC_TIME = 'TZYX'

VOLUMETRIC_TIME_CHANNEL = 'TCZYX'

property ndim: int

__new__(value)

class bioimageflow_core.types.ImageSpec

Bases: object

Defines type constraints. Empty sets mean ‘any’ (wildcard).

semantics: Set[Semantic]

layouts: Set[Layout]

dtypes: Set[str]

formats: Set[str]

__init__(semantics=<factory>, layouts=<factory>, dtypes=<factory>, formats=<factory>)

Parameters:

• semantics (Set[Semantic])

• layouts (Set[Layout])

• dtypes (Set[str])

• formats (Set[str])

Return type:

None

class bioimageflow_core.types.SharedArray

Bases: object

A reference to data in shared memory. Picklable.

name: str

shape: Tuple[int, ...]

dtype: str

__init__(name, shape, dtype)

Parameters:

• name (str)

• shape (Tuple[int, ...])

• dtype (str)

Return type:

None

bioimageflow_core.types.ImageShared(semantics=None, layouts=None, dtypes=None, gui=None)

Returns Annotated[SharedArray, ImageSpec(…), optional GUIMeta].

Return type:

Any

Parameters:

• semantics (Any | None)

• layouts (Any | None)

• dtypes (Any | None)

• gui (Any | None)

class bioimageflow_core.types.Connectable

Bases: Enum

Whether a tool input field can be bound to an upstream dataframe column.

• NEVER: No input pin, no toggle — the field can never be wired.

• NOT_BY_DEFAULT: Pin hidden by default; a GUI checkbox reveals it.

• BY_DEFAULT: Pin visible by default; a GUI checkbox can hide it.

NEVER = 'never'

NOT_BY_DEFAULT = 'not_by_default'

BY_DEFAULT = 'by_default'

class bioimageflow_core.types.PathPicker

Bases: Enum

Which filesystem values a GUI path picker should offer.

FILE = 'file'

FOLDER = 'folder'

BOTH = 'both'

class bioimageflow_core.types.GUIMeta

Bases: object

Declarative GUI hints for a tool Inputs / Outputs field.

Attach to an Inputs or Outputs annotation via Annotated to control how a GUI renders the field (label, tooltip, widget range, pin visibility, tab grouping, …).

Parameters:

• display_name (str | None) – Human-readable label shown next to the field in the GUI. If None, frontends should fall back to the field name (optionally prettified).

• description (str | None) – Longer help text (tooltip / inline help) explaining what the field means and how it is used.

• connectable (Connectable) – Controls whether and how an Inputs field can be bound to an upstream column. Ignored for Outputs fields. Defaults to Connectable.NOT_BY_DEFAULT.

• min (float | None) – Minimum allowed value (numeric fields only).

• max (float | None) – Maximum allowed value (numeric fields only).

• step (float | None) – Step increment for spinbox / slider widgets (numeric fields only).

• group (str | None) – Logical group name for organising fields into tabs or sections (e.g. "general", "advanced", "gpu"). None means the field belongs to the default / unnamed group.

• path_picker (PathPicker | None) – Picker actions offered for path-typed inputs. None lets the GUI infer a backward-compatible default from the field type. This is a rendering hint only and does not validate the filesystem value.

display_name: Optional[str] = None

description: Optional[str] = None

connectable: Connectable = 'not_by_default'

min: Optional[float] = None

max: Optional[float] = None

step: Optional[float] = None

group: Optional[str] = None

path_picker: Optional[PathPicker] = None

__init__(display_name=None, description=None, connectable=Connectable.NOT_BY_DEFAULT, min=None, max=None, step=None, group=None, path_picker=None)

Parameters:

• display_name (str | None)

• description (str | None)

• connectable (Connectable)

• min (float | None)

• max (float | None)

• step (float | None)

• group (str | None)

• path_picker (PathPicker | None)

Return type:

None

bioimageflow_core.types.extract_gui_meta(annotation)

Extract GUIMeta from an Annotated type, or return None.

Return type:

Optional[GUIMeta]

Parameters:

annotation (Any)

bioimageflow_core.types.check_compatibility(producer_spec, consumer_spec)

Returns True if the producer’s output is acceptable for the consumer’s input.

Return type:

bool

Parameters:

• producer_spec (ImageSpec)

• consumer_spec (ImageSpec)

Environment

Environment and resource specifications.

class bioimageflow_core.environment.EnvironmentSpec

Bases: object

Defines a reusable Wetlands environment specification.

name: str

dependencies: dict[str, Any]

allow_flexible_versions: bool = False

__init__(name, dependencies, allow_flexible_versions=False)

Parameters:

• name (str)

• dependencies (dict[str, Any])

• allow_flexible_versions (bool)

Return type:

None

class bioimageflow_core.environment.ResourceSpec

Bases: object

Resource requirements for a processing tool.

cpu: int = 1

gpu: int = 0

gpu_memory: Optional[str] = None

max_concurrent: int = 0

memory: Optional[str] = None

__init__(cpu=1, gpu=0, gpu_memory=None, max_concurrent=0, memory=None)

Parameters:

• cpu (int)

• gpu (int)

• gpu_memory (str | None)

• max_concurrent (int)

• memory (str | None)

Return type:

None

exception bioimageflow_core.environment.EnvironmentMismatchError

Bases: Exception

Raised when two EnvironmentSpecs share a name but differ in dependencies.

Tool Base Classes

Worker-safe tool base classes.

class bioimageflow_core.tool.Category

Bases: str, Enum

High-level functional category for a tool.

CONVERSION = 'conversion'

IMAGE_PROCESSING = 'image_processing'

SEGMENTATION = 'segmentation'

REGISTRATION = 'registration'

SPECTRAL_ANALYSIS = 'spectral_analysis'

TRACKING = 'tracking'

MEASUREMENT = 'measurement'

SPOT_DETECTION = 'spot_detection'

DECONVOLUTION = 'deconvolution'

RESTORATION = 'restoration'

COLOCALIZATION = 'colocalization'

STITCHING = 'stitching'

CLASSIFICATION = 'classification'

UTILITIES = 'utilities'

__new__(value)

class bioimageflow_core.tool.Template

Bases: object

Explicit marker for ProcessingTool output path templates.

pattern: str

__init__()

class bioimageflow_core.tool.IOModel

Bases: object

Lightweight declarative base for tool Inputs/Outputs.

__init__(**kwargs)

Parameters:

kwargs (Any)

Return type:

None

class bioimageflow_core.tool.BaseTool

Bases: object

Common base for all tools. Provides identity and Inputs. __call__ is NOT defined here — each subclass defines its own.

display_name: ClassVar[str] = ''

documentation: ClassVar[str] = ''

category: ClassVar[Optional[Category]] = None

tags: ClassVar[list[str]] = []

Inputs

alias of IOModel

Outputs: ClassVar[Optional[type[IOModel]]] = None

__init__()

Return type:

None

class bioimageflow_core.tool.ProcessingTool

Bases: BaseTool

Tool that processes data in an isolated Wetlands environment.

environment: ClassVar[Any]

resources: ClassVar[Any] = None

run_empty_batch: ClassVar[bool] = False

empty_batch_anchor_inputs: ClassVar[tuple[str, ...]] = ()

zero_row_scalar_outputs: ClassVar[dict[str, Any]] = {}

process_row(arguments, *, context=None)

Process a single row. Override in subclasses.

Return type:

Any

Parameters:

• arguments (Any)

• context (Any | None)

process_batch(arguments_list, *, context=None)

Process all rows at once. Override for batch processing.

Return type:

Any

Parameters:

• arguments_list (list[Any])

• context (Any | None)

Arguments

Arguments namespace, execution context, and index lineage helpers.

class bioimageflow_core.arguments.ExecutionContext

Bases: object

Per-execution filesystem context for ProcessingTool runtime scratch.

run_dir: Path

assets_dir: Path

work_dir: Path

rows_dir: Path

row_dir: Optional[Path] = None

batch_dir: Optional[Path] = None

row_index: Optional[str] = None

to_dict()

Return a picklable representation for worker dispatch.

Return type:

dict[str, Optional[str]]

classmethod from_dict(data)

Reconstruct an execution context from a worker payload.

Return type:

ExecutionContext

Parameters:

data (dict[str, Any])

__init__(run_dir, assets_dir, work_dir, rows_dir, row_dir=None, batch_dir=None, row_index=None)

Parameters:

• run_dir (Path)

• assets_dir (Path)

• work_dir (Path)

• rows_dir (Path)

• row_dir (Path | None)

• batch_dir (Path | None)

• row_index (str | None)

Return type:

None

class bioimageflow_core.arguments.Arguments

Bases: object

Lightweight namespace for passing resolved values to tool methods. Supports attribute access with helpful error messages on typos.

__init__(**kwargs)

Parameters:

kwargs (Any)

Return type:

None

bioimageflow_core.arguments.parse_index_lineage(index)

Split an exploded index into its lineage components.

Return type:

list[str]

Parameters:

index (str)

bioimageflow_core.arguments.parent_index(index)

Return the parent index (strip last explosion level).

Return type:

str

Parameters:

index (str)

I/O

I/O dispatch helpers with pluggable file readers and NumPy shared-memory views.

bioimageflow_core.io.load_image(source, *, file_reader)

Dispatch between file and shared memory sources. - SharedArray: attaches to shared memory, yields numpy view. - Path or str: delegates to file_reader, yields result.

Return type:

Generator[Any, None, None]

Parameters:

• source (Any)

• file_reader (Callable[[Path], Any])

bioimageflow_core.io.save_image(destination, data, *, file_writer)

Save image data to disk using the provided writer.

Return type:

None

Parameters:

• destination (str | Path)

• data (Any)

• file_writer (Callable[[Path, Any], None])

Shared Memory

Shared memory helpers that expose NumPy array views.

bioimageflow_core.shm.create_shared_output(data, name=None)

Create a shared memory segment, copy data into it, and yield a SharedArray. Closes the local handle on exit but does NOT unlink (data persists).

Return type:

Generator[SharedArray, None, None]

Parameters:

• data (Any)

• name (str | None)

bioimageflow_core.shm.open_shared_array(ref)

Attach to an existing shared memory segment. Yields a zero-copy numpy array. Closes handle on exit.

Return type:

Generator[Any, None, None]

Parameters:

ref (SharedArray)