PixelPatrol

Image Dataset Quality Control and Exploration

Example Report | Tutorials | Documentation | Viewer | PyPI

Image datasets are rarely as clean or consistent as they appear. PixelPatrol scans your images and builds a shareable, browser-based interactive report - file and image metadata, pixel statistics, quality metrics, and per-dimension slice statistics - so you can compare conditions, catch outliers, and verify batch consistency before you use the data.

Overview mode - every widget as a tile; click one to expand it in place.

Installation

No terminal? Use the one-click app instead: install guide. It runs PixelPatrol in your browser, with no terminal commands or Python API.

Terminal: requires Python 3.12+. We recommend uv:

uv venv --python 3.12 .venv
source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
uv pip install pixel-patrol

For a modular install (core only + selected add-ons):

uv pip install pixel-patrol-base         # includes image quality metrics
uv pip install pixel-patrol-loader-bio   # BioIO, Zarr, Tifffile loaders

Quickstart

1. Process your dataset:

pixel-patrol process path/to/images/ -o results.parquet --loader bioio

For datasets with experimental conditions:

pixel-patrol process path/to/images/ -o results.parquet --loader bioio \
  -p condition_a -p condition_b

2. Explore in the viewer:

pixel-patrol view results.parquet

Or combine both steps with --view:

pixel-patrol process path/to/images/ -o results.parquet --loader bioio --view

To use viewer parameters, run the two commands sequentially:

pixel-patrol process path/to/images/ -o results.parquet --loader bioio && pixel-patrol view results.parquet

Or use the report manager for a visual interface - list, add, import, and open reports:

pixel-patrol launch

Python API

from pixel_patrol_base import api

project = api.create_project("my-project", base_dir="path/to/images/", loader="bioio")
api.add_paths(project, ["condition_a", "condition_b"])  # optional
api.process_files(project)
api.view(project)

Example visualizations

Spot inconsistent crops or resolutions.

See per-image spread and outliers, e.g. mean intensity, across groups.

Compare brightness and contrast across conditions.

Sharing PixelPatrol results

Send the .parquet file and open it in the hosted viewer - no installation needed. Or build a self-contained static viewer:

pixel-patrol build-viewer-html -o viewer.html             # light (~7 MB), loads DuckDB WASM from a CDN
pixel-patrol build-viewer-html -o viewer.html --offline   # fully self-contained, works with no network

Note: The static viewer may not load very large parquet files (e.g. 5 GB+). Use pixel-patrol view for large reports.

Extending PixelPatrol

PixelPatrol is designed to be extended with custom loaders, processors, and viewer widgets as standalone Python packages. See pixel-patrol-example-extension for a working template, and the Extensions documentation.