CLI Reference

pixel-patrol --help

`pixel-patrol process`

Scans a directory tree, processes the images, and writes a .parquet table with embedded project metadata.

pixel-patrol process BASE_DIRECTORY -o OUTPUT.parquet [OPTIONS]

Arguments

Name	Description
`BASE_DIRECTORY`	Root folder containing your dataset.

Options

Name	Description
`-o, --output PATH`	Path for the output parquet file (e.g., my_project.parquet).
`-l, --loader NAME`	Loader plugin to use (e.g. bioio, zarr, tifffile). The loader opens image files and extracts image metadata. Without a loader, only basic file info is collected (name, size, extension).
`-p, --paths PATH`	Subdirectory to process, relative to BASE_DIRECTORY. If specified, only files within those paths are processed and they become the default grouping when the interactive report opens. If omitted, all supported files under BASE_DIRECTORY are processed. Repeatable.
`-e, --file-extensions EXT`	File extension to include (e.g. tif, nd2). Defaults to all extensions supported by the loader (every file if no loader is set). Repeatable.
`--name TEXT`	Name of the project. If not provided, derived from BASE_DIRECTORY.
`--flavor TEXT`	Label shown next to the PixelPatrol title in the viewer.
`--description TEXT`	Free-form description of the data or the project, shown below the title in the viewer and embedded in the parquet metadata.
`--processors-include NAME`	Run only these processors by ID (e.g. raster-basic, thumbnail). If set, the exclude list is ignored. Repeatable.
`--processors-exclude NAME`	Skip these processors by ID. Repeatable.
`--slice-size DIM=SIZE`	Per-dimension granularity of statistics in the output table. Z=1 produces one set of statistics per Z slice; Z=5 groups every 5 slices. By default X and Y are not sliced and all other dims step by 1. Use -1 for no slicing along that dimension. Repeatable.
`--max-workers N`	Maximum number of parallel Dask workers (default: as many as fit in free RAM, at most the CPU count). Use 1 to disable parallelism. Ignored when connecting to an existing Dask cluster.
`--mb-per-worker N`	RAM per worker in MB (default: 4096). More RAM per worker means fewer parallel workers. Images larger than 1/8 of this (headroom for in-memory expansion) are split into chunks; smaller images are batched up to that size. With an existing Dask cluster, defaults to the smallest worker's memory.
`--max-images-per-task N`	Max images per batch task or sub-images per container task (default: 200).
`--scheduler URL`	Connect to an existing Dask scheduler instead of spawning a local one (e.g. tcp://host:8786). Useful for HPC clusters.
`--rows-per-part N`	Number of rows buffered in memory before being flushed to a temporary file on disk (default: 10000).
`--parquet-row-group-size N`	Rows per row group in the final parquet (default: 2048). Smaller values speed up thumbnail sampling in the viewer.
`--log-file`	Write a debug log file alongside the output parquet (auto-named).
`--omit-base-dir`	Do not store the base directory in the parquet metadata. Useful when sharing tables without revealing local filesystem paths.
`--view`	Open the viewer immediately after processing completes, using default viewer settings. Equivalent to running `pixel-patrol view OUTPUT` afterwards.

Examples

# Minimal - basic file info only:
pixel-patrol process my-data/ -o results.parquet

# BioIO loader, two conditions, TIFF and ND2 only:
pixel-patrol process my-data/ -o results.parquet --loader bioio \
  -p control -p treated -e tif -e nd2

# Large dataset on a cluster:
pixel-patrol process my-data/ -o results.parquet --loader bioio \
  --scheduler tcp://host:8786 --log-file

# Process and open the viewer in one step:
pixel-patrol process my-data/ -o results.parquet --loader bioio --view

`pixel-patrol view`

Opens a .parquet table in the viewer as an interactive report. Starts a local server backed by DuckDB and opens the browser automatically.

pixel-patrol view PARQUET_FILE [OPTIONS]

Arguments

Argument	Description
`PARQUET_FILE`	Path to a `.parquet` file (PixelPatrol table) produced by `process`.

Options

Option	Default	Description
`--port N`	8052	Port for the local server.
`--no-browser`	off	Start the server without opening the browser.
`--group-by COL`	`path`	Column to group by on first load. Each distinct value becomes a group with its own color.
`--filter-col COL`		Column to filter on.
`--filter-op OP`		Filter operation: `eq`, `in`, `gt`, `lt`, `ge`, `le`, `contains`, `not_contains`.
`--filter-val VAL`		Filter value.
`--dim KEY=VALUE`		Pre-select a dimension slice shown across all widgets, e.g. `z=0`. Repeatable.
`--widgets-exclude NAME`		Hide a widget by its ID. Repeatable. See Available widgets.
`--significance`	off	Show pairwise statistical significance brackets on violin plots (Mann-Whitney U, Bonferroni corrected).
`--palette NAME`	tab10	Color palette for group colors.

Examples

pixel-patrol view results.parquet
pixel-patrol view results.parquet --group-by path --dim z=0 --dim t=0
pixel-patrol view results.parquet --filter-col file_extension --filter-op in --filter-val tif,nd2
pixel-patrol view results.parquet --widgets-exclude histogram --no-browser --port 9000

`pixel-patrol build-viewer-html`

Packages the viewer as a self-contained static file for sharing or hosting without a running server.

pixel-patrol build-viewer-html -o OUTPUT [OPTIONS]

If OUTPUT ends in .html or .htm, writes a single self-contained HTML file with all JS, CSS, and extensions inlined. Otherwise writes a GitHub Pages-style site folder with the viewer in OUTPUT/viewer/.

Examples

# Single file - share alongside your .parquet:
pixel-patrol build-viewer-html -o viewer.html

# Site folder - deploy to any static host:
pixel-patrol build-viewer-html -o site/

# Load a remote parquet via URL (the viewer is in site/viewer/):
# https://your-host.com/site/viewer/?data=https://yourserver.com/results.parquet

Warning

The static viewer runs entirely in the browser and 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.

`pixel-patrol schema`

Exports the table schema and plugin catalog as JSON.

pixel-patrol schema [OPTIONS]

Two formats are available:

catalog (default) - full plugin catalog: every column with description, type, and producer; loader/processor/widget metadata; and the connection graph between them.
row-schema - a standard JSON Schema document describing one parquet table row. Fixed columns are in properties; per-axis families (size_*, dim_*, pixel_size_*) are in patternProperties.

Options

Option	Default	Description
`-o, --output PATH`	`schema.json`	Path to write the JSON output.
`--print`	off	Print to stdout instead of writing a file.
`--no-widgets`	off	Skip widget metadata (requires Node).
`--format [catalog\\|row-schema]`	`catalog`	Output format.

Examples

# Full plugin catalog to a file:
pixel-patrol schema -o catalog.json

# Standard JSON Schema for integration with validators or editors:
pixel-patrol schema --format row-schema -o row-schema.json

# Print catalog to stdout:
pixel-patrol schema --print

`pixel-patrol list`

Lists available loaders and processors from installed plugins.

pixel-patrol list [--loaders] [--processors]

With no flags, lists both. Use --loaders or --processors to narrow down.

Example output

Loaders:    nifti, dicom, bioio, h5, tifffile, zarr, geospatial
Processors: raster-basic, raster-histogram, thumbnail, raster-quality, nodata-statistics

`pixel-patrol launch`

Opens the web-based report manager: it lists your existing reports, lets you add new ones (processing runs in the background), import reports stored elsewhere, and open any report in the built-in viewer.

pixel-patrol launch [--port N] [--no-browser]

Reports are stored in PIXEL_PATROL_REPORTS_DIR (default: ~/pixel-patrol-reports). Imported reports living outside that folder are remembered across restarts.

Options

Option	Default	Description
`--port N`	8051	Port for the report manager server.
`--no-browser`	off	Do not open the browser automatically.