PyOrthanc is a comprehensive Python client for Orthanc, providing:
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.
Another project python-orthanc-api-client
from orthanc-team is quite similar to pyorthanc.
If you are wondering which one to use, please refer to this discussion.
pip install pyorthanc # Basic installation
pip install pyorthanc[all] # Install all optional dependencies
Assuming an Orthanc server running locally at http://localhost:8042:
from pyorthanc import Orthanc, upload
# 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
upload(client, 'image_path.dcm')
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'})
from pyorthanc import find_patients, find_studies, find_series, find_instances
# 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...
# Note the existing function to query Orthanc
find_studies(client, query={...})
find_series(client, query={...})
find_instances(client, query={...})
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)
Typical example can be found in these notebooks.
The Orthanc and AsyncOrthanc classes are generated from https://orthanc.uclouvain.be/api/.
Compatibility of versions between PyOrthanc and the Orthanc REST API are the following. Note that recent PyOrthanc versions will likely support older Orthanc version.
| PyOrthanc version | Generated from |
|---|---|
| >= 1.20.0 | Orthanc API 1.12.6 with Python Plugin 4.2 |
| 1.19.0, 1.19.1 | Orthanc API 1.12.5 with Python Plugin 4.2 |
| 1.18.0 | Orthanc API 1.12.4 with Python Plugin 4.2 |
| 1.17.0 | Orthanc API 1.12.3 with Python Plugin 4.2 |
| 1.13.2 to 1.16.1 | Orthanc API 1.12.1 with Python Plugin 4.1 |
| 1.13.0, 1.13.1 | Orthanc API 1.12.1 with Python Plugin 4.0 |
| 1.12.* | Orthanc API 1.12.1 |
| 1.11.* | Orthanc API 1.11.3 |
| 0.2.* | Provided Google sheet from Orthanc maintainer |
The tests are run in a docker image launched with docker compose.
docker compose run test
This command starts 3 containers :
orthanc1) on which the PyOrthanc client is connectedorthanc2) which acts as a modality connected to orthanc1FAQs
Orthanc REST API python wrapper with additional utilities
We found that pyorthanc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Browserslist-rs now uses static data to reduce binary size by over 1MB, improving memory use and performance for Rust-based frontend tools.
Research
Security News
Eight new malicious Firefox extensions impersonate games, steal OAuth tokens, hijack sessions, and exploit browser permissions to spy on users.
Security News
The official Go SDK for the Model Context Protocol is in development, with a stable, production-ready release expected by August 2025.