openhcs

<!-- mcp-name: io.github.OpenHCSDev/openhcs -->

<div align="center">

<img src="openhcs/resources/assets/openhcs-icon-square.svg" width="132" alt="OpenHCS array-processing logo">

<h1>OpenHCS</h1>

**Turn high-content microscopy images into reproducible measurements**\
**One reviewable workflow across the GUI, Python, CellProfiler, and local agents**

[![PyPI version](https://img.shields.io/pypi/v/openhcs.svg)](https://pypi.org/project/openhcs/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11-3.13](https://img.shields.io/badge/python-3.11--3.13-blue.svg)](https://www.python.org/downloads/)
[![GPU Accelerated](https://img.shields.io/badge/GPU-Accelerated-green.svg)](https://github.com/OpenHCSDev/OpenHCS)
[![Documentation](https://readthedocs.org/projects/openhcs/badge/?version=latest)](https://openhcs.readthedocs.io)

</div>

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**](https://github.com/OpenHCSDev/OpenHCS/releases/latest/download/OpenHCS-Windows-Installer.exe) ·
[**macOS installer**](https://github.com/OpenHCSDev/OpenHCS/releases/latest/download/OpenHCS-macOS-Installer.dmg) ·
[**Installation options**](https://openhcsdev.github.io/openhcs/#install)

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](website/assets/gallery/multi-plate-overview.webp)](https://openhcsdev.github.io/openhcs/#gallery)

[Browse the UI and viewer gallery](https://openhcsdev.github.io/openhcs/#gallery) ·
[Watch an agent build, debug, run, and inspect a workflow](https://openhcsdev.github.io/openhcs/#mcp)

---

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.

```mermaid
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

<table>
<tr>
<td width="50%" valign="top">

### 🛡️ Compile-Time Validation
Configuration is resolved once into step snapshots and a compilation session. Typed plans then validate sources, artifacts, materialization, memory contracts, and worker requirements before execution begins. Errors surface immediately, not after hours of processing.

</td>
<td width="50%" valign="top">

### 🔄 Bidirectional GUI ↔ Code
Design pipelines visually, export as executable Python, edit in your IDE, re-import to the GUI. Code generation works at **any scope level** — function patterns, individual steps, pipeline configs, full orchestrator scripts — any window holding objects can generate and re-import code.

</td>
</tr>
<tr>
<td width="50%" valign="top">

### 🧠 Agent-Assisted Workflows
Give a supported MCP client a microscopy folder or plate and an analysis goal. It can inspect the connected execution server's functions, build and validate a typed pipeline, run it, inspect results in OpenHCS or a viewer, and revise the generated Python.

</td>
<td width="50%" valign="top">

### ⚡ Multiprocessing & GPU Acceleration
Bounded worker lanes use `ProcessPoolExecutor` by default, with deterministic
well assignment and sequential processing inside each lane. Compiled callable
contracts select framework-local GPU devices independently; single-worker and
debugging configurations can use inline or threaded execution.

</td>
</tr>
<tr>
<td width="50%" valign="top">

### 🔌 Any Python Function
Register **any** Python function by decorating it with `@numpy`, `@cupy`, `@pyclesperanto`, `@torch`, or another memory-type decorator. Custom functions receive contract validation, UI integration, multiprocessing-safe import identity, and the same server-owned catalog projection as built-in functions. Persisted functions live in the platform-specific OpenHCS user-data directory.

</td>
<td width="50%" valign="top">

### 📊 Results Materialization
Callable and module artifact contracts declare semantic outputs independently of Python argument names. The artifact graph and materialization plans route images, measurements, object labels, relationships, tables, and files to their configured stores and exporters.

</td>
</tr>
<tr>
<td width="50%" valign="top">

### 🔬 Process-Isolated Napari & Fiji
Stream images to **Napari** and **Fiji/ImageJ** in real time during pipeline execution. OpenHCS `StreamingConfig` declarations and viewer adapters own identity, display, and persistence policy. PolyStore builds generic storage and streaming payloads; ZMQRuntime supplies process-isolated transport, readiness, acknowledgments, and lifecycle.

</td>
<td width="50%" valign="top">

### 🪟 Live Cross-Window Updates
Edit a value in `GlobalPipelineConfig` — watch it propagate in real-time to `PipelineConfig` and `StepConfig` windows. Dual-axis resolution (context hierarchy × class MRO) with scope isolation per orchestrator.

</td>
</tr>
<tr>
<td width="50%" valign="top">

### 🧬 CellProfiler Pipeline Import
Open `.cppipe` files in the desktop application or lower them from Python into ordinary `PipelineConfig` and `FunctionStep` declarations. Named images, objects, measurements, relationships, and exports use the same typed compiler and runtime as native OpenHCS pipelines. The source-backed Official30 suite continuously exercises 30 pipelines from CellProfiler examples, tutorials, and benchmark supplements under explicit equivalence policies.

</td>
<td width="50%" valign="top">

### 🤖 MCP Agent Automation
Use the local stdio MCP server with ChatGPT desktop, Codex, Claude Desktop, and other supported clients, or deploy the separately secured HTTP surface. The graphical installers register detected local clients automatically. Capability profiles, schemas, knowledge, UI attachment, authoring, execution, runtime inspection, viewer review, and governed custom-function registration are projected from typed authorities rather than duplicated tool lists.

</td>
</tr>
</table>

---

## 🧩 The OpenHCS Ecosystem

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

```mermaid
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/>(forms)"]

    OS --> PI["python-introspect<br/>(signatures)"]
    OH --> MR["metaclass-registry<br/>(plugins)"]
    OH --> PC["pycodify<br/>(serialization)"]
```

| Library | Role in OpenHCS | What It Does |
|:--------|:----------------|:-------------|
| [**ObjectState**](https://github.com/OpenHCSDev/ObjectState) | Configuration framework | Lazy dataclasses with dual-axis inheritance (context hierarchy × class MRO) and `contextvars`-based resolution |
| [**ArrayBridge**](https://github.com/OpenHCSDev/ArrayBridge) | Memory type conversion | Unified API across NumPy, CuPy, PyTorch, JAX, TensorFlow, pyclesperanto with DLPack zero-copy transfers |
| [**PolyStore**](https://github.com/OpenHCSDev/PolyStore) | Unified I/O & stream payloads | Generic storage and streaming payload primitives, backend lifecycle, virtual workspaces, atomic writes, format detection, and ROI extraction |
| [**ZMQRuntime**](https://github.com/OpenHCSDev/ZMQRuntime) | Process & transport runtime | Generic request, status, progress, cancellation, process-lifecycle, and viewer-control transport protocols |
| [**PyQT-reactive**](https://github.com/OpenHCSDev/PyQT-reactive) | UI form generation | React-style reactive forms from dataclasses with cross-window sync and flash animations |
| [**pycodify**](https://github.com/OpenHCSDev/pycodify) | Code ↔ object conversion | Python source as serialization format — type-preserving, diffable, editable, with collision handling |
| [**python-introspect**](https://github.com/OpenHCSDev/python-introspect) | Signature analysis | Pure-Python function/dataclass introspection for automatic UI generation and contract analysis |
| [**metaclass-registry**](https://github.com/OpenHCSDev/metaclass-registry) | Plugin discovery | Zero-boilerplate regist