MONAI Bundle Inference Operator #

Authors: Holoscan SDK Team (NVIDIA)
Supported platforms: x86_64, aarch64
Language: Python
Last modified: August 5, 2025
Latest version: 1.1.0
Minimum Holoscan SDK version: 1.0.3
Tested Holoscan SDK versions: 2.2.0, 3.2.0
Contribution metric: Level 2 - Trusted

This operator performs inference using MONAI Bundles for medical imaging tasks.

Overview#

The MonaiBundleInferenceOperator loads a MONAI Bundle model and applies it to input medical images for inference, supporting flexible deployment in Holoscan pipelines.

Requirements#

Holoscan SDK Python package
MONAI
torch

Tests#

The disk I/O regression suite runs in the consuming imaging_ai_segmentator application's CTest suite. Run the focused test from the repository root without sample dataset downloads:

./holohub test imaging_ai_segmentator --language python \
  --cmake-options="-DHOLOHUB_DOWNLOAD_DATASETS=OFF" \
  --ctest-options="-DCTEST_TEST_INCLUDE=^imaging_ai_segmentator_disk_io_test$"

With the operator's runtime dependencies and pytest installed, it can also run directly from the repository root:

python -m pytest -v applications/imaging_ai_segmentator/test_monai_bundle_disk_io.py

The suite exercises the real MONAI compute path with CPU tensors. The CUDA output case also runs when a CUDA-enabled PyTorch installation and GPU are available.

Path-based I/O#

Input Path values must refer to pickle-free NPY arrays with dtypes supported by torch.from_numpy. A .npy extension is optional. Pickle files, object arrays, and NPZ archives are rejected. Pass Image, dictionaries, and other Python objects through in-memory ports.

Holoscan graphs use in-memory output ports; save emitted arrays with a downstream writer. The legacy path-based output helper writes NPY only when its output context provides a directory through get(name), preserving the configured file name. It does not add support for IOType.DISK output-port registration.

Existing numeric pickle files must be converted to NPY in a trusted environment before use. Only convert files whose source and contents you trust; this operator does not unpickle legacy data.

Example Usage#

from pathlib import Path
from holoscan.core import Fragment
from operators.medical_imaging.monai_bundle_inference_operator import MonaiBundleInferenceOperator
from operators.medical_imaging.core import AppContext, IOMapping, IOType, Image

fragment = Fragment()
app_context = AppContext({})  # Initialize with empty args dict

bundle_op = MonaiBundleInferenceOperator(
    fragment,
    name="monai_bundle",  # Optional operator name
    app_context=app_context,
    input_mapping=[
        IOMapping(
            label="image",
            data_type=Image,
            storage_type=IOType.IN_MEMORY
        )
    ],
    output_mapping=[
        IOMapping(
            label="pred",
            data_type=Image,
            storage_type=IOType.IN_MEMORY
        )
    ],
    model_name="model",  # Name of the model in the bundle
    bundle_path=Path("model/model.ts")  # Path to the MONAI bundle
)

API Reference#

Python#

`MonaiBundleInferenceOperator`#

Inherits from: InferenceOperator

This inference operator automates the inference operation for a given MONAI Bundle.

Attributes#

Name	Type	Default
`known_io_data_types`	`ClassVar`	`{'image': Image, 'series': np.ndarray, 'tuples': np.ndarray, 'probabilities': dict[str, Any]}`

Methods#

Method	Description
`__init__(fragment)`	Create an instance of this class, associated with an Application/Fragment.
`model_name()`
`model_name(name)`
`bundle_path()`	The path of the MONAI Bundle model.
`bundle_path(bundle_path)`
`parser()`	The ConfigParser object.
`parser(parser)`
`setup(spec)`
`compute(op_input, op_output, context)`	Infers with the input(s) and saves the prediction result(s) to output
`predict(data)`	Predicts output using the inferer.
`pre_process(data)`	Processes the input dictionary with the stored transform sequence `self._preproc`.
`post_process(data)`	Processes the output list/dictionary with the stored transform sequence `self._postproc`.

MONAI Bundle Inference Operator#