OpenHCS

OpenHCS

将高内涵显微图像转化为可复现的测量结果
在 GUI、Python、CellProfiler 和本地 Agent 之间共享一套可审查的工作流

OpenHCS 面向成像科学家和研究软件团队，适用于需要一致分析大量孔、位点、通道、Z 平面或时间点的高内涵研究。源选择、处理步骤和结果定义都保存在同一条经过验证的流水线中，而不是分散在仅限界面的状态、脚本和自动化流程里。

如果工作流需要在可视化编辑、代码和自动化之间保持可审查性，OpenHCS 就很适合。可在桌面 GUI 中编辑同一条流水线，也可以用 Python 编辑；还可以从受支持的 CellProfiler .cppipe 文件导入，并通过本地 MCP 接口构建或审查。

安装

Windows 安装程序 · macOS 安装程序 · 安装选项

图形安装程序会设置一个隔离且适用于 CPU 的桌面环境，其中包含 OpenHCS GUI、CellProfiler 兼容支持、本地 MCP 服务、Napari、Fiji/ImageJ 和 Bio-Formats。GPU 库为可选组件。

查看 OpenHCS 的实际使用

浏览 UI 和查看器图库 · 观看 Agent 构建、调试、运行和检查工作流

OpenHCS 采用先编译后执行架构处理大型显微镜数据集。流水线会在处理开始之前，根据选定的执行轴进行验证，避免在耗费大量时间的工作完成后才出现错误。可在 GUI 中设计流水线、导出为 Python、以代码形式编辑，再重新导入——在可视化和编程工作流之间自由切换。本地 MCP 会向受支持的 Agent 提供同一套工作流模型，因此由 Agent 编写的流水线仍可在 GUI 和生成的 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

⚡ 核心功能

🧩 OpenHCS 生态系统

OpenHCS 由 8 个按用途拆分、独立发布的库构建而成——每个库都解决一个通用问题，并共同组成一个平台：

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)"]

🔬 显微镜与函数支持

处理领域：图像预处理 · 分割 · 细胞计数 · 拼接（MIST + Ashlar GPU）· 神经突追踪 · 形态学 · 测量

维度由函数定义，而非全局模式：真正的体积分割和测量路径可以与逐平面函数并存；后者的标签不会在 Z 轴上被静默拼接。请参阅维度和测量能力参考。

🚀 快速开始

对于大多数桌面用户，请下载 Windows 安装程序 或 macOS 安装程序。 这两种下载都无需解压 ZIP，也无需预先安装 Python。 从 OpenHCS 0.7.23 或更早版本升级时，请按照 一次性安装程序迁移说明操作。

如果 macOS 因官方引导程序未签名且未经公证而阻止其运行， 请尝试打开 OpenHCS Installer.app，然后前往 系统设置 > 隐私与安全性，向下滚动到 安全性，点击 仍要打开，进行身份验证，并 确认点击 打开。仅对从 OpenHCS 官方 GitHub 发行版下载的磁盘映像绕过 Gatekeeper。Apple 在此处记录了当前的恢复 步骤。

如需手动安装，请创建虚拟环境，并安装与图形安装程序相同的 CPU 安全型桌面组件：

# Complete CPU-safe desktop environment
python -m pip install "openhcs[gui,viz,bioformats,mcp,cellprofiler-compat]"

# Launch the application
openhcs

# Launch the local MCP server over stdio
openhcs-mcp

较小的环境可以只选择所需功能：

# Basic installation with GUI
python -m pip install "openhcs[gui]"

# Add Napari viewer
python -m pip install "openhcs[gui,napari]"

# Add Fiji/ImageJ viewer
python -m pip install "openhcs[gui,fiji]"

# Add both viewers
python -m pip install "openhcs[gui,viz]"

# Add GPU acceleration on a compatible CUDA 12 system
python -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 clients
python -m pip install "openhcs[gui,mcp,viz]"

# Or lower a CellProfiler pipeline into public OpenHCS declarations
from pathlib import Path

from objectstate import ensure_global_config_context
from openhcs.core.config import GlobalPipelineConfig
from openhcs.core.orchestrator.orchestrator import PipelineOrchestrator
from 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)

GUI 和执行服务使用相同的 list[FunctionStep]、 PipelineConfig 和类型化执行包。有关明确的底层执行调用和进度生命周期，请参阅 API 概览。

运行 CellProfiler/OpenHCS 对比的维护者可以使用打包的 openhcs-benchmark 命令。openhcs-benchmark list-cases --manifest PATH 会检查声明的案例来源，而不获取数据或启动运行；专家级 openhcs_list_benchmark_cases MCP 工具提供相同的选择功能。 每次对比运行都会记录一份类型化回执，其中包含 其生命周期状态、精确的重运行命令、声明的工作内容以及结构化结果 产物。请使用新的或空的输出目录；如果目录非空，系统会在加载清单之前拒绝运行。在专家级 full MCP 接口上， openhcs_inspect_benchmark_run 可以检查本地读取路径策略允许访问的现有结果目录。 openhcs-benchmark inspect-run --output-dir PATH 会读取相同的类型化检查结果； 两种方式都会通过 artifact_limit 和 artifact_offset 对结构化产物分页，而不是返回无界的清单。 openhcs_report_benchmark_run 和 openhcs-benchmark inspect-run --output-dir PATH --report 会根据类型化回执和 观测结果生成有界的案例结果报告。这些 MCP 接口为只读接口：它们不会启动、恢复、取消或重新运行 基准测试；记录的回执用于记录来源信息，并不构成科学上的一致性 声明。 对于单个常规测量流水线，openhcs-benchmark inspect-measured --output-dir PATH 以及专家级 MCP 检查/报告工具会读取相同的 已验证运行回执，并检查保留的来源、观测结果和摘要摘要值。缺少后两种摘要值的 归档回执仍可读取，但无法验证这些文件。这些接口不会创建 第二套流水线运行器或作业状态系统。 openhcs-benchmark run-measured --plate PLATE --pipeline-source-file PIPELINE.py --output-dir EVIDENCE --run-id ID --wait-timeout-ms 120000 会通过常规无头作业控制提交该 流水线，然后调用相同的回执收尾程序。如果输入工作区已单独准备，请使用 --execution-plate PREPARED_PLATE；证据目录必须为空。 使用 --observation-scope outcomes 可保留每个轴的成功状态和来源信息，而不传输运行时数组；此操作不会比较输出值。 常规无头作业完成后，专家级 openhcs_finalize_measured_pipeline_run 工具可以验证其运行时 观测结果，并根据确切提交的流水线和服务端完成记录保留该回执。它不会提交另一个作业。

python -m pip install "openhcs"              # Headless engine
python -m pip install "openhcs[gui]"         # Desktop GUI
python -m pip install "openhcs[gui,napari]"  # GUI + Napari viewer
python -m pip install "openhcs[gui,viz]"     # GUI + Napari + Fiji
python -m pip install "openhcs[gui,viz,gpu]" # Full installation
python -m pip install "openhcs[gpu]"         # Headless + GPU
python -m pip install "openhcs[omero]"       # OMERO integration
python -m pip install -e ".[all,dev]"         # Development (all features)

python scripts/install_omero_deps.py
pip install 'openhcs[omero]'

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

📖 文档

⚙️ 架构亮点

PipelineConfig + list[FunctionStep]
        ↓ resolve once
StepSnapshot + CompilationSession
        ↓ derive and validate
typed CompiledStepPlan objects
        ↓ package
CompiledExecutionBundle
        ↓ execute
runtime values + materialized artifacts

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

🤝 贡献

git clone --recurse-submodules https://github.com/OpenHCSDev/OpenHCS.git
cd 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

贡献方向：显微镜格式 · 处理函数 · GPU 后端 · 文档

📄 许可证

MIT — 参见 LICENSE。

🙏 致谢

OpenHCS 由 EZStitcher 演进而来，并基于 Ashlar（拼接）、MIST（相位相关）、pyclesperanto（GPU 图像处理）和 scikit-image（图像分析）构建。

OpenHCS 与 CellProfiler 的互操作性和一致性验证基于 CellProfiler 项目的开源软件、文档以及公开的示例、教程和基准材料。我们感谢 CellProfiler 的作者和贡献者，以及其分发的生物数据集的作者。请遵循 CellProfiler 的官方引用指南引用 CellProfiler，其中包括 Stirling 等人，《CellProfiler 4：速度、实用性和易用性的改进》（2021）。

第三方项目名称和徽标用于标识 OpenHCS 支持的集成、兼容 客户端或所使用的软件。它们仍归各自项目或所有者所有；其出现不代表 存在关联或认可。