Skip to content

DISTRIBUTION.md

Latest commit

 

History

History
549 lines (412 loc) · 12.9 KB

DISTRIBUTION.md

File metadata and controls

549 lines (412 loc) · 12.9 KB

Distribution and Deployment Guide

This document provides comprehensive guidance for distributing and deploying DICOMKit components.

Table of Contents

  1. Package Distribution
  2. CLI Tools Distribution
  3. Demo Applications
  4. Docker Deployment
  5. Integration Examples

Package Distribution

Swift Package Manager (Primary Method)

DICOMKit is distributed as a Swift Package, making it easy to integrate into Swift projects.

Adding as a Dependency

In your Package.swift:

dependencies: [
    .package(url: "https://github.com/Raster-Lab/DICOMKit.git", from: "1.0.0")
]

Then add the specific modules you need to your targets:

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "DICOMKit", package: "DICOMKit"),      // High-level API
        .product(name: "DICOMCore", package: "DICOMKit"),     // Core parsing
        .product(name: "DICOMNetwork", package: "DICOMKit"),  // PACS networking
        .product(name: "DICOMWeb", package: "DICOMKit"),      // DICOMweb services
    ]
)

In Xcode Projects

  1. File → Add Package Dependencies...
  2. Enter: https://github.com/Raster-Lab/DICOMKit.git
  3. Select version: "1.0.0" (or "Up to Next Major")
  4. Choose the modules you need: DICOMKit, DICOMCore, DICOMNetwork, DICOMWeb

CLI Tools Distribution

DICOMKit includes 35 command-line tools for working with DICOM files. Multiple distribution methods are available:

Method 1: Homebrew with Local Formula (Recommended for macOS Users)

The easiest installation method for macOS users:

# Clone the repository
git clone https://github.com/Raster-Lab/DICOMKit.git
cd DICOMKit

# Install using local formula (builds from source)
brew install --build-from-source Formula/dicomkit.rb

Using a Homebrew Tap (Optional)

If you have set up a dedicated Homebrew tap repository (see HOMEBREW_TAP_SETUP.md):

# Add the DICOMKit tap (requires separate repository)
brew tap Raster-Lab/dicomkit
brew install dicomkit

Note: The brew tap command requires a separate GitHub repository named homebrew-dicomkit to exist at https://github.com/Raster-Lab/homebrew-dicomkit. See the tap setup guide for instructions on creating this repository.

Method 2: Direct Download from GitHub Releases

Pre-built binaries are available from GitHub Releases:

  1. Go to https://github.com/Raster-Lab/DICOMKit/releases
  2. Download dicomkit-cli-tools-v1.0.0-macos-arm64.tar.gz
  3. Extract and install:
tar -xzf dicomkit-cli-tools-v1.0.0-macos-arm64.tar.gz
sudo cp bin/dicom-* /usr/local/bin/

Method 3: Build from Source

See INSTALLATION.md for detailed instructions.

git clone https://github.com/Raster-Lab/DICOMKit.git
cd DICOMKit
./Scripts/install-cli-tools.sh

Tool Categories

Phase 1 - Core Tools (7 tools):

  • dicom-info - Display DICOM metadata
  • dicom-convert - Convert transfer syntaxes and export images
  • dicom-validate - Validate DICOM conformance
  • dicom-anon - Anonymize patient information
  • dicom-dump - Hexadecimal inspection
  • dicom-query - Query PACS servers
  • dicom-send - Send files to PACS

Phase 2 - Enhanced Workflow (4 tools):

  • dicom-diff - Compare DICOM files
  • dicom-retrieve - Retrieve from PACS (C-MOVE/C-GET)
  • dicom-split - Extract frames from multi-frame images
  • dicom-merge - Create multi-frame images

Phase 3 - Format Conversion (4 tools):

  • dicom-json - Convert to/from DICOM JSON
  • dicom-xml - Convert to/from DICOM XML
  • dicom-pdf - Handle encapsulated PDF/CDA documents
  • dicom-image - Convert images to DICOM Secondary Capture

Phase 4 - Archive Management (3 tools):

  • dicom-dcmdir - Create and manage DICOMDIR files
  • dicom-archive - Local DICOM archive with indexing
  • dicom-export - Advanced export with metadata embedding

Phase 5 - Network & Workflow (5 tools):

  • dicom-qr - Integrated query-retrieve workflow
  • dicom-wado - DICOMweb client (WADO-RS, QIDO-RS, STOW-RS)
  • dicom-echo - Network diagnostics (C-ECHO)
  • dicom-mwl - Modality Worklist queries
  • dicom-mpps - Modality Performed Procedure Step

Phase 6 - Advanced Utilities (6 tools):

  • dicom-pixedit - Pixel data manipulation
  • dicom-tags - Tag manipulation utilities
  • dicom-uid - UID generation and management
  • dicom-compress - Compression/decompression
  • dicom-study - Study/Series organization
  • dicom-script - Workflow automation scripting

DICOM Studio Distribution

DICOM Studio is a native macOS application for viewing, analyzing, and managing DICOM medical imaging files. Multiple installer formats are available.

Method 1: DMG Installer (Recommended)

Download the DMG from GitHub Releases and drag DICOM Studio to your Applications folder:

  1. Go to https://github.com/Raster-Lab/DICOMKit/releases
  2. Download DICOMStudio-<version>.dmg
  3. Open the DMG and drag DICOMStudio.app to the Applications folder

Or build the DMG locally:

git clone https://github.com/Raster-Lab/DICOMKit.git
cd DICOMKit
./Scripts/package-dicom-studio-dmg.sh --version 1.0.16

Optional code signing and notarization:

./Scripts/package-dicom-studio-dmg.sh \
    --version 1.0.16 \
    --sign "Developer ID Application: Your Name (TEAM_ID)" \
    --notarize

Method 2: macOS .pkg Installer

The .pkg installer provides a guided installation experience:

  1. Go to https://github.com/Raster-Lab/DICOMKit/releases
  2. Download DICOMStudio-<version>.pkg
  3. Double-click to run the guided installer

Or build the .pkg locally:

git clone https://github.com/Raster-Lab/DICOMKit.git
cd DICOMKit
./Scripts/package-dicom-studio-pkg.sh --version 1.0.16

Optional signing and notarization:

./Scripts/package-dicom-studio-pkg.sh \
    --version 1.0.16 \
    --sign "Developer ID Installer: Your Name (TEAM_ID)" \
    --notarize

Method 3: Homebrew Cask

Install DICOM Studio via Homebrew using the local cask formula (requires cloning the repository):

git clone https://github.com/Raster-Lab/DICOMKit.git
cd DICOMKit
brew install --cask Formula/dicomstudio.rb

Or, if a Homebrew tap has been set up (see HOMEBREW_TAP_SETUP.md):

brew tap Raster-Lab/dicomkit
brew install --cask dicomstudio

To uninstall:

brew uninstall --cask dicomstudio

CI/CD Automated Releases

DICOM Studio releases are automated via the dicom-studio-release.yml GitHub Actions workflow. The workflow is triggered by pushing a tag matching studio-v*.*.*:

git tag studio-v1.0.16
git push origin studio-v1.0.16

This will:

  1. Validate the build and run DICOMStudio tests
  2. Build both DMG and .pkg installers
  3. Generate SHA-256 checksums
  4. Create a GitHub Release with all artifacts

Demo Applications

DICOMKit includes three fully-functional demo applications:

DICOMViewer iOS

Mobile DICOM viewer for iPhone and iPad.

Distribution Options:

  1. TestFlight (recommended for beta testing)
  2. App Store (for public distribution)
  3. Direct Installation (Xcode required)

Status: iOS viewer has been removed from the repository.

Status: macOS viewer has been removed from the repository.

Docker Deployment

Docker containers enable easy deployment of DICOMKit server components.

DICOMweb Server Container

Create a Dockerfile for the DICOMweb server:

FROM swift:6.2-jammy

WORKDIR /app

# Copy source code
COPY . .

# Build DICOMweb server
RUN swift build -c release --product DICOMWebServer

# Expose DICOMweb ports
EXPOSE 8080

# Run server
CMD [".build/release/DICOMWebServer"]

Build and run:

docker build -t dicomkit-server .
docker run -p 8080:8080 dicomkit-server

Docker Compose for Full Stack

docker-compose.yml example:

version: '3.8'

services:
  dicomweb-server:
    build: .
    ports:
      - "8080:8080"
    environment:
      - DICOM_STORAGE_PATH=/data/dicom
      - LOG_LEVEL=info
    volumes:
      - dicom-data:/data/dicom
    restart: unless-stopped

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: dicomkit
      POSTGRES_USER: dicom
      POSTGRES_PASSWORD: changeme
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  dicom-data:
  postgres-data:

Start the stack:

docker-compose up -d

Kubernetes Deployment

Example Kubernetes deployment (k8s/deployment.yaml):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: dicomkit-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: dicomkit-server
  template:
    metadata:
      labels:
        app: dicomkit-server
    spec:
      containers:
      - name: dicomkit
        image: dicomkit-server:latest
        ports:
        - containerPort: 8080
        env:
        - name: LOG_LEVEL
          value: "info"
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "2Gi"
            cpu: "2000m"
---
apiVersion: v1
kind: Service
metadata:
  name: dicomkit-service
spec:
  selector:
    app: dicomkit-server
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
  type: LoadBalancer

Deploy:

kubectl apply -f k8s/deployment.yaml

Integration Examples

Example 1: Swift iOS App Integration

import SwiftUI
import DICOMKit

struct DICOMReaderView: View {
    @State private var dicomFile: DICOMFile?
    @State private var patientName: String = ""
    
    var body: some View {
        VStack {
            Button("Open DICOM File") {
                openDICOMFile()
            }
            
            if let file = dicomFile {
                Text("Patient: \(patientName)")
                    .font(.headline)
            }
        }
    }
    
    func openDICOMFile() {
        // File picker logic here
        if let url = selectedFileURL {
            do {
                dicomFile = try DICOMFile(fileURL: url)
                patientName = dicomFile?.dataSet.string(for: .patientName) ?? "Unknown"
            } catch {
                print("Error reading DICOM file: \(error)")
            }
        }
    }
}

Example 2: Command-Line Tool Integration

#!/bin/bash
# Batch anonymization script

INPUT_DIR="/path/to/dicom/input"
OUTPUT_DIR="/path/to/dicom/output"

# Anonymize all DICOM files
for file in "$INPUT_DIR"/*.dcm; do
    basename=$(basename "$file")
    dicom-anon \
        --input "$file" \
        --output "$OUTPUT_DIR/$basename" \
        --patient-name "Anonymous" \
        --patient-id "ANON$(date +%s)"
done

echo "Anonymization complete: $(ls -1 $OUTPUT_DIR | wc -l) files"

Example 3: DICOMweb Client Integration

import DICOMWeb

let client = DICOMwebClient(baseURL: URL(string: "https://dicom.example.com")!)

// Query for studies
let studies = try await client.searchStudies(
    patientName: "Doe^John",
    studyDate: "20240101-20241231"
)

// Retrieve a study
for study in studies {
    let instances = try await client.retrieveStudy(
        studyUID: study.studyInstanceUID
    )
    print("Retrieved \(instances.count) instances")
}

Example 4: PACS Integration

import DICOMNetwork

// Configure PACS connection
let config = AssociationConfiguration(
    callingAE: "MY_APP",
    calledAE: "PACS_SCP",
    host: "pacs.hospital.org",
    port: 11112
)

// Query for patients
let queryService = QueryService(configuration: config)
let results = try await queryService.findPatients(
    patientName: "Smith*",
    patientID: nil
)

// Retrieve studies
let retrieveService = RetrieveService(configuration: config)
for result in results {
    try await retrieveService.moveStudy(
        studyUID: result.studyInstanceUID,
        destinationAE: "MY_STORAGE"
    )
}

Deployment Checklist

Pre-Deployment

  • All tests pass (swift test)
  • Code builds without warnings (swift build -c release)
  • Security scan clean (CodeQL)
  • Documentation up to date
  • Version numbers updated
  • CHANGELOG.md updated

Distribution

  • GitHub release created
  • Release notes written
  • Binaries built and uploaded
  • Checksums generated
  • Homebrew formula updated
  • Documentation deployed

Post-Deployment

  • Installation verified on clean system
  • CLI tools work correctly
  • Package Manager integration tested
  • User documentation verified
  • Announcement posted (if applicable)

Support and Resources

Last Updated: February 2026
Version: 1.0.0