Pixel Patrol

Image Dataset Quality Control and Exploration

Documentation | Tutorials | Example Report | PyPI | Viewer

Image datasets are rarely as clean or consistent as they appear. Pixel Patrol scans your images and generates a shareable, interactive browser report - file and image metadata, pixel statistics, quality metrics, and per-dimension slice statistics. Get immediate results, compare conditions, catch outliers, verify batch consistency, and get the full picture before you use your dataset.

The interactive viewer - filter, group, and explore your dataset.

---

Installation

Requires Python 3.11+. We recommend uv:

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

Or with pip:

pip install pixel-patrol

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

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

---

Quickstart

1. Process your dataset:

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

For datasets with experimental conditions:

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

2. Explore in the viewer:

pixel-patrol view report.parquet

Or use the processing dashboard for a visual interface:

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

File size distribution across the dataset.

Image mosaic - sort by any metric to surface outliers visually.

Dimension size distributions and statistics.

---

Sharing a report

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

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

---

Extending Pixel Patrol

Pixel Patrol is designed to be extended with custom loaders, processors, and viewer widgets as standalone Python packages. See examples/minimal-extension/ for a working template, and the Extensions documentation.

---

Full documentation

ida-mdc.github.io/pixel-patrol/docs/