MTK 1.1.1

MTK 1.1.1

This release covers the changes from tag 1.1.0 to tag 1.1.1.

Compare: 1.1.0...1.1.1

Summary

MTK 1.1.1 focuses on volume ingestion and texture reuse. It adds chunked volume upload entry points across the rendering engine and UI-facing viewport/session types, lets rendering and MPR paths reuse a preuploaded primary 3D texture instead of uploading the same volume again, updates DICOM volume import to respect per-slice rescale parameters from DICOM-Decoder, and moves the DICOM-Decoder dependency to 1.2.1.

The diff from 1.1.0 contains one commit and changes 12 files, with 387 insertions and 30 deletions.

Chunked Volume Uploads

• Added MTKRenderingEngine.setVolume(uploadDescriptor:slices:for:progress:) for assigning a streamed VolumeUploadSlice sequence to one or more viewports.
• The engine now acquires a shared VolumeResourceHandle from ChunkedVolumeUploader / VolumeResourceManager, retains it for all target viewports, invalidates MPR frame caches, and releases replaced handles.
• The upload path deduplicates viewport IDs and validates that every target viewport exists before committing the shared handle.
• Added public applyVolumeUpload(referenceDataset:uploadDescriptor:slices:progress:) APIs through:
  • ClinicalViewerCoordinator
  • ClinicalViewportGridController
  • VolumeViewportController
  • StackViewport
  • VolumeViewport3D
  • ClinicalViewportSession

Preuploaded Primary Volume Textures

• Added PreuploadedPrimaryVolumeTexture tracking in VolumeViewportController.
• The controller records the uploaded Metal texture together with cache key, byte count, dimensions, pixel format, intensity range, and texture identity.
• Dataset application now skips redundant work when the existing dataset storage and preuploaded texture identity already match.
• MPR texture lookup now reuses the preuploaded primary texture when it matches the active dataset.
• 3D rendering now calls renderTexture(using:volumeTexture:) with the preuploaded texture when available, avoiding an additional upload path for the same volume.
• MetalVolumeRenderingAdapter.renderTexture(using:volumeTexture:) is now public so UI/controller layers can render directly from a managed texture.

DICOM Import Changes

• Updated DicomVolumeDatasetImporter to apply per-slice rescale parameters when converting decoder-owned DicomSeriesVolume voxels into MTK modality voxel data.
• The importer uses per-slice slope/intercept values when sliceRescaleParameters.count == depth; otherwise it keeps the existing default slope/intercept behavior.
• The conversion path handles both signed and unsigned source pixel buffers and updates the resulting intensity range from converted modality values.
• Added a DICOM bridge packaging test covering per-slice rescale conversion for a two-slice unsigned volume.

Dependency Changes

• Updated DICOM-Decoder from 1.2.0 to 1.2.1.
• Package.resolved now pins DICOM-Decoder to revision 800028d9dcf448670b9fd115494860d5535440d4.

MTK 1.1.0

MTK 1.1.0

This release covers the changes from tag 1.0.9 to tag 1.1.0.

Compare: 1.0.9...1.1.0

Summary

MTK 1.1.0 expands the library from core volume, MPR, and clinical viewport primitives into a broader DICOM-aware clinical viewing toolkit. The release adds DICOM bridge support for segmentation, RT Dose, RT Structure, PET fusion, parametric maps, structured reports, key-object navigation, presentation state, non-image objects, and ROI round-tripping. It also adds quantitative scalar layer models, dose sampling/statistics, progressive volume update plumbing, MPR presentation shutters, scalar overlays in MPR, hanging-protocol layout support, structured-report UI state, and new SwiftUI components for clinical object display.

The diff from 1.0.9 contains one commit and changes 113 files, with 13,850 insertions and 262 deletions.

Package and Dependency Changes

• Updated the remote DICOM-Decoder dependency from 1.1.4 to 1.2.0.
• Updated Package.resolved to pin DICOM-Decoder at revision 3fc5905a4ffaef0c89e860914259737c8dcdff6b.
• Added MTKUI as a dependency of MTKDicomBridge and MTKDicomBridgeTests, because the bridge now exposes viewer-facing state for key images, structured reports, ROI round-trips, and related clinical UI models.

DICOM Bridge Expansion

• Added DicomClinicalObjectImporter and DicomClinicalObjectDisplayBridge for routing decoded DICOM clinical objects into MTK display state.
• Extended DicomVolumeDatasetImportResult with quantitativeValueProfile and keyImageNavigationState.
• Added conversion from DICOM SEG objects into VolumeLayer labelmaps through DicomSegmentationVolumeLayerBuilder.
• Added optional SEG-derived surface mesh extraction through MarchingCubesExtractor and SurfaceMeshLayer output.
• Added VolumeMaskDicomSegmentationExporter for exporting edited volume masks back into DICOM segmentation datasets and Part 10 data.
• Added DicomRTDoseVolumeOverlayBuilder for building RTDoseVolumeOverlay values from decoded RT Dose volumes, including dose-grid scaling, frame-of-reference validation, colorwash transfer functions, and dose metadata.
• Added DicomRTStructureContourOverlayBuilder for RT Structure contour overlays and optional surface mesh layer generation.
• Added DicomPETFusionLayerBuilder for PET scalar overlays aligned to a base volume, including SUV mapping, SUV unit metadata, frame-of-reference validation, and additive PET-style default blending.
• Added DicomParametricMapScalarLayerBuilder for DICOM Parametric Map scalar overlays with physical value mapping, real-world value metadata, and stored-value quantization.
• Added DicomPresentationStateMPRBridge for converting DICOM grayscale presentation state content into MPR presentation state.
• Added DicomStructuredReportViewerBridge for mapping decoded structured reports into StructuredReportViewerState, measurement lines, tree nodes, and CAD finding overlays.
• Added DicomKeyObjectSelectionNavigationBridge for converting key object selection documents into key-image navigation state.
• Added DicomProgressiveVolumeDatasetStream for streaming decoded DICOM volume updates into progressive MTK datasets.
• Added ViewerROIDicomRoundTrip for converting viewer ROI annotations to and from DICOM SR, grayscale presentation state, segmentation, and Part 10 data.
• Extended DicomVolumeDatasetImporter with dataset construction from DicomSeriesVolume, unsigned pixel conversion, rescale slope/intercept conversion, recommended window calculation, study description propagation, and key-image state construction.

Core Domain Models

• Added MPRPresentationState, MPRPresentationGraphicAnnotation, MPRPresentationGraphicStyle, and presentation shutters for MPR display state.
• Added ProgressiveVolumeDataset, ProgressiveVolumeDatasetUpdate, ProgressiveVolumeLayer, and stream state types for preview/final volume update workflows.
• Added QuantitativeScalarLayer models for coded concepts, quantity definitions, physical value mappings, scalar legends, and sampled quantitative values.
• Added QuantitativeScalarVolumePicking and QuantitativeScalarStatistics for sampling quantitative scalar overlays and summarizing values inside labelmap ROIs.
• Added RTDoseVolumeOverlay, RTDoseColorLookupTable, RTDoseSample, and RTDoseStatistics for dose colorwash overlays, dose picking, and ROI dose statistics.
• Added RTStructureContourOverlay and RTStructureContour for contour-based RT Structure overlays.
• Added RTStructureSurfaceMeshExtractor for converting RT Structure contours into surface mesh layers.
• Extended SurfaceMesh with metadata support for source and DICOM-related fields.
• Extended VolumeDataset and clinical metadata surfaces to support the new DICOM bridge workflows.

Volume Layers and MPR Rendering

• Extended ScalarVolumeLayer and VolumeLayer with optional QuantitativeScalarMapping.
• Added quantitative legend accessors on VolumeLayer.
• Added labelmap segment visibility and opacity mutators.
• Added MPRScalarVolumeOverlay and ScalarVolumeColorLUTBuilder for scalar overlays in MPR views.
• Extended VolumeLayerMPRMapper and VolumeLayerResourceCache to build and cache MPR scalar overlay textures and color lookup textures.
• Updated RenderPassDispatcher, MTKRenderingEngine, RenderFrame, and FrameMetadataBuilder to carry the expanded layer and metadata surface.
• Updated ArgumentEncoderManager for the new rendering/resource paths.
• Rebuilt bundled metallib resources for macOS, iPhoneOS, and iPhone simulator.

MPR Presentation Pass

• Added MPR scalar overlay compositing for signed and unsigned scalar textures.
• Added rectangular and circular MPR presentation shutters.
• Added scalar overlay validation for device, scalar pixel format, and LUT pixel format.
• Added alternate reusable overlay texture handling to avoid read/write conflicts when chaining scalar and labelmap overlays.
• Extended presentation metadata with scalar overlay counts and shutter presence.
• Updated mpr_presentation.metal with shutter checks and scalar overlay kernels for signed and unsigned textures.

Clinical UI and Viewport State

• Extended MedicalViewport, StackViewport, VolumeViewport, VolumeViewport3D, and ClinicalViewportSession with progressive update state and APIs.
• Added public session APIs for RT Dose overlays, RT Structure contour overlays, quantitative scalar statistics, labelmap volume summaries, MPR presentation state, structured report state, metadata overlay settings, and hanging protocols.
• Added HangingProtocolDefinition, display-set matching, rule resolution, resolved layouts, and HangingProtocolEngine.
• Updated ClinicalViewportGrid to apply hanging protocols, render a 3D slot when requested, and suppress manual axis controls when a resolved protocol owns slot assignment.
• Added key-image navigation state through KeyImageNavigationState, KeyImageReference, LoadedKeyImageInstance, and ResolvedKeyImage.
• Added StructuredReportViewerState, structured report tree nodes, measurement lines, CAD finding overlay items, and selected-finding state.
• Added RTStructureContourOverlayProjector and contour overlay configuration for 2D projection of RT Structure contours.
• Added metadata overlay settings for viewport-specific clinical metadata display.

New UI Components and Overlays

• Added ClinicalEncapsulatedDocumentView and display state for encapsulated document objects.
• Added ClinicalNonImageObjectPanelView and state for non-image clinical objects.
• Added ClinicalVideoView and video display state.
• Added ClinicalWaveformView and waveform trace display state.
• Added StructuredReportPanelView for structured-report measurements, tree content, and CAD finding selection.
• Added CADFindingOverlayView for viewport overlay of structured-report/CAD finding regions.
• Added ClinicalViewportMetadataOverlay.
• Extended Clinical2DViewportOverlay, Clinical2DHUDOverlay, and MPRImageAnnotationsOverlay to include quantitative, dose, metadata, and annotation changes.

ROI and Measurement Changes

• Extended ViewerROIKind with angle, Cobb angle, area, ellipse, closed path, curved line, scribble, volume, and CTR measurement modes.
• Added measurement model and unit handling for the expanded ROI types.
• Added ROI persistence models for points, measurements, and store state.
• Added ROI measurement calculation for distances, angles, areas, ellipses, polylines/freehand length, ratios, and volume-style summaries.
• Added labelmap volume summary calculation for ROI/segmentation layers.
• Updated 2D ROI overlay rendering for polylines, polygons, ellipses, Cobb angle, CTR, area labels, and measurement labels.
• Added ROI round-trip support through DICOM SR and presentation-state bridge types.

Diagnostics and Benchmarks

• Extended ClinicalBenchmarkMeasurement with per-stage measurements.
• Added ClinicalBenchmarkStageMeasurement.
• Updated JSON decoding to tolerate missing stageMeasurements in older benchmark reports.
• Added stageBreakdown to CSV export.
• Added per-stage aggregation from profiling samples, including CPU time, optional GPU time, and peak memory.

Tests

• Added or extended tests for quantitative scalar layers, RT Dose overlays, RT Structure surface extraction, MPR scalar overlays and shutters, benchmark stage export, volume picking, volume layers, DICOM clinical object import/display, key object navigation, structured reports, ROI DICOM round-trips, volume mask segmentation export, hanging protocols, key-image navigation, progressive volume updates, structured report UI state, non-image clinical object state, video/waveform components, RT Structure projection, medical viewport contracts, and expanded ROI behavior.

Notes for Adopters

• MTKDicomBridge now exposes some UI-facing bridge resul...

MTK 1.0.9

MTK 1.0.9

This release covers the changes from tag 1.0.6 (48295a0) to tag 1.0.9.

Compare: 1.0.6...1.0.9

Summary

MTK 1.0.9 expands the clinical viewer surface beyond the previous MPR-focused release. The main changes are a dedicated 2D stack mode, more complete MPR and 3D viewer controls, configurable volume rendering quality, ROI and synchronization models, improved MPR viewport transforms, and an update of the remote DICOM-Decoder dependency to 1.1.4.

The diff from 1.0.6 contains four commits and changes 82 files, with 10,733 insertions and 151 deletions.

Clinical Viewer Modes and Chrome

• Added ClinicalViewerMode.stack2D alongside the existing single3D and clinical modes.
• Added a larger ClinicalViewerCoordinator state surface for switching between 3D, MPR, and 2D workflows while retaining cached viewports where appropriate.
• Added data-driven viewer chrome configuration through ViewerChromeConfiguration, ViewerChromeConfigurationFactory, tool descriptors, menu items, option actions, settings sheet identifiers, and chrome state tracking.
• Added reusable SwiftUI toolbar and menu views for bottom toolbars, MPR toolbars, options buttons, and contextual viewer menus.
• Added quick preset models for clinical transfer functions and window/level presets used by the viewer controls.
• Added compact and mode-specific control handling for 3D, MPR, and 2D tools.

2D Stack Viewing

• Added StackViewport presentation state for 2D stack workflows, including slice index, axis, window/level, CLUT inversion, viewport transform, and adaptive-sampling interaction hooks.
• Added 2D tool models for scrolling, window/level, rotation, ROI, sync, and reslice.
• Added 2D scroll configuration, including speed presets, loop-through behavior, image sort mode, and optional on-screen controls.
• Added 2D transform support for zoom, pan, rotation, horizontal flip, and vertical flip.
• Added Clinical2DInteractionOverlay, Clinical2DHUDOverlay, and Clinical2DViewportOverlay for stack interaction and presentation state.
• Added reslice-axis handling and availability checks for volumetric versus planar datasets.
• Added privacy-safe 2D HUD text construction through ClinicalDisplayTextSanitizer.

ROI and Sync Models

• Added common ROI models: ViewerROIKind, ViewerROIAnnotation, ViewerROIStore, ROI styling, measurement values, hit testing, editing helpers, and measurement calculators.
• Added distance, angle, Cobb angle, area, polyline, CTR, and text ROI measurement support at the model level.
• Added MPR annotation overlay support through MPRImageAnnotationsOverlay.
• Added ROI actions to MPR and 2D coordinator paths, including active-view deletion and full-session deletion.
• Added viewer synchronization models for transforms, window/level, location, same-study constraints, panel identity, and source-panel propagation.
• Added Clinical2DSyncCoordinator for applying compatible 2D panel updates across registered panels.

3D Volume Controls

• Added VolumeRenderQualitySettings, VolumeRenderQualityOption, VolumeRenderIterationQuality, and VolumeShadowMode as the public rendering-quality contract.
• Added quality settings persistence through VolumeRenderQualitySettingsStore and coordinator-level loading/saving.
• Connected quality settings to sampling step, interaction sampling factor, gradient depth scale, lighting enablement, and shader lighting parameters.
• Added 3D orientation presets through Volume3DAnatomicalOrientation, including anatomical camera axes derived from the dataset orientation.
• Added camera orientation and camera-rotation reset entry points on the 3D viewport/controller path.
• Added 3D crop and brush state models, overlay views, tool menus, brush mask editing, and brush cursor layout helpers.
• Added 3D picking integration through VolumeViewportController.pickVolume(...) and VolumeViewport3D.pickVolume(...).
• Added primary volume dataset override support for layer-oriented volume rendering workflows.

MPR Presentation and Controls

• Added rotation to MPRViewportTransform and propagated it through MPR presentation uniforms and the Metal presentation shader.
• Updated MPR presentation coordinate handling so zoom, pan, rotation, and flips can be applied without invalidating the cached raw MPR slice.
• Added MPR toolbar support for rotation and ROI tools.
• Added MPRSlabBlendOption for mean, minIP, and MIP slab controls.
• Added MPR screen layout choices (hSplit2x1, hSplit1x2, vSplit3x1) and coordinator state for the selected layout.
• Added MPR window preset, CLUT preset, inversion, slab thickness, and slab blend state to the public session surface.
• Added presentation-only MPR inversion and CLUT handling for stack and MPR viewports.
• Updated orientation labels to use per-label rounded backgrounds instead of one shared overlay background.

Clinical Viewport Behavior

• Improved viewport session caching so switching modes can preserve the relevant 3D, MPR, or 2D state.
• Added explicit state synchronization from ClinicalViewportSession and StackViewport back into ClinicalViewerCoordinator.
• Added APIs for applying and propagating volume layers, surface mesh layers, crop/clip state, adaptive sampling, quality settings, MPR transforms, ROI state, and window/level state through the coordinator.
• Added snapshot export plumbing for active 3D and MPR workflows, including PNG export metadata and explicit error reporting when the active mode cannot export.
• Added profiling HUD refresh support for timing and resource metrics.

DICOM Bridge and Dependency Changes

• Updated DICOM-Decoder from 1.1.3 to the remote GitHub dependency at 1.1.4.
• Updated Package.resolved to pin DICOM-Decoder at revision 17b84bc8428e8c43495e16e19fe8a427f5120c83.
• Updated the README wording so MTKDicomBridge is described as depending on the remote DICOM-Decoder package, not a local package.
• Added patient-name propagation from DicomCore.DicomDecodedSeries into ClinicalImageMetadata.

Tests Added or Updated

• Added coverage for volume render quality settings, sampling-step derivation, lighting gating, and scheduler application.
• Added 2D interaction router, 2D viewport overlay, display-text sanitizer, viewer chrome, ROI, sync, brush, crop, orientation, and window/level tests.
• Added MPR annotation overlay and MPR presentation transform coverage.
• Expanded clinical viewer coordinator tests for mode switching, 2D stack behavior, MPR controls, ROI actions, sync state, quality settings, snapshot paths, crop/clip state, and volume brush state.
• Expanded clinical viewport grid and controller tests for shared resource behavior, active-axis state, MPR windowing, ROI state, quality propagation, and camera/orientation behavior.
• Updated DICOM bridge packaging tests to cover patient-name metadata propagation.

Compatibility Notes

• Consumers with exhaustive switches over ClinicalViewerMode must handle the new stack2D case.
• Consumers with exhaustive switches over ClinicalMPRInteractionTool must handle the new rotation and roi cases.
• Consumers with exhaustive switches over NativeVolume3DInteractionMode must handle the new crop and brush cases.
• VolumeRenderRequest now carries renderQualitySettings; the initializer supplies .default, so existing initializer call sites remain source-compatible unless they depend on memberwise behavior.
• RenderQualityScheduler.interactionFactor is now public private(set) and should be updated through setInteractionFactor(_:) or applyVolumeRenderQualitySettings(_:).

MTK 1.0.6

MTK 1.0.6

This release covers the changes from tag 1.0.5 to tag 1.0.6.

Compare: 1.0.5...1.0.6

Summary

MTK 1.0.6 focuses on MPR presentation correctness, clinical viewport behavior, architecture documentation, and package dependency maintenance. The release adds shared layout primitives for MPR rendering, picking, and crosshair projection; lets the rendering engine retain per-viewport MPR plane geometry; updates the clinical grid around the displayed MPR surfaces; and moves the optional DICOM bridge dependency from exact 1.1.2 to SwiftPM from: "1.1.3".

The diff from 1.0.5 contains one commit and changes 59 files, with 3,198 insertions and 561 deletions.

MPR Presentation and Geometry

• Added MPRPresentationLayout and MPROutputAspect as shared primitives for aspect-fit MPR presentation. Rendering, picking, and overlay coordinate conversion can now use the same drawable-to-image mapping.
• Extended MPRPlaneGeometry with optional outputWidth and outputHeight, plus derived outputPixelSize and physicalAspectRatio helpers.
• Changed MPRPlaneGeometry.sizedForOutput(_:) so it records the requested output size without rescaling the plane axes. This keeps physical plane geometry separate from raster output dimensions.
• Updated MPRFrameSignature hashing so MPR cache keys include the explicit output dimensions.
• Updated MPRPresentationPass and mpr_presentation.metal so MPR slabs are presented into the drawable size while preserving the plane physical aspect ratio. Labelmap overlay uniforms use the same image-origin and image-size mapping.
• Relaxed MPR presentation size validation from exact source/drawable equality to positive source and drawable dimensions, matching the new aspect-fit presentation path.

Picking, Crosshair, and Oblique MPR Behavior

• Added VolumePickError.outsideImagedArea for clicks or drags in aspect-fit letterbox/pillarbox regions outside the rendered MPR image.
• Updated VolumePicking.pickMPR and VolumePicking.screenPoint to take an outputAspect argument, so MPR interaction and world-to-screen projection can account for presentation layout.
• Reworked clinical crosshair state around a single cursor model (mprCursorVoxel and mprCursorWorldPoint) instead of only per-axis normalized positions.
• Updated crosshair offsets to project through the same aspect-fit layout used by the MPR presentation shader, reducing overlay drift on anisotropic datasets.
• Added crosshair angle support and oblique plane configuration for perpendicular MPR views. Drag handling now distinguishes crosshair movement, slice scrolling, pan, window/level, and tilt-style interaction.
• Corrected coronal texture-coordinate handling so the sagittal component is mirrored consistently with the display contract.

Rendering Engine and Compute Path

• Added per-viewport mprPlaneGeometry storage to MTKRenderingEngine, with cache invalidation when the configured geometry changes.
• Updated RenderPassDispatcher to prefer configured MPR geometry when present, falling back to the factory-generated axis plane otherwise.
• Added a debug accessor for configured MPR plane geometry to support regression tests.
• Added MetalMPRComputeAdapter.ComputeError.invalidComputeConfiguration and validation for positive dispatch dimensions, command queue/device consistency, and output texture capacity.
• Updated MPR slab sizing so explicit geometry output dimensions drive compute dispatch size when available.
• Refreshed precompiled Metal libraries for device, simulator, and macOS package resources.
• Added a two-level empty-space skipping path in the volume compute shader, with helper routines for block-exit distance and mip-level transparency checks.

Clinical Viewport UI and Session Behavior

• Added interactionMode and showsCompactChrome options to ClinicalViewportGrid initializers.
• Reworked ClinicalViewportGrid layout around three displayed MPR panes, including compact phone layout support, resizable split panes, axis menus, and per-pane fullscreen toggles.
• Added post-layout MPR presentation refresh so surface size changes can reconfigure rendering and crosshair projection after layout settles.
• Limited routine clinical grid rendering to the displayed MPR viewports. The retained volume viewport is now configured for explicit snapshot/export-style work instead of being scheduled for hidden presentation updates during ordinary MPR changes.
• Updated window/level, transfer-function, layer, clipping, and volume-mode flows to avoid scheduling hidden volume renders when only MPR presentation should update.
• Preserved clinical session state when switching modes through ClinicalViewerCoordinator, and propagated opacity/adaptive-sampling preferences to existing and future sessions.

Presentation Surface Robustness

• Hardened MetalViewportSurface readiness checks to reject detached or invalid transient layout states before submitting presentation work.
• Added finite-size sanitization for drawable pixel sizes, falling back to 1x1 when bounds or scale produce invalid values.
• Added refreshPresentationSurface(forceReadyNotification:) for explicit drawable-size refreshes.
• Updated surface logging to report drawable dimensions safely, including non-finite intermediate layout values.
• Updated SwiftUI/AppKit/UIKit container handling so a surface view is not detached incorrectly when it has been reparented to another viewport container, and so higher-priority containers retain ownership while attached.

Architecture and Documentation

• Added architecture documents for public API boundaries, clinical rendering decisions, multi-volume registration scope, and rendering engine split.
• Added an architecture README index.
• Updated the main README with separate 3D and MPR screenshots.
• Removed the older single screenshot and added screenshots/screenshot1.PNG and screenshots/screenshot2.PNG.
• Adjusted README setup and testing notes to describe the local package layout and optional sibling demo fixtures more directly.

Dependency Changes

• Updated DICOM-Decoder from exact 1.1.2 to SwiftPM from: "1.1.3" in Package.swift.
• Updated Package.resolved accordingly.

Tests Added or Updated

• Added MPR presentation coverage for aspect-fit letterboxing instead of stretching source pixels.
• Added volume-picking tests for aspect-fit screen projection, rejection of letterbox/pillarbox clicks, and screen/pick round-tripping.
• Added MPR compute coverage for single-pixel output dispatch.
• Added clinical grid tests for global cursor synchronization, overlay-to-presentation pixel alignment on anisotropic panes, ignored letterbox drags, crosshair rotation, oblique MPR configuration, and clinical orientation labels after rotation.
• Added clinical coordinator tests for opacity scale propagation, adaptive-sampling preference propagation, and clinical session caching across mode changes.
• Added presentation surface tests for detached surface rejection, invalid drawable-size fallback, container reparenting, and presentation-priority ownership.
• Added an iOS host-view integration test confirming the clinical grid hosts three MPR Metal viewport surfaces.

Compatibility Notes

• Call sites for VolumePicking.pickMPR and VolumePicking.screenPoint must now provide an MPROutputAspect value.
• Code that inferred output raster size from scaled MPR plane axes should switch to MPRPlaneGeometry.outputWidth, outputHeight, or outputPixelSize.
• DICOM-Decoder is no longer pinned to exactly 1.1.2; SwiftPM can resolve compatible versions starting at 1.1.3.

MTK 1.0.5

MTK 1.0.5

This is the first published GitHub release for MTK. These notes summarize the repository from the initial import through tag 1.0.5.

Tag 1.0.5 is based on MTK with DICOM-Decoder pinned to 1.1.2, including the corrected IPP-based DICOM Z spacing used by MTKDicomBridge.

Summary

MTK is a Swift Package for Metal-native volumetric rendering and clinical-style viewport presentation on Apple platforms. The package exposes core rendering types, a SwiftUI presentation layer, an optional DICOM bridge, synthetic fixtures, and a benchmark executable. The official interactive rendering path is Metal-based; SceneKit-era presentation code was removed from the package
contract.

Package products

• MTKCore: core domain models, rendering adapters, Metal resources, geometry, transfer functions, statistics, texture upload, render graph utilities, and diagnostics.
• MTKUI: SwiftUI-facing viewport contracts, clinical grid/session UI, overlays, interaction handling, and MTKView/CAMetalLayer presentation.
• MTKDicomBridge: optional bridge from DICOM-Decoder decoded series into renderer-ready VolumeDataset values.
• MTKFixtures: synthetic fixture datasets generated by code for examples and tests.
• VolumeRendererComparison: benchmark executable for comparing the MTK rendering path with a reference ray-marching shader.

Rendering architecture

• Establishes the Metal-native clinical pipeline: VolumeDataset -> VolumeResourceManager -> GPU textures -> MTKRenderingEngine -> ViewportRenderGraph -> render passes -> PresentationPass -> MTKView.
• Uses MTLTexture as the interactive frame result. CGImage readback is kept for explicit snapshot, export, debug, or test workflows.
• Adds MTKRenderingEngine, ViewportRenderGraph, render-route resolution, output texture pools, texture leases, presentation passes, and resource management for shared viewport resources.
• Adds MetalRaycaster, MetalVolumeRenderingAdapter, VolumeRaycastPass, VolumeLayerCompositePass, and related dispatch/parameter/texture preparation infrastructure.
• Adds precompiled metallib resources for downstream Xcode projects and removes the shader build plugin from the release package path.
• Adds structured runtime checks for Metal availability and optional MPS feature availability.

Volume data and geometry

• Adds VolumeDataset, ImageData3D, spacing, dimensions, pixel format, intensity range, orientation, origin, and dataset identity/fingerprint support.
• Adds DICOMGeometry and DICOM-aware world, voxel, and texture coordinate transforms.
• Adds MPR plane geometry and display transform factories for anatomical MPR presentation.
• Adds volume picking utilities for mapping viewport interaction back into volume coordinates.
• Adds volume clipping/cropping contracts and axis-aware clipping behavior.
• Adds surface and labelmap data contracts, including SurfaceMesh, SurfaceMeshLayer, and deterministic CPU marching-cubes extraction.

DICOM bridge

• Adds MTKDicomBridge as the package boundary between DICOM parsing and MTK rendering.
• Converts DicomCore.DicomDecodedSeries into VolumeDataset while preserving dimensions, spacing, orientation, origin, rescale information, signed/unsigned modality data, and series metadata.
• Leaves DICOM source discovery, ZIP extraction, geometry validation, rescale/window metadata, and parser errors in DICOM-Decoder.
• Pins DICOM-Decoder to 1.1.2, which uses real IPP slice deltas for volume Z spacing when reliable IPP metadata is available.

MPR, projection, and 3D rendering

• Adds Metal MPR adapters and compute shaders for axial, coronal, sagittal, and oblique reslicing.
• Adds slab support and presentation shaders for MPR output.
• Adds 3D volume rendering through DVR and projection-style rendering paths backed by Metal textures and transfer functions.
• Adds presentation support for MPR frames and volume frames through the same drawable-backed presentation infrastructure.
• Adds render quality state and scheduling utilities for interactive updates.

Transfer functions and windowing

• Adds clinical transfer-function models, JSON-compatible transfer-function contracts, transfer-function preset loading, and volume-rendering preset metadata.
• Adds CT and MR transfer-function resource presets, including bone, lung, soft tissue, brain, angiography, cardiac, abdominal, liver vasculature, fat, chest contrast, pulmonary arteries, and whole-volume CT presets.
• Adds advanced tone-curve modeling and UI-facing transfer-function editing support.
• Adds optional 2D transfer-function/gradient-opacity support.
• Adds window/level preset helpers and display contracts used by MPR and volume presentation.

Multi-volume, overlays, and surfaces

• Adds v1 scalar volume fusion through VolumeLayer, per-layer transfer functions, opacity, visibility, and source-over/additive blend modes.
• Adds volume layer compositing in Metal.
• Adds labelmap and surface overlay contracts that share the same coordinate model as the base volume.
• Keeps registration and resampling outside v1: layered volumes must already be aligned into the base volume texture space.

MTKUI application layer

• Adds public viewport/session types such as StackViewport, VolumeViewport, VolumeViewport3D, ClinicalViewportSession, and the clinical viewport grid.
• Adds MetalViewportSurface, MetalViewportView, and MetalViewportContainer as the official drawable-backed presentation surface.
• Adds VolumeViewportController, MPR support, rendering support, camera support, and state publishing.
• Adds clinical grid configuration, crosshair, picking, diagnostics, rendering, and resource-stress coverage.
• Adds overlays for crosshair, orientation, slab thickness, snapshot export, window/level, and HUD-style telemetry.
• Adds native 3D interaction handling with orbit state, gesture configuration, pan/zoom/roll behavior, and SwiftUI integration.

Performance, diagnostics, and resource management

• Adds chunked volume upload and HU conversion pipelines for private Metal textures.
• Adds MPS empty-space acceleration with explicit success/unavailable/failure reporting.
• Adds Metal histogram, gradient histogram, and statistics calculators.
• Adds GPU resource metrics, command buffer profiling, clinical benchmark reports, CSV export, snapshot metrics, and profiling sessions.
• Adds output texture factories and reusable output texture pools to avoid unnecessary interactive readback and allocation churn.
• Adds source-policy tests around avoiding CGImage-backed interactive paths.

Fixtures, examples, and documentation

• Adds MTKFixtures with synthetic fixture generation instead of shipping large raw fixture archives in the package product.
• Adds example code for basic volume rendering, DICOM loading, MPR viewer, triplanar MPR, synchronized MPR grids, and transfer-function customization.
• Adds DocC documentation for MTKCore and MTKUI, including getting started, volume rendering, MPR, DICOM integration, transfer functions, volume pipeline, and storage-mode policy guides.
• Adds architecture documentation for the public API, clinical rendering decision, and multi-volume registration roadmap.
• Adds shader tooling for manual metallib rebuilds.

Tests and validation

• Adds broad unit and integration coverage for rendering adapters, MPR, presentation, transfer functions, geometry, picking, upload, statistics, volume layers, output texture management, fixtures, DICOM bridge packaging, and MTKUI contracts.
• Validation used for this release:
  • swift test --filter MTKDicomBridgeTests
  • Result: 3 tests executed, 0 failures.

Requirements and limitations

• Requires Swift 5.10 and Xcode 16.
• Supports iOS 17+ and macOS 14+.
• Requires a Metal-capable device for rendering. GPU-dependent tests skip when Metal is unavailable.
• MPS acceleration is optional and feature-specific; the baseline renderer is pure Metal ray marching.
• MTK is a rendering and UI toolkit for research, education, and prototype applications. It is not clinical validation or regulatory clearance.
• Multi-volume fusion assumes pre-registered inputs; registration and resampling are not included in this release.