Formats & Architecture Contracts
Overview
This reference summarizes the technical formats, semantic-segmentation data guarantees, and architectural boundaries enforced across DeepHistoImageAI Desktop (apps/desktop/) and the rest of the DeepHistoImageAI platform.
Whole-Slide Image & External Tool Integrations
| Capability | Requirements / Notes | Configured In |
|---|---|---|
| Standard Pyramidal WSIs | Supported native slide formats (e.g., .svs, .ndpi, .tif/.tiff) loaded lazily by tile pyramid level |
Viewer |
Bio-Formats Slides (e.g., .vsi) |
Requires Java 11+ (recommended: Eclipse Temurin JDK 17 for Windows x64) and configured JVM heap (512–32768 MiB) |
Settings |
QuPath Project Import (.qpproj) |
Converts external QuPath project slide references and supported annotations into a DeepHistoImageAI SQLite project | Projects |
| QuPath GeoJSON Interchange | Import manual GeoJSON regions and export ground-truth annotations or single/class prediction overlays (PredictionQuPathExportDialog) |
Viewer |
ML & Dataset Invariants
The desktop dataset preparation pipeline (DatasetWizardDialog) and runtime model packages uphold the following non-negotiable guarantees:
- Zero Data Leakage: Train, validation, and test splits are assigned strictly at the WSI level so tiles from one whole slide never cross split boundaries.
- Deterministic Evaluation: Validation and test splits exclude stochastic augmentations while training supports selectable profiles (
None,Basic,Heavy,Histology focused). - Mask & Class Fidelity: Image/mask spatial alignment, background vs semantic class indices, class ordering, and label names remain consistent from dataset creation through training and inference.
- Preprocessing Parity: Inference runs (via Viewer → Predict…) apply the exact normalization, pixel scale (MPP), and class mapping bundled inside the portable
.zipmodel package. - Lazy Slide Access: Gigapixel slides are queried tile-by-tile within the configured
Decoded tile cache (64–2048 MiB)budget rather than decoding whole slides into RAM.
Process & Security Trust Boundaries
flowchart LR
Desktop["Desktop Client\n(PySide6 / QML / Per-Project SQLite)"] -->|"HTTP API + OIDC PKCE Bearer Token"| Backend["FastAPI Control Plane\n(Auth · Tenant · Jobs · Presigned URLs)"]
Backend -->|"SQLAlchemy / Alembic"| Postgres["PostgreSQL"]
Backend -->|"Signed URLs"| ObjectStore["MinIO / S3 Object Storage"]
Backend -->|"Job Envelope + Scoped Token"| Worker["Universal CPU / CUDA Worker"]
Desktop -.->|"Direct Local Slide Access Only\n(No DB / S3 Master / Worker Imports)"| WSI["Local WSI Files"]- Desktop Client (
apps/desktop/): Owns local project directories, per-project SQLite databases, WSI filesystem paths, tile caches, and UI workflow state. Never importsservices/backendorservices/workercode. - Backend Control Plane (
services/backend/): Authoritative source for user/tenant authorization, job state transitions, remote SSH worker provisioning, and scoped object-store presigned URLs. - Universal Worker (
services/worker/): Runs versioned ML plugins (U-Net,DeepLabV3+,SegFormer-B2) inside isolated CPU/CUDA containers using temporary scoped credentials and reporting heartbeat/epoch/terminal events back to the backend.