Documentation

Install qTrace and start capturing provenance in minutes

A short guide for anyone using QuPath — no prior coding or compliance background required. Whether you run analyses, review them for a regulated lab, or build on top of qTrace, this page gets you started.

🚀 Getting Started

Requirements: QuPath 0.7.x. Java is already bundled with QuPath — nothing extra to install there.

Install qTrace Core (free)

Download qtrace-core-1.0.11.jar from the latest release.
Copy it into your QuPath extensions folder:
Linux~/QuPath/v0.7/extensions/
macOS~/Library/Application Support/QuPath/v0.7/extensions/
Windows%APPDATA%\QuPath\v0.7\extensions\
Can't find it? In QuPath, go to Edit > Preferences > Extensions directory.
Restart QuPath, then check Extensions > QTrace — you should see "qTrace Core" in the title bar.

Activate Compliance (optional upgrade)

Compliance adds certified identity, PIN-protected stamps, replay, and chain-of-custody. It's an add-on — Core works fully without it.

Subscribe at qtrace.ca and complete identity verification (KYC).
Download your .qtlicense file from the portal.
In QuPath: Extensions > QTrace > Settings — load the file under License.
Your name appears in green (✓) in the panel once the license is valid.

⚠️Warning — Avoid renaming your QuPath project while an analysis is in progress — qTrace ties recorded steps to the project as it exists at that moment.

🖥️ Daily Workflow

qTrace works passively in the background — you don't change how you use QuPath. Open the floating panel (Extensions > QTrace > Open QTrace Panel) and follow this four-step loop.

◉

1. Record

Passive capture in the background — annotate, train classifiers, threshold as usual. Nothing to click yet.

⚡

2. Generate

Writes the Meta-Script — a plain-text recipe of what you did, readable by anyone, even without a coding background.

✅

3. Stamp

Validate & Stamp: Case ID, scope, confidence, notes — and a PIN if you’re on Compliance.

📤

4. Export

Writes the certified .qtrace sidecar file next to your image.

The resulting .qtrace file is a JSON record of your session: what was done, when, by whom, and with which parameters — everything a reviewer needs, without re-running anything.

Dashboard

Search and review validated analyses by project, date, or operator — no need to reopen QuPath.

Batch export

Export every .qtrace in a project as a single ZIP — ready to hand to a reviewer.

⚡ Compliance & Enterprise Features

Available once a Compliance license is active.

▶

Replay

Re-run a recorded analysis on another machine with one click, to prove it reproduces.

⑃

Version graph

A revision tree of every analysis and re-validation, git-like.

▤

Activity report

Printable, per-contributor audit summaries for FDA / GLP review.

☁

Cloud sync

Push a .qtrace and its classifiers to your portal workspace for certified storage.

How verification works — for QA & Compliance officers▾

Even if qTrace disappears tomorrow, your .qtrace file stays independently verifiable with open-source tools — verification doesn't depend on trusting our servers.

Offline verification — the open-source qtrace-verify CLI checks a certificate without any network access:

pip install qtrace-verify

qtrace-verify check --case-dir path/to/case_<id>/ --qpdata path/to/data.qpdata
qtrace-verify stamp   --case-dir path/to/case_<id>/
qtrace-verify upgrade --case-dir path/to/case_<id>/

Verdict	Meaning
GREEN	Signature valid · data matches · chain intact · Bitcoin anchor confirmed
YELLOW	Signature valid · chain intact · Bitcoin confirmation still pending
RED	Signature invalid, data tampered, chain broken, or validator revoked

Online verification — anyone can check a certificate at qtrace.ca/verify.

Timestamp anchoring — certificates are anchored to the Bitcoin blockchain via OpenTimestamps, giving independent proof that a record existed before a given time and can't be backdated.

🔒Compliance Note (§11.10(e)) — Audit trails are computer-generated and time-stamped automatically by ActionLogger, append-only via git — nothing is ever overwritten.

🔒Compliance Note (§11.50(a)) — Every stamp carries the signer's printed name (from a KYC-verified license), the date/time of signing, and the meaning of the signature.

🔒Compliance Note (§11.200(a)(1)(ii)) — Each stamp requires both signature components — the license and a personal PIN — every time, with no exceptions.

For developers — .qtrace format & QuPath hooks▾

A .qtrace file is JSON containing: image metadata, session info (user, machine, qTrace/QuPath version), the validation stamp, workflow step and correction counts, git commit info, project info, contributor info, and any alignment/registration data.

qTrace hooks into QuPath's own event system rather than polling — ActionLogger subscribes to QuPath's WorkflowListener and watches for classifier changes, so every recorded step reflects a real QuPath event, not a guess.

Full build-from-source instructions, the Core/Compliance architecture, and the complete security model are documented in the GitHub README.

❓ FAQ & Troubleshooting

QuPath doesn't show the qTrace menu after install

Double-check the JAR was copied to the correct extensions folder for your OS (see Getting Started above — or Edit > Preferences > Extensions directory in QuPath), then restart QuPath completely.

Where are my exported files stored?

Alongside your image: the .qtrace sidecar, a Groovy replay script under scripts/validated/, and a cumulative master_validation_log.csv. Compliance also writes a .qtcert certificate under case_<id>/certs/.

Are there limits on very large or complex images?

A few known edge cases: alignment landmarks aren't capturable after you click Apply (place Point annotations first for a visual trail); Advanced Options of the Train Pixel Classifier (max samples, seed, boundary strategy) aren't serialized by QuPath itself; and Warpy reference-image selection can't be automated.

💡Tip — Core works fully offline — recording, stamping, and exporting don't need an internet connection. Only Compliance license validation and cloud sync require connectivity, which suits air-gapped GLP workstations.

Ready to get started?

Download qTrace Core (free, open-source) — or request Compliance access for replay, chain-of-custody, and certified identity.

Download Core (free)Request Enterprise access →