Skip to content

Sharing a Report

A Pixel Patrol report is a single .parquet file holding everything about your dataset - metrics, thumbnails, schema, the works. Pair it with a viewer and you get the full interactive experience; this page covers all the ways to get a viewer to your collaborators (or the other way around).

Which method fits you?

📤 Tell us about your situation

Answer the three questions below and the cards for methods that don't fit will dim out - so the right one stands out at a glance.

Roughly how big is your report?
Does your collaborator need to see any custom widgets you've built?
Is this for one person (or a small group), or for anyone to find online?

Click the ✓ in the corner of each card to mark it as reviewed and track your progress.

0 / 4 methods reviewed
🖱️ Drag & drop into the hosted viewer

The zero-effort option. No installation required on either end - send your collaborator the .parquet file and point them to:

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

They drag the file into the browser and the full interactive viewer loads. Everything runs locally in their browser - no data is uploaded anywhere.

⚠️
Browser memory limits: the hosted viewer runs DuckDB in a browser WebAssembly context, capped by available browser memory. Files under 1-2 GB typically work fine; 5 GB+ may fail to load or get sluggish - reach for pixel-patrol view instead.
⚠️
No custom widgets: the hosted viewer only ships with the built-in widgets - your own viewer plugins aren't bundled in. If your collaborator needs to see those, build and host your own viewer instead (see "Host on a static server" below).
💡
Best for: a quick look together over a call, or sending a small/medium report to one person who doesn't have Pixel Patrol installed.
💻 Run pixel-patrol view locally

Your collaborator will need Pixel Patrol installed - a single pip install pixel-patrol away (see the installation tutorial). Once it's there, they can open any .parquet file directly:

pixel-patrol view report.parquet

This starts a local server backed by native DuckDB - no browser memory ceiling, fast even for very large reports.

✅
The recommended method for files above a few gigabytes. No upload, no waiting on browser WASM - just your data and your collaborator's machine.
💡
Custom widgets: they'll show up here too, but only if your collaborator also installs your extension package - it isn't bundled into pixel-patrol view the way it is into a self-contained HTML or hosted site (see below).
💡
Best for: labmates, frequent collaborators, or anyone already in the Pixel Patrol ecosystem - and the best option once your report gets big, custom widgets and all.
📄 Build a self-contained HTML viewer

Package the viewer into a single HTML file that works with any parquet:

pixel-patrol build-viewer-html -o viewer.html

Send both viewer.html and report.parquet to your collaborator. They open viewer.html in any browser, pick the parquet from the file picker, and get the full interactive experience - with nothing to install and no external link to track down.

🔬 What's actually inside viewer.html
viewer.html is the application shell, not the data - your collaborator still needs the .parquet file alongside it (same folder is easiest; the viewer offers a file picker on load). Its core - DuckDB, Plotly, your extensions - is bundled directly into the file. Its styling (Bootstrap CSS and icons), however, still loads from a CDN at runtime, so your collaborator needs an internet connection the first time they open it, even though nothing needs installing.
💡
Best for: handing someone a self-sufficient package - by email, drive, or USB stick - without needing them to find or trust an external URL.
🌐 Host on a static server

Want to publish results online - on GitHub Pages, an institutional server, an S3 bucket, or any static host? Deploy the viewer as a site folder and link straight to your parquet.

✅
This is also the natural way to share a custom viewer: any extensions installed in your environment - including your own viewer plugins - are discovered and bundled into the site folder automatically, so your collaborators get your custom widgets without installing anything.

Step 1 - build a viewer site folder:

pixel-patrol build-viewer-html -o my-report-site/

This creates a my-report-site/ directory with index.html and all viewer assets.

Step 2 - upload your parquet alongside the site (or to any public URL).

Step 3 - link to the viewer with a ?data= parameter:

https://your-host.com/my-report-site/?data=https://your-host.com/report.parquet

The viewer fetches the parquet from the URL, so it can live anywhere publicly reachable - S3, GitHub releases, institutional storage, you name it.

🔬 GitHub Pages, end to end 
# Build the viewer into your gh-pages output
pixel-patrol build-viewer-html -o docs/viewer/

# Add the parquet to the same repo (or reference an external URL)
cp report.parquet docs/viewer/

# After deploying to GitHub Pages, share:
# https://your-org.github.io/your-repo/viewer/?data=https://your-org.github.io/your-repo/viewer/report.parquet
💡
Skip the deploy entirely: if your parquet is already publicly accessible, the hosted Pixel Patrol viewer accepts a ?data= URL too - https://ida-mdc.github.io/pixel-patrol/viewer/?data=https://your-server.com/report.parquet. Anyone with that link opens the full interactive report immediately, no deployment required.
💡
Best for: publishing results alongside a paper, a project page, or a team dashboard that anyone can land on.

Bonus: share exactly what matters

✂️ Share a filtered subset
After exploring your report, apply your filters in the sidebar (by quality metric, condition, file type, ...), then Save as Parquet to export the current view as a new, fully-interactive report - or Save as CSV for the same data as a plain spreadsheet, handy for building include/exclude lists or just browsing the numbers yourself. Share either via any method above. Useful for sending a "clean" dataset after removing outliers, handing a teammate just their relevant subset, or publishing a curated, low-noise version of your results.
🏷️ Name it before you share it
If you're processing specifically to share, set --name and --description so recipients aren't left guessing what they're looking at - both appear at the top of every viewer session:

pixel-patrol process /data/my_experiment \
    -o experiment_report.parquet \
    --name "Experiment 42 - Drug Screen" \
    --description "Round 1, n=384, 20x brightfield. Processed 2026-06-07."