Skip to content

PyOrthanc

PyOrthanc is a Python client for the Orthanc REST API. It provides:

  • Complete wrapping of the Orthanc REST API methods
  • High-level utilities for common DICOM operations
  • Asynchronous client support
  • Helper functions for working with DICOM data
  • Integration with the Orthanc Python plugin

Why PyOrthanc?

PyOrthanc makes it easy to work with DICOM medical images stored on Orthanc servers using Python - instead of dealing with the DICOM protocol directly or creating complex code to interact with Orthanc's REST API.

Researchers and clinicians can make simple Python script to access and manage their medical imaging data.

Advanced users can use PyOrthanc to make Orthanc query a hospital PACS (Picture Archiving and Communication System). This allows to find and retrieve images produced in the clinic for research or quality control purposes. Additionally, since PyOrthanc simplifies Orthanc's anonymization operations, an entire medical image management workflow can be implemented in Python.

Quick Install

pip install pyorthanc        # Basic installation
pip install pyorthanc[all]   # Install all optional dependencies (progr)

Basic Usage

from pyorthanc import Orthanc

# Connect to Orthanc server
client = Orthanc('http://localhost:8042')
# Or with authentication:
client = Orthanc('http://localhost:8042', username='orthanc', password='orthanc')

# Basic operations
patient_ids = client.get_patients()
studies = client.get_studies() 

# Upload DICOM file
with open('image.dcm', 'rb') as f:
    client.post_instances(f.read())

Working with DICOM Modalities

from pyorthanc import Modality

# Create modality connection
modality = Modality(client, 'REMOTE_PACS')

# Test connection with C-ECHO
if modality.echo():
    print("Successfully connected to PACS")

# Query studies with C-FIND
response = modality.find({
    'Level': 'Study',
    'Query': {
        'PatientID': '12345*',
        'StudyDate': '20230101-20231231'
    }
})

# Matches (i.e. answers in Orthanc nomenclature) can be reviewed before retrieving results
response['answers']

# Retrieve results with C-MOVE to a target AET
modality.move(response['ID'], {'TargetAet': 'ORTHANC'})

Finding and Processing DICOM Data

from pyorthanc import find_patients

# Search for patients
patients = find_patients(
    client,
    query={'PatientName': '*Gabriel'},
    labels=['research']  # It is also possible to filter by labels
)

# Process patient data
for patient in patients:
    print(f"Patient: {patient.name} (ID: {patient.patient_id})")
    print(f"Birth Date: {patient.birth_date}")
    print(f"Labels: {patient.labels}")

    # Access studies
    for study in patient.studies:
        print(f"\nStudy Date: {study.date}")
        print(f"Description: {study.description}")

        # Access series
        for series in study.series:
            print(f"\nModality: {series.modality}")
            print(f"Series Description: {series.description}")

            # Access individual DICOM instances
            for instance in series.instances:
                # Convert to pydicom dataset
                ds = instance.get_pydicom()
                # Process DICOM data...

Using pyorthanc within Orthanc

Use the orthanc_sdk module when using Orthanc's Python plugin. orthanc_sdk acts as the same as orthanc, but it provides type hints and autocompletion. For example:

from pyorthanc import orthanc_sdk

# Register a new REST endpoint
def handle_api(output: orthanc_sdk.RestOutput, uri: str, **request):
    """Handle REST API request"""
    if request['method'] == 'GET':
        output.AnswerBuffer('Hello from plugin!', 'text/plain')
    else:
        output.SendMethodNotAllowed('GET')

orthanc_sdk.RegisterRestCallback('/hello-world', handle_api)

# Handle incoming DICOM
def on_store(dicom: orthanc_sdk.DicomInstance, instance_id: str):
    """Process stored DICOM instances"""
    print(f'Received instance {instance_id}')
    print(f'Size: {dicom.GetInstanceSize()} bytes')
    print(f'Transfer Syntax: {dicom.GetInstanceTransferSyntaxUid()}')

orthanc_sdk.RegisterOnStoredInstanceCallback(on_store)

Examples

Typical example can be found in these notebooks. - This notebook shows how a user can query image data from an Orthanc server - This notebook shows how a user can query and pull data from other modality (such as a CT scan or a PACS) connected to an Orthanc Server.

Cheat sheet

First steps

Getting started

Examples

Community guidelines

Releases

Contacts

Citation