Horos

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

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.