Quickstart

Choose the path that fits you: the app (no terminal) or the terminal.

Path A: the app (no terminal)

Download and run the one-click launcher from the Installation page. No Python needed.
It opens the report manager in your browser. Use + New Report to process a folder of images, or Import Report… to add a .parquet file.
Click any report to open it in the interactive viewer.

Already installed PixelPatrol in the terminal? Run pixel-patrol launch to open the same report manager.

Path B: terminal

Install

If you don't have uv installed, install it first (once):

# macOS / Linux:
curl -Ls https://astral.sh/uv/install.sh | sh

# Windows:
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then create an environment and install PixelPatrol:

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

Requires Python 3.12+. See Installation for more options.

The two-step workflow

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

The first command reads every supported file in path/to/images/ - including subdirectories - in parallel and writes a results.parquet table. The second opens the interactive report in your browser.

Step 1: Process your dataset

PixelPatrol supports several image loaders, each suited to different formats - see Loaders for the full list. For many image formats (TIFF, Zarr, CZI, ND2, PNG, ...) the bioio loader covers everything:

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

If you have subfolders representing experimental conditions, or you only want to process images in specific subdirectories, use -p:

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

Each path becomes a group in the interactive report via the imported_path column. You can change the grouping column interactively.

To restrict to specific file extensions:

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

Step 2: Open the viewer

pixel-patrol view results.parquet

This starts a local server and opens the viewer in your browser. The viewer shows you plots for exploring your data and lets you filter, group, and compare conditions interactively.

Tip

Prefer a GUI? pixel-patrol launch opens the same app as the launcher in your browser, where you can pick your folder, process it, and open the report with a few clicks, no further commands needed (see launch).

The easiest way to share PixelPatrol results is to send the .parquet file and open it in the PixelPatrol viewer - no installation needed on the recipient's side. See the privacy policy for what's included in that file before sharing it.

Warning

The browser-based viewer may not be able to load parquet files larger than a few GB. For large tables use pixel-patrol view instead, which is backed by a local Python server with native DuckDB.

Python API

The same workflow is available as a Python API:

from pixel_patrol_base import api

if __name__ == "__main__":
    project = api.create_project(
        "my-project",
        base_dir="path/to/images/",
        loader="bioio",
        output_path="results.parquet",
    )

    # Optional: define conditions as subdirectory paths
    api.add_paths(project, ["condition_a", "condition_b"])

    api.process_files(project)
    api.view(project)

Loading a saved table

records_df, metadata = api.load("results.parquet")
print(f"{metadata.project_name}: {len(records_df)} records")

Viewing with filters

api.view(
    "results.parquet",
    group_col="path",
    filter_by={"file_extension": {"op": "in", "value": "tif,nd2"}},
    dimensions={"z": "0", "t": "0"},
)