AcqView

Open microscopy images in your browser

Open AcqView

AcqView opens supported microscopy image files directly from your computer. It shows image metadata such as dimensions, channels, data type, acquisition time, and physical scaling, then displays the available primary and reference images.

Your files stay on your computer and are not uploaded. AcqView does not modify the files you open.

Open a microscopy file

To open a file:

1. Select Open image file and choose a CZI, ND2, OIR, TIF, or TIFF file.
2. Review the metadata reported by AcqView.

Primary images appear in the main viewer. When a supported file contains a reference image, it appears in a separate expandable viewer. OIR scan paths are drawn over reference images when available.

Microscopy formats such as OIR, CZI, ND2, and TIFF can contain many different image layouts and vendor-specific features. AcqView intentionally supports a limited set of layouts. A supported filename extension does not guarantee that every file of that type can be opened; some valid files may not open.

Export TIF files

To export an image:

1. Select Export TIF to download the complete decoded primary image.
2. When Export reference TIF is available, select it to download the reference image separately.

Exports are uncompressed ImageJ-compatible TIFF files. Primary download names append .tif to the complete uploaded filename. Reference download names append .reference.tif. Existing TIF/TIFF uploads are already TIFF, so export is disabled.

Export is intentionally simple. It preserves supported pixel values, data type, axes, and representable physical calibration, but it does not preserve every vendor metadata field, attachment, or acquisition feature. Viewer contrast, orientation, overlays, and OIR scan paths are not rendered into exported pixels.

Verify important exported files in Fiji/ImageJ or another authoritative application before using them for quantitative analysis.

Reader packages

File type	Version	GitHub Repo	Notes
CZI	2019.7.2.3	czifile	Uncompressed, single-scene files only.
ND2	0.11.3	nd2	Modern, non-RGB files; no legacy JPEG2000.
OIR	2026.7.28	oirfile	Single-file only; no spectral acquisitions.
TIF/TIFF	2026.8.23	tifffile	First series only; codec support is limited.

Technical overview

AcqView 0.2.0 is a static Vue/TypeScript application. It runs pinned Python readers in Pyodide inside a Web Worker. Opening is metadata-first; after reading metadata, the viewer requests image planes through an explicit lazy pixel path.

The normal path mounts the selected browser File read-only through Emscripten WORKERFS. It does not read or copy the complete file into MEMFS.

Requirements

• Node.js 20 or newer (build/test tooling only)
• Python 3.12 (Python adapter tests only; production uses Pyodide)
• A modern browser with Web Workers, WebAssembly, and WORKERFS support
• Internet access on first load for Pyodide and the pinned pure-Python reader wheels

The built dist/ directory is a static site. There is no application server, API, database, or Node runtime in production.

Run

AcqView uses @mapmanager/image-viewer from mapmanager-web-components for interactive image rendering, channel layouts and composites, contrast controls, physical calibration, orientation, and overlays. The two repositories use a sibling checkout layout:

cs_project/
├── acqview/
└── mapmanager-web-components/

Build the private shared viewer package before installing AcqView:

cd /path/to/mapmanager-web-components
npm ci
npm run build --workspace @mapmanager/image-viewer

cd ../acqview
npm ci
npm run dev

AcqView declares @mapmanager/image-viewer as a sibling file: dependency. The same layout and build order are used by GitHub Actions; no npm publication or machine-local npm link is required.

Build and preview

npm run build
npm run preview

Deploy the contents of dist/ to any static host. base: './' allows subdirectory hosting.

GitHub Pages

.github/workflows/pages.yml verifies and builds both repositories, uploads dist/, and deploys it to GitHub Pages on pushes to main or manual workflow runs. In the GitHub repository settings, select GitHub Actions as the Pages source.

The workflow consumes mapmanager/mapmanager-web-components@main. A component-only push does not redeploy AcqView; push AcqView or manually run its Pages workflow when a new shared-component build should go live.

Tests

npm test
npm run test:python
npm run typecheck
npm run build
npx playwright install chromium
npm run test:e2e

The default Playwright suite validates the SPA shell and exercises WORKERFS, Pyodide, metadata, pixel transfer, failure recovery, and rendering with the small uncompressed TIFF fixture in e2e/fixtures/. Regenerate that deterministic fixture with uv run scripts/create_test_tiff.py.

To exercise additional real files:

OIR_FIXTURE=/absolute/path/to/sample.oir npm run test:e2e
TIFF_FIXTURE=/absolute/path/to/sample.tif npm run test:e2e
CZI_FIXTURE=/absolute/path/to/sample.czi npm run test:e2e
ND2_FIXTURE=/absolute/path/to/sample.nd2 npm run test:e2e

npm run check runs unit tests, type checking, and the production build.

@mapmanager/image-viewer integration

The SPA uses the real ImageViewerWidget. A thin adapter exposes the scientific loader as the viewer's format-neutral AsyncPlaneSource. The viewer owns Viv, orientation, channel layouts, composites, contrast, and calibration. Python owns file-format interpretation and selected-plane reads.

An optional scan path is part of AcqView's format-neutral reference-image descriptor. The viewer wrapper translates it to the image viewer's public XyOverlay API; no OIR-specific logic exists in the viewer component. The overlay follows the viewer's transpose and flip transformations and is shared across channels.

Architecture

Vue UI / metadata / controls
        │ typed RPC
        ▼
dedicated Web Worker ── Pyodide ── Python backend registry
        │                    │
        │                    └── read-only WORKERFS browser File
        │ transferable one-plane ArrayBuffer
        ▼
AsyncRasterSource ── viewer bridge ── @mapmanager/image-viewer

Key source folders:

• src/loaders/ — stable format-neutral contracts and validation
• src/loaders/pyodide/ — shared worker-backed loader and raster source
• src/loaders/formats.ts — browser file-picker extension mirror
• src/worker/ — typed RPC, Pyodide lifecycle, WORKERFS mount
• src/worker/python/scientific_io/models.py — JSON-safe scientific dataclasses
• src/worker/python/scientific_io/backends.py — minimal backend protocol and reader registry
• src/worker/python/scientific_io/normalization.py — canonical scientific axis semantics
• src/worker/python/scientific_io/serialization.py — bounded vendor-metadata conversion
• src/worker/python/scientific_io/oir.py — isolated upstream-oirfile backend and bounded plane reader
• src/worker/python/scientific_io/czi.py — restricted legacy-czifile backend and selected-subblock reader
• src/worker/python/scientific_io/nd2.py — modern ND2 metadata and selected-frame backend
• src/worker/python/scientific_io/tiff.py — isolated upstream-tifffile backend and selected-page reader
• src/worker/python/scientific_io/pixels.py — shared pixel dtype transport
• src/worker/python/scientific_io/rpc_api.py — thin Pyodide entry points
• src/worker/python/requirements-pyodide.txt — exact runtime Python dependency pins
• src/viewer/ — OIR-free image-viewer bridge
• tests/ and e2e/ — contracts, memory invariant, RPC, viewer adapter, browser smoke tests

Native reader inspection

Native inspection scripts are separate from the browser runtime. They can use compiled packages such as imagecodecs to evaluate formats before AcqView claims browser support. Each script declares its own pinned dependencies for uv, so it does not add a Python environment or dependency lock to the SPA.

Inspect one CZI without loading pixel arrays:

uv run scripts/inspect_czi.py /absolute/path/to/sample.czi

Recursively inventory a directory, emitting one compact JSON record per file:

uv run scripts/inspect_czi.py --compact /absolute/path/to/czi-folder

The report includes the CZI header, scenes, axes, shapes, dtypes, channels, pyramid levels, and compression modes. This native result is an inventory tool, not evidence that a compression codec will run in Pyodide.

Memory behavior and limits

WORKERFS avoids a whole-file MEMFS copy. Metadata parsing can still read format index/header structures into Python. A pixel request reads one selected OIR or ND2 plane, TIFF page, or uncompressed CZI subblock, copies the resulting plane to a JS typed array, and transfers its ArrayBuffer to the main thread. The MapManager/Viv path manages its own rendering buffers.

OIR does not expose a stable public region/tile API today, so claiming true tile reads would be misleading. fetchPlane() is the current boundary. A later measured optimization can add regions without changing UI or viewer contracts.

Format-specific notes

OIR reference scan paths

When an OIR contains a reference image and oirfile exposes its public reference.line_roi value, AcqView records the two endpoints in reference-image pixel coordinates. The path appears in metadata exports and is drawn over the reference viewer. It is metadata-only and does not require loading primary-image pixels.

CZI reference scan paths

CZI scan-path support is deliberately not implemented. AcqView pins czifile==2019.7.2.3 for the current browser-compatible CZI reader. That release exposes generic attachments, but a ZISRAW attachment decodes to a nested CziFile rather than the NumPy array expected by the scan-path heuristic used with newer czifile releases. AcqView will not upgrade the reader solely for this feature. A representative CZI containing both a reference image and a scan path must first be verified with the pinned version.

Deliberately deferred

• Recursive directory selection and the metadata table
• Legacy JPEG2000, RGB, and multi-position ND2
• Additional TIFF series, pyramids, and compression codecs unavailable in Pyodide
• Multi-file OIR
• Spectral/lambda acquisitions
• CZI reference images and scan paths
• Pixel cache and prefetching (the current release retains only the current plane)
• imagecodecs, server-side parsing, and uploads

Diagnostics

The metadata panel presents normalized file and selected-image headers first, followed by format-specific metadata. Runtime adapter and performance diagnostics remain available as secondary details. The UI records open/metadata duration, file size, selected-plane duration, and bytes transferred. Backend diagnostics report WORKERFS and wholeFileCopied: false. The memory-policy test prevents whole-file reads or writes of the selected image. Small Python application modules are installed into Pyodide's application filesystem during worker initialization.

License, legal notice, and attribution

Copyright © 2026 Robert H. Cudmore. AcqView is licensed under the GNU General Public License version 3.

AcqView is an independent open-source research viewer and is not affiliated with or endorsed by ZEISS, Nikon, Olympus, or Evident. It is not intended for clinical use. See the full legal notice and third-party attribution.