https://github.com/thalesmms/mtk-demo

MTK Library and DICOM-Decoder demonstration
https://github.com/thalesmms/mtk-demo

dicom ios macos medical-imaging metal mtk swift

Last synced: about 2 months ago
JSON representation

MTK Library and DICOM-Decoder demonstration

• Host: GitHub
• URL: https://github.com/thalesmms/mtk-demo
• Owner: ThalesMMS
• License: apache-2.0
• Created: 2025-10-28T00:27:57.000Z (9 months ago)
• Default Branch: main
• Last Pushed: 2026-05-18T19:32:33.000Z (2 months ago)
• Last Synced: 2026-05-18T21:45:40.916Z (2 months ago)
• Topics: dicom, ios, macos, medical-imaging, metal, mtk, swift
• Language: Swift
• Homepage:
• Size: 49.1 MB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# MTK Demo (iOS)

SwiftUI reference viewer for the official MTK clinical path. The demo uses the public `ClinicalViewportSession` contract, one shared `VolumeResourceHandle`, four `MetalViewportSurface` instances, and explicit `TextureSnapshotExporter` readback only for user-requested export.

  

    3D Volume Rendering

    MPR View

  

  

    

    

  

## Features

- Fixed 2x2 `ClinicalViewportGrid`: axial, coronal, sagittal, and one volume/projection viewport.

- Shared dataset upload: all four panes reuse the same `VolumeResourceHandle`.

- Metal-native presentation only: interactive frames stay as `MPRTextureFrame` or `VolumeRenderFrame` until `PresentationPass`.

- Explicit snapshot/export: `TextureSnapshotExporter` is called only from the export button.

- HUD: render, presentation, upload, memory, and conditional snapshot readback timing.

- DICOM import: `DicomVolumeDatasetImporter` converts the pure-Swift `DICOM-Decoder` output into an MTK `VolumeDataset`.

- CT + PET fusion: import a CT volume, then add a PT series as a DICOM-backed PET layer with SUV cursor/ROI values, per-layer opacity, visibility, and source-over/additive blend controls.

## User-visible reference workflows

- DICOM import into the 2x2 clinical grid: choose a supported local series, convert it through `MTKDicomBridge`, and inspect axial, coronal, sagittal, and 3D views backed by one shared volume resource.

- Snapshot/export from rendered texture output: use the explicit export action; interactive viewport rendering remains texture-backed and readback happens only for the requested snapshot.

- CT plus PET fusion: import a CT series, add the registered PT series as a scalar layer, then compare SUV-aware cursor/ROI values with layer visibility, opacity, and blend mode controls.

- Feature parity diagnostics: open the in-app feature parity page to inspect codec, clinical-object, network, and demo-workflow availability without exposing imported subject data or local fixture paths.

## Project layout

- `Source/` — SwiftUI views, clinical-grid integration, and DICOM loading helpers.

- `Resource/TransferFunction/` — CT/MR presets consumed at runtime.

- `Examples/MTK_Integration_Example.swift` — Reference-only integration sample for the MTK APIs (not part of the shipping UI).

- `MTK-DemoTests/` — Tests for transfer functions, histograms, DICOM loading, and integration with MTKCore.

## Requirements

- Xcode 16, iOS 17+ deployment target.

- Metal-capable device or Apple Silicon simulator; GPU-dependent tests check this requirement and skip when Metal is absent.

- MTK package is consumed from GitHub (https://github.com/ThalesMMS/MTK.git) at version 1.1.1.

- DICOM import is provided by DICOM-Decoder from GitHub (https://github.com/ThalesMMS/DICOM-Decoder.git) at version 1.2.1 through MTKDicomBridge and direct DicomCore integration.

## Running the app

1. Open `MTK-Demo.xcodeproj`; Swift Package Manager resolves MTK and DICOM-Decoder from their GitHub repositories.

2. Select `iPhone 17 Pro Max (26.5)` or `iPad Pro 13-inch (M5) (26.5)` for simulator verification.

3. Build and run. If DICOM import cannot load a study, the import UI surfaces a descriptive error and does not treat the study as loaded.

4. For viewport-path investigation and regression debugging, see `DEBUGGING.md`.

## DICOM fixtures and tests

- Tests expect sample assets under `MTK-Demo/DICOM_Example/` (e.g., `dicom_series_example.zip` from `sample_dicom/b.zip`, and optionally `dicom_slice_example.dcm`). Missing fixtures cause skips.

- The app path uses `DICOM-Decoder` through `MTKDicomBridge`. Unit tests may inject `VolumeDatasetImporting` stubs for UI-state coverage, but the demo does not expose runtime loader switching.

## Notes on MTK integration

- `ClinicalViewportSession` is the demo's public viewer contract. It owns the shared clinical grid implementation and exposes stable viewport IDs, surfaces, debug snapshots, render mode, timing, and snapshot export entrypoints.

- `ClinicalViewportGrid(session:)` is the reference SwiftUI layout for the public clinical session contract.

- The demo does not expose legacy 3D wrappers, compatibility paths, or `CGImage`-backed interactive presentation paths.

- The demo requires Metal for rendering. Baseline Metal ray marching is the primary rendering path; MPS empty-space acceleration is an optional enhancement on supported devices.

- Multi-volume fusion uses the DICOM Frame of Reference UID plus preserved volume geometry for the initial CT/PT layer alignment. 3D rendering still expects render-compatible scalar layer texture space; MPR picking and overlays use each layer's DICOM geometry.

- Transfer function presets can be extended by adding `.tf` files to `Resource/TransferFunction/` with matching bundle paths in tests and runtime loaders.