Skip to content

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:

  1. 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.
  2. Deterministic Evaluation: Validation and test splits exclude stochastic augmentations while training supports selectable profiles (None, Basic, Heavy, Histology focused).
  3. 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.
  4. Preprocessing Parity: Inference runs (via Viewer → Predict…) apply the exact normalization, pixel scale (MPP), and class mapping bundled inside the portable .zip model package.
  5. 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 imports services/backend or services/worker code.
  • 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.