Repository avatar
Monitoring
v0.4.0
active

openreadout

io.github.openreadout/openreadout

Read raw lab-instrument files offline: metadata, previews, integrity checks, open-format export.

Documentation

OpenReadout

OpenReadout lets AI agents read and analyze raw files from lab instruments like microscopes, mass specs, flow cytometers, plate readers and NMR. It reads 120+ formats without vendor software, and runs as an MCP server, a CLI, or a Python or R package.

CI Docs License: MIT OR Apache-2.0

🧪 Try it: browser demo  |  📖 Docs: openreadout.github.io/openreadout

Gallery

Light Microscopy

Confocal image of a fruit fly egg chamber in three colours, from a Leica LIF fileDeconvolved max projection of HeLa cells with tubulin, nuclei and Cajal bodies, from a DeltaVision fileSpinning-disk image of a Convallaria root cross-section, from an Imaris file
Leica LIF · fly egg chamberDeltaVision · HeLa cellsImaris · plant root section
Max projection of one neuron and its dendrites, from an Imaris fileCell Painting field with three stains from a Yokogawa CV8000 plateConfocal image of testes from an Evident OIR file
Imaris · a single neuronYokogawa CellVoyager · Cell PaintingEvident OIR · testes, confocal

Electron Microscopy

Projection of a virus capsid density map from an MRC fileAtomic columns of HfZrO2 imaged by electron ptychography, from a Gatan DM3 fileZnO nanorods on graphene oxide, from a Gatan DM4 file
EMDB MRC · virus capsidGatan DM3 · atoms by ptychographyGatan DM4 · ZnO nanorods
Single-crystal electron diffraction spots with the beam stop, from a Gatan DM4 fileNanoparticles on a support film, a STEM HAADF image from a Velox EMD fileChains of silica particles in TEM, from an FEI SER file
Gatan DM4 · electron diffractionVelox EMD · STEM HAADFFEI SER · silica particles

Figures

Sanger sequencing trace with base calls and quality barsRaman spectra of graphene with one to three layers, stackedIsothermal titration calorimetry thermogram with 39 injections
ABI .ab1 · Sanger readWITec · Raman of grapheneMicroCal ITC · titration
CD4 and CD8 T-cell populations gated from a FlowJo workspace96 growth curves drawn in plate positionsProton NMR spectrum of sucrose processed from the raw FID
BD FCS + FlowJo · gated T cellsSoftMax .pda · 96 growth curvesBruker TopSpin · NMR from the FID
EPR spectra of BDPA at 14 microwave powersFragment analysis peaks sized against the LIZ ladderTotal ion current with the mass spectrum at its apex
Bruker EPR · power seriesABI .fsa · fragment sizingmzML · TIC and spectrum
Firing rate against injected current, with example sweepsCyclic voltammogram, cycles 1 and 4qPCR amplification curves on a log axis
Axon ABF · firing against currentGamry · cyclic voltammogramApplied Biosystems .eds · qPCR

All read from the raw files. More in the gallery, and image credits in CREDITS.md.

Get Started

Install it, then connect it to your agent:

brew install openreadout/tap/openreadout    # other ways under Installation below
openreadout mcp --install claude-desktop    # or claude, codex, cursor, vscode, gemini

Then ask your agent about a file, like "What's in cells.czi?" In Claude Code you can install it as a plugin instead (see AI Integration).

Or try the browser demo with no install. Your files never leave your computer.

With an Agent

Claude finds the cerebellum in a 3.7 GB slide scan and labels its layers.

https://github.com/user-attachments/assets/7ee0f9fe-e6e0-4378-a46d-5cdc04d57151

Data: Zenodo 10577621 (CC BY 4.0).

Claude checks a gene knockout with files from five instruments.

https://github.com/user-attachments/assets/658d300b-dc9d-4164-af84-bb48261fd33f

Data: Edyanto et al., figshare (CC BY 4.0).

What It Does

  • Inspect images, channels, traces, spectra, tables, and metadata, in plain text or structured JSON
  • Check files for truncation, missing planes, and damaged structure, with exit code 4 when a file is corrupt
  • Export to OME-TIFF, OME-Zarr, mzML, NWB, CSV, Parquet, Arrow, JCAMP-DX, Allotrope ASM, and RDML, reading every export back to verify it
  • Preview image planes, traces, spectra, and plate heat maps as PNG
  • Analyze chromatographic peaks, plate assays (IC50, standard curves), qPCR (Cq, ΔΔCq), NMR peaks, patch-clamp features, spikes, and flow-cytometry gates, with documented methods
  • Batch over whole directories, index lab shares, and watch running acquisitions

On the Command Line

# Install (macOS / Linux; other ways under Installation)
curl -fsSL https://raw.githubusercontent.com/openreadout/openreadout/main/scripts/install.sh | sh

# What is in the file?
openreadout info cells.lif
# → format: Leica LIF (lif) v2  size: 16.0 MiB  images: 1  planes: 2
# →   [0] PEI_laminin_35k  2048x2048 z=1 c=2 t=1  uint16  px=0.3250 µm
# →       objective: HC PL FLUOTAR L 20x/0.40 DRY

# Is it complete?
openreadout check partial-copy.lif
# → error  truncated       block chain runs past end of file
# → error  missing_planes  geometry needs 16777216 bytes but only 8969789 are stored

# Integrate the peaks of a chromatogram
openreadout analyze peaks gc-run.ch --min-height 1
# → 4 peaks, area in pA·min
# → 1   4.852 min  area 0.2779  25.08 %
# → ...

# Structured JSON for scripts and agents
openreadout info cells.lif --json
{
  "ok": true,
  "schema_version": "2",
  "data": {
    "format": { "id": "lif", "name": "Leica LIF", "vendor": "Leica Microsystems" },
    "images": [
      {
        "size_x": 2048, "size_y": 2048, "size_c": 2,
        "pixel_type": "uint16",
        "physical_size": { "x": 0.325, "y": 0.325, "unit": "µm" }
      }
    ]
  }
}

Terminal session: openreadout info describes a Leica LIF file, check reports that a truncated copy is incomplete and exits with code 4, export writes a verified OME-TIFF, analyze peaks lists four peaks in a GC chromatogram, and info --json piped to jq prints the pixel size.

Formats

AreaFormatsExport to
Light microscopyZeiss CZI, Nikon ND2, Leica LIF, Olympus OIR/VSI/OIB, Imaris, OME-TIFF and other TIFF variants, OME-Zarr, whole-slide images (including Philips iSyntax, Hamamatsu VMS and MIRAX)OME-TIFF, OME-Zarr
High-content screeningHarmony (Opera Phenix, Operetta), ImageXpress, CellVoyagerOME-Zarr plate, OME-TIFF
Electron microscopyMRC, Gatan DM3/DM4, FEI SER/EMI, Velox EMD, EER movies, SerialEM mdocOME-TIFF, OME-Zarr, MRC
Structural biologyCBF/miniCBF, SMV, EIGER NeXus (NXmx) diffraction imagesMRC, OME-TIFF
Medical imagingDICOM (files, series, studies, DICOMDIR), NIfTI, Analyze, Bruker ParaVisionNIfTI, OME-TIFF
Mass spectrometryThermo RAW, Bruker timsTOF and BAF, Agilent MassHunter, Waters MassLynx, Sciex WIFF, mzMLmzML, Parquet, Arrow
ChromatographyAgilent ChemStation and OpenLab, Shimadzu, Chromeleon, AIA/ANDICSV, JCAMP-DX, Parquet
ElectrophysiologyAxon ABF, Intan, SpikeGLX, Open Ephys, Neuralynx, Blackrock, Plexon, HEKA, Spike2, TDT, Axona, NWBNWB, CSV, Parquet
NMR and spectroscopyBruker TopSpin and OPUS, Varian, JEOL, Thermo OMNIC, Renishaw, JCAMP-DX, SPCJCAMP-DX, CSV
Flow cytometryFCS, FlowJo workspaces, Gating-MLCSV, Parquet, Arrow
Plate readers and qPCRPlate-reader exports, RDML, Applied Biosystems, LightCycler, Rotor-GeneAllotrope ASM, RDML, CSV
DNA sequencing and electrophoresisIllumina run folders, Oxford Nanopore POD5 and FAST5, FASTQ, BAM, ABIF Sanger and fragment-analysis files, Agilent Bioanalyzer and TapeStationFASTQ, CSV, Parquet
OtherNanoDrop, Qubit, Incucyte, gel and blot imagers, ÄKTA, ITC, Biacore, Seahorse, Octet, Zetasizer, XRD, EPR, electrochemistry, thermal analysisCSV, Parquet

The format list lists every format OpenReadout reads, with its known gaps.

Installation

Ships as a single self-contained binary. No Java, no Python, no vendor DLLs -- nothing else to install.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/openreadout/openreadout/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/openreadout/openreadout/main/scripts/install.ps1 | iex

# Homebrew (macOS / Linux)
brew install openreadout/tap/openreadout

# npm (all platforms; installs the native binary for your platform as a dependency)
npm install -g openreadout

# Rust toolchain
cargo install openreadout --locked

Docker, Nix, cargo-binstall, and the other channels are on the install page.

Verify installation: openreadout --version

AI Integration

MCP Server

Built-in MCP server — register with one command:

openreadout mcp --install claude          # Claude Code
openreadout mcp --install claude-desktop  # Claude Desktop
openreadout mcp --install codex           # OpenAI Codex
openreadout mcp --install cursor          # Cursor
openreadout mcp --install vscode          # VS Code / Copilot
openreadout mcp --install gemini          # Gemini CLI

Windsurf, Zed, Continue, and Cline are supported too. The server exposes 28 tools (openreadout_info, openreadout_check, openreadout_preview, openreadout_export, openreadout_peaks, ...) over JSON-RPC, so the client doesn't need shell access.

Claude Code Plugin

Installs the MCP server and the skill together:

/plugin marketplace add openreadout/agent-plugins
/plugin install openreadout@openreadout

Gemini CLI Extension

gemini extensions install https://github.com/openreadout/agent-plugins

Codex Plugin

codex plugin marketplace add openreadout/agent-plugins
codex plugin add openreadout@openreadout

Each of these adds the skill and the MCP server from the openreadout/agent-plugins repository. The server runs the openreadout binary from your PATH, so install it first.

Agent Skill

openreadout self skill --install claude   # ~/.claude/skills/openreadout
openreadout self skill --install agents   # ~/.agents/skills/openreadout (Codex, Cursor, Copilot, Gemini CLI)

The skill source is in skills/openreadout.

Built for Agents

  • JSON output for every command, with published schemas.
  • Fixed exit codes: 0 ok, 1 error, 2 usage, 3 unknown format, 4 corrupt, 5 I/O, 6 unsupported.
  • Errors with a hint about what to try next.
  • Assurance on every result: whether that kind of file was checked against another reader. --strict refuses anything that wasn't.
  • Previews the agent can look at, as PNG.
  • Figures from plot: plate grids, dose-response fits, gated dot plots and more, as PNG, SVG or PDF.
  • Fast metadata: info reads headers only, so a 100 GB file is as quick as a small one.
  • Read-only and offline.

Python and R

Python — pip install openreadout returns metadata as dicts and pixels as NumPy, dask, or xarray arrays, with plugins for bioio and napari. See the Python guide.

import openreadout

with openreadout.File("cells.lif") as f:
    f.images[0]["channels"]     # same keys as `info --json`
    stack = f.to_xarray(0)      # labelled with channel names and µm
    f.preview(composite=True)   # shows itself in Jupyter

openreadout.plot(data={"file": "growth.pda"}, facet="plate").save("plate.pdf")

R — the R package returns arrays and data frames, and draws the same previews and figures. See the R guide.

Comparison

OpenReadoutBio-Formatsbioioczifile / nd2 / liffilemsconvert
Open source & free✓ (MIT / Apache-2.0)✓ (GPL)✓ (plugins vary)✓ (BSD)✓ (vendor DLLs are not)
AI-native CLI + JSON + MCP✓✗✗✗✗
Zero install (single binary)✓✗ (JVM)✗ (Python)✗ (Python)✗
No vendor DLLs✓✓✓✓✗
Integrity check✓✗✗✗✗
Microscopy✓✓✓✓ (one format each)✗
Mass spectrometry✓✗✗✗✓
Ephys, flow, NMR, chromatography, plates, qPCR✓✗✗✗✗
Cross-platform✓✓✓✓Windows (or Wine)

Validation

Each reader is tested against other readers on public instrument files. See how we validate.

The readers were written from public files, published specifications and permissively licensed readers (credited in NOTICE), without vendor SDKs or DLLs. GPL readers such as Bio-Formats are only run as black boxes in tests. See the clean-room policy and the per-format provenance logs.

Documentation

The documentation has guides for every command and format:

Privacy

OpenReadout runs on your computer, makes no network connections and sends no telemetry. See PRIVACY.md.

License

Licensed under either the Apache License 2.0 or the MIT license, at your option. OpenReadout is not affiliated with any instrument vendor; see TRADEMARKS.md.

Bug reports and contributions are welcome on GitHub Issues. See CONTRIBUTING.md, and read the clean-room policy before working on a reader.

Demo files and README images come from the public test corpus (corpus/manifest.toml), used under their licences, and are credited in .github/assets/gallery/CREDITS.md. demo.tape regenerates the terminal demo.


If you find OpenReadout useful, please give it a star on GitHub — it helps others discover the project.

NPM
openreadout
Install Command
npm install openreadout
Runtime: npx
CARGO
openreadout
Install Command
cargo install openreadout
MCPB
https://github.com/openreadout/openreadout/releases/download/v0.4.0/openreadout-mcp-aarch64-apple-darwin.mcpb
Install Command
# mcpb: https://github.com/openreadout/openreadout/releases/download/v0.4.0/openreadout-mcp-aarch64-apple-darwin.mcpb
MCPB
https://github.com/openreadout/openreadout/releases/download/v0.4.0/openreadout-mcp-aarch64-unknown-linux-musl.mcpb
Install Command
# mcpb: https://github.com/openreadout/openreadout/releases/download/v0.4.0/openreadout-mcp-aarch64-unknown-linux-musl.mcpb
MCPB
https://github.com/openreadout/openreadout/releases/download/v0.4.0/openreadout-mcp-x86_64-apple-darwin.mcpb
Install Command
# mcpb: https://github.com/openreadout/openreadout/releases/download/v0.4.0/openreadout-mcp-x86_64-apple-darwin.mcpb
MCPB
https://github.com/openreadout/openreadout/releases/download/v0.4.0/openreadout-mcp-x86_64-pc-windows-msvc.mcpb
Install Command
# mcpb: https://github.com/openreadout/openreadout/releases/download/v0.4.0/openreadout-mcp-x86_64-pc-windows-msvc.mcpb
MCPB
https://github.com/openreadout/openreadout/releases/download/v0.4.0/openreadout-mcp-x86_64-unknown-linux-musl.mcpb
Install Command
# mcpb: https://github.com/openreadout/openreadout/releases/download/v0.4.0/openreadout-mcp-x86_64-unknown-linux-musl.mcpb