horos

Configure Horos DICOM and PACS workflows, automate DCMTK transfers, and troubleshoot plugins without interpreting clinical findings.

SKILL.md

GitHub

Horos Open-Source DICOM Viewer AI Skill Guide (Claude)

Overview & Engine Architecture

Horos is a 64-bit open-source medical imaging and DICOM workstation for macOS, derived from the OsiriX foundation. Built with Objective-C and Cocoa, Horos integrates the DCMTK (DICOM ToolKit) networking stack, an embedded SQLite CoreData indexer, multi-planar reconstruction (MPR, MIP, MinIP, 3D Volume Rendering), and an extensible Plugin Architecture (PluginFilter). Horos acts as both a DICOM Storage Service Class Provider (C-STORE SCP Listener) and a Query/Retrieve Client (C-FIND / C-MOVE SCU). Claude operates as a Principal PACS Administrator and Medical Informatics Engineer, specializing in DICOM communication pipelines, Horos database index recovery, automated batch ingestion (pynetdicom), and XML-RPC / URL scheme integration.

Horos PACS & Visualization Architecture

┌─────────────────────────────────────────────────────────────┐
│                 Horos System Architecture                   │
│                                                             │
│  Presentation & Multi-Planar Visualization                  │
│  ├── 2D DICOM Viewport (Window/Level, ROIs, Cine Loop)      │
│  ├── 3D Post-Processing (MPR, Maximum Intensity Projection) │
│  └── 3D Surface / Volume Rendering & Endoscopy Navigation   │
│                                                             │
│  DICOM Networking & Protocol Layer (DCMTK)                  │
│  ├── C-STORE SCP Daemon (Background Ingestion Listener:11112│
│  ├── C-FIND & C-MOVE SCU (PACS Query & Retrieve Engine)     │
│  └── DICOM TLS 1.3 Secure Transfer Association              │
│                                                             │
│  Database & Indexing Core                                   │
│  ├── SQLite CoreData Index (`Horos Data/DATABASE.noindex/`) │
│  └── Objective-C Plugin SDK (`PluginFilter.h`) & XML-RPC IPC│
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

  1. DICOM Networking & PACS Automation: Author Python scripts using pynetdicom to verify DICOM connectivity (C-ECHO) and dispatch medical imaging series (C-STORE) to Horos listeners.
  2. Database Index & SQLite Triage: Repair and rebuild corrupted Horos database index structures (DATABASE.noindex) without losing patient image files.
  3. Automated Anonymization & HIPAA Compliance: Build automated workflows stripping protected health information (PHI) tags from DICOM headers before research exports.
  4. URL Scheme Integration: Trigger remote study retrieval and viewport loading via horos://openStudy?accession=....

Production Python Automation: Automated DICOM Dispatcher & Verification Client (pynetdicom)

Save this script as send_dicom_to_horos.py (requires pip install pydicom pynetdicom):

"""
DICOM C-STORE SCU Pipeline for Horos
Verifies C-ECHO availability and sends patient DICOM studies to the local Horos listener.
"""

import sys
import os
from pydicom import dcmread
from pynetdicom import AE, StoragePresentationContexts, VerificationPresentationContexts

HOROS_AE_TITLE = "HOROS"
HOROS_HOST = "127.0.0.1"
HOROS_PORT = 11112

def send_study_to_horos(dicom_dir: str):
    if not os.path.exists(dicom_dir):
        print(f"Error: Directory '{dicom_dir}' does not exist.")
        return

    # 1. Initialize Application Entity
    ae = AE(ae_title="PYTHON_DISPATCH")
    ae.requested_contexts = StoragePresentationContexts + VerificationPresentationContexts

    print(f"--- [CONNECTING TO HOROS DICOM LISTENER: {HOROS_HOST}:{HOROS_PORT}] ---")
    assoc = ae.associate(HOROS_HOST, HOROS_PORT, ae_title=HOROS_AE_TITLE)

    if not assoc.is_established:
        print("🚨 Error: Could not establish DICOM association. Is Horos running and DICOM listener active?")
        return

    # 2. Test Connection via C-ECHO (Ping)
    print("Testing connection with C-ECHO...")
    echo_status = assoc.send_c_echo()
    if echo_status and echo_status.Status == 0:
        print("✅ C-ECHO Verification Successful!")
    else:
        print("🚨 C-ECHO Verification Failed.")
        assoc.release()
        return

    # 3. Transmit All DICOM Files via C-STORE
    sent_count = 0
    for root, _, files in os.walk(dicom_dir):
        for f in files:
            file_path = os.path.join(root, f)
            try:
                ds = dcmread(file_path, stop_before_pixels=False)
                patient_name = ds.get("PatientName", "Anonymous")
                study_uid = ds.get("StudyInstanceUID", "Unknown")

                status = assoc.send_c_store(ds)
                if status and status.Status == 0:
                    sent_count += 1
                    print(f"  • Sent [#{sent_count}]: {f} (Patient: {patient_name})")
                else:
                    print(f"  🚨 Failed to store: {f} (Status: {status.Status if status else 'None'})")
            except Exception:
                continue # Skip non-DICOM files

    print(f"\n✅ Successfully transferred {sent_count} DICOM slice(s) to Horos database.")
    assoc.release()

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python3 send_dicom_to_horos.py <path_to_dicom_folder>")
        sys.exit(1)
    send_study_to_horos(sys.argv[1])

Technical Troubleshooting Matrix

Issue & Failure Signature Root Cause Analysis Diagnostic & Resolution Pathway
PACS C-MOVE Fails / No Images Transferred Hospital PACS firewall blocking inbound TCP port 11112 back to the Mac or mismatched AE Title. 1. In Horos Preferences $\rightarrow$ Listener, verify port (default 11112) and AE Title (HOROS).<br>2. Ensure macOS Firewall allows inbound connections to Horos.<br>3. Verify Horos AE Title and IP are registered in hospital PACS routing table.
Horos Freezes on Launch at Updating Database SQLite index DATABASE.noindex/HorosData.sqlite corrupted due to force-quitting. 1. Navigate to ~/Documents/Horos Data/DATABASE.noindex/.<br>2. Rename HorosData.sqlite to HorosData.sqlite.bak.<br>3. Launch Horos $\rightarrow$ Select File $\rightarrow$ Rebuild Database.
Application Crashes Opening Large 4D Cardiac CT Out of memory loading uncompressed cine frame volume series into system RAM. In Horos Preferences $\rightarrow$ Viewers, check Load images in 2D Viewer only when needed and enable frame caching.
Anonymization Leaves Private Patient Metadata Vendor-specific private tags (e.g. (0019, 1010)) not listed in standard HIPAA tag removal filter. In Anonymize dialog, check Remove all Private Tags and verify output in metadata viewer.

Command Line Syntax & macOS DCMTK Recipes

# 1. Test DICOM Echo Connectivity to Horos via DCMTK
echoscu -v -aet PYTHON_SCU -aec HOROS 127.0.0.1 11112

# 2. Open Specific Study in Horos via URL Scheme
open "horos://openStudy?accession=ACC987654"

# 3. Read Horos Preferences via defaults CLI
defaults read org.horosproject.horos

Essential File Locations

  • Horos Database Directory: ~/Documents/Horos Data/
  • Preferences Plist: ~/Library/Preferences/org.horosproject.horos.plist
  • Installed Plugins: ~/Library/Application Support/Horos/Plugins/

Agent Operational Directive

MANDATORY: Verify that the Horos C-STORE SCP listener is active on TCP port 11112 using echoscu before diagnosing PACS image retrieval and transfer failures.