Skip to content

Python library that wrap the Orthanc REST API and facilitate the manipulation of data in Orthanc

License

Notifications You must be signed in to change notification settings

gacou54/pyorthanc

Repository files navigation

ci documentation PyPI - Version PyPI - Downloads

PyOrthanc

PyOrthanc is a python client for the Orthanc REST API, which fully wraps all the methods of the REST API. Additionally, it provides many utility functions to interact with an Orthanc instance.

See the full documentation here https://gacou54.github.io/pyorthanc


Install PyOrthanc using pip:

pip install pyorthanc

Then use the client. If Orthanc is running locally, the default URL is http://localhost:8042.

import pyorthanc

client = pyorthanc.Orthanc('http://localhost:8042', username='orthanc', password='orthanc')
patient_ids = client.get_patients()

Interact with connected modalities

import pyorthanc

modality = pyorthanc.Modality(client, 'MY_MODALITY')
assert modality.echo()

# C-Find on modality
response = modality.query({'Level': 'Study', 'Query': {'PatientID': '*'}})

# C-Move to target modality
modality.move(response['ID'], {'TargetAet': 'target_modality'})

Find patients

patients = pyorthanc.find_patients(client, {'PatientID': '*P001'})
for patient in patients:
    patient.labels
    patient.is_stable
    patient.name
    ...
    for study in patient.studies:
        study.labels
        study.date
        ...
        for series in study.series:
            ...
            for instance in series.instances:
                pydicom_ds = instance.get_pydicom()

Resources (Patient, Study, Series, Instance) can be easily anonymized.

import pyorthanc

orthanc_patient_id = client.get_patients()[0]
patient = pyorthanc.Patient(orthanc_patient_id, client)

Waiting the for the anonymization process:

new_patient = patient.anonymize()
new_patient_with_given_patient_id = patient.anonymize(
   keep=['PatientName'],
   replace={'PatientID': 'TheNewPatientID'},
   force=True  # Needed when changing PatientID/StudyInstanceUID/SeriesInstanceUID/SOPInstanceUID
)

For long-running job (i.e. large patient) or to submit many anonymization jobs at the same time, use

job = patient.anonymize_as_job()
job.state  # You can follow the job state

job.wait_until_completion() # Or just wait on its completion
new_patient = pyorthanc.Patient(job.content['ID'], client)

Notes on versioning

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.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

You can still use the old client implementation with

from pyorthanc.deprecated.client import Orthanc  # Old client wrote by hand

Note that due to automatic generation some method names may be less clear. However, the automatic generation allows PyOrthanc to cover all the routes of the API of Orthanc.

Citation

If you publish using PyOrthanc, we kindly ask that you credit us. PyOrthanc can be found on Zenodo : https://zenodo.org/record/7086219 .

Credits

The orthanc_sdk.py has been generated from the scripts/data/python-sdk.txt file, which is from the Python Orthanc Plugin

Contributing

You can contribute to this project with the following steps:

  1. First, fork the project on Github
  2. Clone the project
    git clone https://github.com/<your-github-username>/pyorthanc
    cd pyorthanc
  3. Create a poetry environment (this project use the poetry for dependency management)
    peotry install 
  4. Make a new git branch where you will apply the changes
    git checkout -b your-branch-name
    Now you can make your changes
  5. Once done, git add, git commit and git push the changes.
  6. Make a Pull Request from your branch to the https://github.com/gacou54/pyorthanc.

Run tests

docker compose run --build test

About

Python library that wrap the Orthanc REST API and facilitate the manipulation of data in Orthanc

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages