OpenHCS

OpenHCS is designed for imaging scientists and research software teams running high-content studies where many wells, sites, channels, Z planes, or time points must be analysed consistently. Source selection, processing steps, and result definitions stay together in one validated pipeline instead of being split across interface-only state, scripts, and automation.

It is a good fit when a workflow must remain reviewable across visual editing, code, and automation. The same pipeline can be edited in the desktop GUI or as Python, imported from supported CellProfiler .cppipe files, and built or reviewed through the local MCP surface.

Install

Windows installer · macOS installer · Installation options

The graphical installers set up an isolated CPU-safe desktop environment with the OpenHCS GUI, CellProfiler compatibility, local MCP server, Napari, Fiji/ImageJ, and Bio-Formats. GPU libraries remain optional.

See OpenHCS in use

[OpenHCS desktop application with several assay plates]

Browse the UI and viewer gallery · Watch an agent build, debug, run, and inspect a workflow

OpenHCS processes large microscopy datasets with a compile-then-execute architecture. Pipelines are validated across the selected execution axes before processing starts, preventing late failures after expensive work. Design pipelines in the GUI, export to Python, edit as code, and re-import — switching between visual and programmatic workflows. The local MCP exposes that same workflow model to supported agents, so agent-authored pipelines remain visible, editable, and reviewable in the GUI and generated Python.

graph LR    subgraph Sources        IX[ImageXpress]        OP[Opera Phenix]        BF[Bio-Formats]        OM[OMERO]    end
    subgraph OpenHCS Platform        PD["Pipeline Designer<br/>(GUI ⇄ Code ⇄ Agent)"]        CO["Typed Compiler<br/>(resolve + validate)"]        EX["Bounded Worker Executor<br/>(well scheduling · multi-GPU)"]        FN["Registry-Discovered Functions<br/>scikit-image · CuPy · pyclesperanto<br/>PyTorch · JAX · TF · CuCIM · custom"]        PS["PolyStore<br/>(Memory ↔ Disk ↔ Zarr ↔ Stream)"]    end
    subgraph Viewers        NA[Napari]        FJ[Fiji/ImageJ]    end
    IX --> PD    OP --> PD    BF --> PD    OM --> PD    PD --> CO --> EX    EX --> FN --> PS    PS --> NA    PS --> FJ

⚡ Key Capabilities

🧩 The OpenHCS Ecosystem

OpenHCS is built on 8 purpose-extracted, separately published libraries — each solving a general problem and all composed into one platform:

graph TD    OH["OpenHCS Platform<br/>(domain wiring + pipelines)"]
    OH --> OS["ObjectState<br/>(config)"]    OH --> AB["ArrayBridge<br/>(arrays)"]    OH --> PS["PolyStore<br/>(I/O + streaming)"]    OH --> ZR["ZMQRuntime<br/>(exec)"]    OH --> QR["PyQT-reactive<br/>(Qt forms)"]    OH --> FB["formbridge<br/>(form model + UI bridge)"]    QR --> FB
    OS --> PI["python-introspect<br/>(signatures)"]    OH --> MR["metaclass-registry<br/>(plugins)"]    OH --> PC["pycodify<br/>(serialization)"]

🔬 Microscope & Function Support

Processing domains: image preprocessing · segmentation · cell counting · stitching (MIST + Ashlar GPU) · neurite tracing · morphology · measurements

Dimensionality is function-defined rather than a global mode: true volumetric segmentation and measurement routes coexist with plane-local functions, whose labels are not silently stitched across Z. See the dimensionality and measurement capability reference.

🚀 Quick Start

For most desktop users, download the Windows installer or macOS installer. Neither download requires ZIP extraction or an existing Python installation. When upgrading OpenHCS 0.7.23 or earlier, follow the one-time installer migration.

If macOS blocks the official bootstrap because it is unsigned and not notarised, try to open OpenHCS Installer.app, then go to System Settings > Privacy & Security, scroll to Security, click Open Anyway, authenticate, and confirm Open. Only override Gatekeeper for the disk image downloaded from the official OpenHCS GitHub release. Apple documents the current recovery steps here.

For a manual installation, create a virtual environment and install the same CPU-safe desktop surface as the graphical installers:

# Complete CPU-safe desktop environmentpython -m pip install "openhcs[gui,viz,bioformats,mcp,cellprofiler-compat]"
# Launch the applicationopenhcs
# Launch the local MCP server over stdioopenhcs-mcp

Smaller environments can select only the required features:

# Basic installation with GUIpython -m pip install "openhcs[gui]"
# Add Napari viewerpython -m pip install "openhcs[gui,napari]"
# Add Fiji/ImageJ viewerpython -m pip install "openhcs[gui,fiji]"
# Add both viewerspython -m pip install "openhcs[gui,viz]"
# Add GPU acceleration on a compatible CUDA 12 systempython -m pip install "openhcs[gui,gpu]"
# Full installation (GUI + viewers + GPU)python -m pip install "openhcs[gui,viz,gpu]"
# Add the local MCP server for agent clientspython -m pip install "openhcs[gui,mcp,viz]"

# Or lower a CellProfiler pipeline into public OpenHCS declarationsfrom pathlib import Path
from objectstate import ensure_global_config_contextfrom openhcs.core.config import GlobalPipelineConfigfrom openhcs.core.orchestrator.orchestrator import PipelineOrchestratorfrom openhcs.interop.cellprofiler.pipeline_import import import_cellprofiler_pipeline
plate_path = Path("/data/plate").resolve()ensure_global_config_context(GlobalPipelineConfig, GlobalPipelineConfig())steps, pipeline_config = import_cellprofiler_pipeline(    "analysis.cppipe",    source_root=plate_path,)
orchestrator = PipelineOrchestrator(    plate_path,    pipeline_config=pipeline_config,).initialize()execution_bundle = orchestrator.compile_pipelines(steps)

The GUI and execution services consume the same list[FunctionStep], PipelineConfig, and typed execution bundle. See the API orientation for the explicit low-level execution call and progress lifecycle.

Maintainers running CellProfiler/OpenHCS comparisons can use the packaged openhcs-benchmark command. openhcs-benchmark list-cases --manifest PATH checks declared case sources without acquiring data or starting a run; the expert openhcs_list_benchmark_cases MCP tool exposes the same selection. Each comparison run records a typed receipt with its lifecycle state, exact rerun command, declared work, and structured result artifacts. Use a new or empty output directory; an occupied one is rejected before the run loads its manifest. On the expert full MCP surface, openhcs_inspect_benchmark_run can inspect an existing result directory allowed by the local read-path policy. openhcs-benchmark inspect-run --output-dir PATH reads the same typed inspection; both routes page structured artifacts through artifact_limit and artifact_offset instead of returning an unbounded inventory. openhcs_report_benchmark_run and openhcs-benchmark inspect-run --output-dir PATH --report render bounded case outcomes from the typed receipt and observations. These MCP routes are read-only: they do not launch, resume, cancel, or rerun a benchmark, and a recorded receipt is provenance rather than a scientific parity claim. For a single ordinary measured pipeline, openhcs-benchmark inspect-measured --output-dir PATH and the expert MCP inspection/report tools read the same validated-run receipt and check retained source, observation, and summary digests. Archived receipts without the latter two digests remain readable but cannot verify those files. These routes do not create a second pipeline runner or job-status system. openhcs-benchmark run-measured --plate PLATE --pipeline-source-file PIPELINE.py --output-dir EVIDENCE --run-id ID --wait-timeout-ms 120000 submits that pipeline through ordinary headless job control, then calls the same receipt finalizer as MCP. Use --execution-plate PREPARED_PLATE when the input workspace has been prepared separately; the evidence directory must be empty. Use --observation-scope outcomes to retain per-axis success and provenance without transferring runtime arrays; this does not compare output values. After an ordinary headless job completes, the expert openhcs_finalize_measured_pipeline_run tool can validate its runtime observation and retain that receipt from the exact submitted pipeline and server completion record. It does not submit another job.

python -m pip install "openhcs"              # Headless enginepython -m pip install "openhcs[gui]"         # Desktop GUIpython -m pip install "openhcs[gui,napari]"  # GUI + Napari viewerpython -m pip install "openhcs[gui,viz]"     # GUI + Napari + Fijipython -m pip install "openhcs[gui,viz,gpu]" # Full installationpython -m pip install "openhcs[gpu]"         # Headless + GPUpython -m pip install "openhcs[omero]"       # OMERO integrationpython -m pip install -e ".[all,dev]"         # Development (all features)

python scripts/install_omero_deps.pypip install 'openhcs[omero]'

pip install -r requirements-omero.txtpip install 'openhcs[omero]'

📖 Documentation

⚙️ Architecture Highlights

PipelineConfig + list[FunctionStep]        ↓ resolve onceStepSnapshot + CompilationSession        ↓ derive and validatetyped CompiledStepPlan objects        ↓ packageCompiledExecutionBundle        ↓ executeruntime values + materialized artifacts

Function patterns · Individual steps · Pipeline configs · Full orchestrator scripts              ↕  generate / AST-parse back  ↕

🤝 Contributing

git clone --recurse-submodules https://github.com/OpenHCSDev/OpenHCS.gitcd OpenHCS# Install the eight local packages using docs/source/development/repository_setup.rst,# then install OpenHCS itself:python -m pip install -e ".[dev,gui]"OPENHCS_CPU_ONLY=1 python -m pytest tests/unit

Contribution areas: microscope formats · processing functions · GPU backends · documentation

📄 License

MIT — see LICENSE.

🙏 Acknowledgments

OpenHCS evolved from EZStitcher and builds on Ashlar (stitching), MIST (phase correlation), pyclesperanto (GPU image processing), and scikit-image (image analysis).

OpenHCS's CellProfiler interoperability and parity validation build on the CellProfiler project's open-source software, documentation, and public example, tutorial, and benchmark materials. We thank the CellProfiler authors and contributors and the authors of the biological datasets they distribute. Please cite CellProfiler following its official citation guidance, including Stirling et al., CellProfiler 4: improvements in speed, utility and usability (2021).

Third-party project names and logos identify supported integrations, compatible clients, or software used by OpenHCS. They remain the property of their respective projects or owners; their appearance does not imply affiliation or endorsement.