# python-orthanc-api-client
A python client to ease using the Orthanc Rest API.
Functionalities are very limited now ! Backward compat will break a lot in the near future !
Installation:
```shell
pip3 install orthanc-api-client
```
Examples:
```python
from orthanc_api_client import OrthancApiClient, ResourceType, InstancesSet
import datetime
orthanc_a = OrthancApiClient('http://localhost:8042', user='orthanc', pwd='orthanc')
orthanc_b = OrthancApiClient('http://localhost:8043', user='orthanc', pwd='orthanc')
if not orthanc_a.wait_started(timeout=20):
print("Orthanc has not started after 20 sec")
if not orthanc_a.is_alive():
print("Could not connect to Orthanc, check it is running")
# upload files/folders
orthanc_a.upload_folder('/home/o/files', ignore_errors=True)
instances_ids = orthanc_a.upload_file('/home/o/files/a.dcm')
instances_ids = orthanc_a.upload_file('/home/o/files/a.zip')
with open('/home/o/files/a.dcm', 'rb') as f:
instances_ids = orthanc_a.upload(f.read())
orthanc_a.upload_files_dicom_web(['/home/o/files/a.dcm'])
# list all resources ids
all_patients_ids = orthanc_a.patients.get_all_ids()
all_studies_ids = orthanc_a.studies.get_all_ids()
all_series_ids = orthanc_a.series.get_all_ids()
all_instances_ids = orthanc_a.instances.get_all_ids()
# show some daily stats
orthanc_a.studies.print_daily_stats(from_date=datetime.date(2022, 2, 4), to_date=datetime.date(2022, 2, 8))
orthanc_a.series.print_daily_stats() # show last 8 days per default
orthanc_a.instances.print_daily_stats()
# get system stats
print(f"This Orthanc stores {orthanc_a.get_statistics().studies_count} studies for a total of {orthanc_a.get_statistics().total_disk_size_mb} MB")
# instances methods
dicom_file = orthanc_a.instances.get_file(orthanc_id=all_instances_ids[0])
instances_ids = orthanc_b.upload(buffer=dicom_file)
study_id = orthanc_b.instances.get_parent_study_id(instances_ids[0])
# access study info & simplified tags
study = orthanc_b.studies.get(study_id)
patient_id = study.patient_main_dicom_tags.get('PatientID')
study_description = study.main_dicom_tags.get('StudyDescription')
dicom_id = study.dicom_id
# get the ids of all the studies of a patient
studies = orthanc_a.patients.get_studies_ids(patient_id)
# access metadata
orthanc_a.instances.set_string_metadata(orthanc_id=all_instances_ids[0],
metadata_name=1024,
content='my-value')
# access tags
tags = orthanc_a.instances.get_tags(orhtanc_id=all_instances_ids[0])
patient_name = tags['PatientName']
patient_id = tags['0010,0020']
patient_sex = tags['0010-0040']
# anonymize
anon_study_id = orthanc_b.studies.anonymize(
orthanc_id=study_id,
keep_tags=['PatientName'],
replace_tags={
'PatientID': 'ANON'
},
force=True,
delete_original=False
)
# find locally in Orthanc
study_id = orthanc_a.studies.lookup(dicom_id='1.2.3.4')
study_id = orthanc_a.studies.lookup(dicom_id='1.2.3.4', filter="Study")
studies = orthanc_a.studies.find(query={
'PatientName': 'A*',
'StudyDate': '20220101-20220109'
})
# find in a remote modality
remote_studies = orthanc_a.modalities.query_studies(
from_modality='pacs',
query={'PatientName': 'A*', 'StudyDate': '20220101-20220109'}
)
orthanc_a.modalities.retrieve_study(
from_modality=remote_studies[0].remote_modality_id,
dicom_id=remote_studies[0].dicom_id
)
# send to a remote modality
orthanc_a.modalities.send(
modality='orthanc-b',
resources_ids=[study_id],
synchronous=True
)
# send to a remote peer (synchronous)
orthanc_a.peers.send(
target_peer='orthanc-b',
resources_ids=[study_id]
)
# send using transfer plugin
orthanc_a.transfers.send(
target_peer='orthanc-b',
resources_ids=[study_id],
resource_type=ResourceType.STUDY,
compress=True
)
# work with a snapshot of a study
instances_set = InstancesSet.from_study(orthanc_a, study_id=study_id)
modified_set = instances_set.modify(
replace_tags={
'InstitutionName' : 'MY'
},
keep_tags=['SOPInstanceUID', 'SeriesInstanceUID', 'StudyInstanceUID'],
force=True,
keep_source=True # we are not changing orthanc IDs -> don't delete source since it is the same as destination
)
# send instance_set
orthanc_a.transfers.send(
target_peer='orthanc-b',
resources_ids=modified_set.instances_ids,
resource_type=ResourceType.STUDY,
compress=True
)
# delete after send
modified_set.delete()
```
## helpers methods
```python
import datetime
from orthanc_api_client import helpers, OrthancApiClient
dicom_date = helpers.to_dicom_date(datetime.date.today())
standard_date = helpers.from_dicom_date(dicom_date)
# for tests:
o = OrthancApiClient('http://localhost:8042', user='orthanc', pwd='orthanc')
helpers.wait_until(lambda: len(o.instances.get_all_ids() > 50), timeout=30)
dicom_date = helpers.get_random_dicom_date(date_from=datetime.date(2000, 1, 1),
date_to=datetime.date.today())
dicom_file = helpers.generate_test_dicom_file(width=128,
height=128,
tags={
"PatientName": "Toto",
"StudyInstanceUID": "123"
})
```
## upload a folder to Orthanc
```python
from orthanc_api_client import OrthancApiClient
o = OrthancApiClient('http://localhost:8042', user='orthanc', pwd='orthanc')
o.upload_folder('/home/o/files', ignore_errors=True)
```
## running from inside an Orthanc python plugin
```python
from orthanc_api_client import OrthancApiClient
import orthanc
import json
orthanc_client = None
def OnChange(changeType, level, resource):
global orthanc_client
if changeType == orthanc.ChangeType.ORTHANC_STARTED:
orthanc.LogWarning("Starting python plugin")
# at startup, use the python SDK direct access to the Rest API to retrieve info to pass to the OrthancApiClient that is using 'requests'
system = json.loads(orthanc.RestApiGet('/system'))
api_token = orthanc.GenerateRestApiAuthorizationToken()
orthanc_client = OrthancApiClient(
orthanc_root_url=f"http://localhost:{system['HttpPort']}",
api_token=api_token
)
...
orthanc.RegisterOnChangeCallback(OnChange)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/orthanc-team/python-orthanc-api-client",
"name": "orthanc-api-client",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "orthanc, dicom, rest api",
"author": "Orthanc Team",
"author_email": "info@orthanc.team",
"download_url": "https://files.pythonhosted.org/packages/f2/a5/79a96699b6b8de560bf2b481a674bd4bdce7dcc1088ee9318f482dfbcf62/orthanc_api_client-0.15.1.tar.gz",
"platform": null,
"description": "# python-orthanc-api-client\n\nA python client to ease using the Orthanc Rest API.\n\nFunctionalities are very limited now ! Backward compat will break a lot in the near future !\n\nInstallation:\n\n```shell\npip3 install orthanc-api-client\n```\n\n\nExamples:\n\n```python\nfrom orthanc_api_client import OrthancApiClient, ResourceType, InstancesSet\nimport datetime\n\northanc_a = OrthancApiClient('http://localhost:8042', user='orthanc', pwd='orthanc')\northanc_b = OrthancApiClient('http://localhost:8043', user='orthanc', pwd='orthanc')\n\nif not orthanc_a.wait_started(timeout=20):\n print(\"Orthanc has not started after 20 sec\")\n\nif not orthanc_a.is_alive():\n print(\"Could not connect to Orthanc, check it is running\")\n\n# upload files/folders\northanc_a.upload_folder('/home/o/files', ignore_errors=True)\ninstances_ids = orthanc_a.upload_file('/home/o/files/a.dcm')\ninstances_ids = orthanc_a.upload_file('/home/o/files/a.zip')\nwith open('/home/o/files/a.dcm', 'rb') as f:\n instances_ids = orthanc_a.upload(f.read())\northanc_a.upload_files_dicom_web(['/home/o/files/a.dcm'])\n \n# list all resources ids\nall_patients_ids = orthanc_a.patients.get_all_ids()\nall_studies_ids = orthanc_a.studies.get_all_ids()\nall_series_ids = orthanc_a.series.get_all_ids()\nall_instances_ids = orthanc_a.instances.get_all_ids()\n\n# show some daily stats\northanc_a.studies.print_daily_stats(from_date=datetime.date(2022, 2, 4), to_date=datetime.date(2022, 2, 8))\northanc_a.series.print_daily_stats() # show last 8 days per default\northanc_a.instances.print_daily_stats()\n\n# get system stats\nprint(f\"This Orthanc stores {orthanc_a.get_statistics().studies_count} studies for a total of {orthanc_a.get_statistics().total_disk_size_mb} MB\")\n\n# instances methods\ndicom_file = orthanc_a.instances.get_file(orthanc_id=all_instances_ids[0])\ninstances_ids = orthanc_b.upload(buffer=dicom_file)\nstudy_id = orthanc_b.instances.get_parent_study_id(instances_ids[0])\n\n# access study info & simplified tags\nstudy = orthanc_b.studies.get(study_id)\npatient_id = study.patient_main_dicom_tags.get('PatientID')\nstudy_description = study.main_dicom_tags.get('StudyDescription')\ndicom_id = study.dicom_id\n\n# get the ids of all the studies of a patient\nstudies = orthanc_a.patients.get_studies_ids(patient_id)\n\n# access metadata\northanc_a.instances.set_string_metadata(orthanc_id=all_instances_ids[0], \n metadata_name=1024, \n content='my-value')\n\n# access tags\ntags = orthanc_a.instances.get_tags(orhtanc_id=all_instances_ids[0])\npatient_name = tags['PatientName']\npatient_id = tags['0010,0020']\npatient_sex = tags['0010-0040']\n\n# anonymize\nanon_study_id = orthanc_b.studies.anonymize(\n orthanc_id=study_id,\n keep_tags=['PatientName'],\n replace_tags={\n 'PatientID': 'ANON'\n },\n force=True,\n delete_original=False\n)\n\n# find locally in Orthanc\nstudy_id = orthanc_a.studies.lookup(dicom_id='1.2.3.4')\nstudy_id = orthanc_a.studies.lookup(dicom_id='1.2.3.4', filter=\"Study\")\n\nstudies = orthanc_a.studies.find(query={\n 'PatientName': 'A*', \n 'StudyDate': '20220101-20220109'\n})\n\n# find in a remote modality\nremote_studies = orthanc_a.modalities.query_studies(\n from_modality='pacs',\n query={'PatientName': 'A*', 'StudyDate': '20220101-20220109'}\n)\northanc_a.modalities.retrieve_study(\n from_modality=remote_studies[0].remote_modality_id,\n dicom_id=remote_studies[0].dicom_id\n)\n\n# send to a remote modality\northanc_a.modalities.send(\n modality='orthanc-b',\n resources_ids=[study_id],\n synchronous=True\n)\n\n# send to a remote peer (synchronous)\northanc_a.peers.send(\n target_peer='orthanc-b',\n resources_ids=[study_id]\n)\n\n# send using transfer plugin\northanc_a.transfers.send(\n target_peer='orthanc-b',\n resources_ids=[study_id],\n resource_type=ResourceType.STUDY,\n compress=True\n)\n\n# work with a snapshot of a study\ninstances_set = InstancesSet.from_study(orthanc_a, study_id=study_id)\nmodified_set = instances_set.modify(\n replace_tags={\n 'InstitutionName' : 'MY'\n },\n keep_tags=['SOPInstanceUID', 'SeriesInstanceUID', 'StudyInstanceUID'],\n force=True,\n keep_source=True # we are not changing orthanc IDs -> don't delete source since it is the same as destination\n )\n\n# send instance_set\northanc_a.transfers.send( \n target_peer='orthanc-b',\n resources_ids=modified_set.instances_ids,\n resource_type=ResourceType.STUDY,\n compress=True\n)\n\n# delete after send\nmodified_set.delete()\n\n```\n\n## helpers methods\n\n```python\nimport datetime\nfrom orthanc_api_client import helpers, OrthancApiClient\n\ndicom_date = helpers.to_dicom_date(datetime.date.today())\nstandard_date = helpers.from_dicom_date(dicom_date)\n\n# for tests:\no = OrthancApiClient('http://localhost:8042', user='orthanc', pwd='orthanc')\nhelpers.wait_until(lambda: len(o.instances.get_all_ids() > 50), timeout=30)\n\ndicom_date = helpers.get_random_dicom_date(date_from=datetime.date(2000, 1, 1),\n date_to=datetime.date.today())\ndicom_file = helpers.generate_test_dicom_file(width=128,\n height=128,\n tags={\n \"PatientName\": \"Toto\",\n \"StudyInstanceUID\": \"123\"\n })\n\n```\n\n## upload a folder to Orthanc\n\n```python\nfrom orthanc_api_client import OrthancApiClient\n\no = OrthancApiClient('http://localhost:8042', user='orthanc', pwd='orthanc')\no.upload_folder('/home/o/files', ignore_errors=True)\n\n```\n\n## running from inside an Orthanc python plugin\n\n```python\nfrom orthanc_api_client import OrthancApiClient\nimport orthanc\nimport json\n\northanc_client = None\n\ndef OnChange(changeType, level, resource):\n global orthanc_client\n\n if changeType == orthanc.ChangeType.ORTHANC_STARTED:\n orthanc.LogWarning(\"Starting python plugin\")\n\n # at startup, use the python SDK direct access to the Rest API to retrieve info to pass to the OrthancApiClient that is using 'requests'\n system = json.loads(orthanc.RestApiGet('/system'))\n api_token = orthanc.GenerateRestApiAuthorizationToken()\n\n orthanc_client = OrthancApiClient(\n orthanc_root_url=f\"http://localhost:{system['HttpPort']}\",\n api_token=api_token\n )\n ...\n\northanc.RegisterOnChangeCallback(OnChange)\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Python Orthanc REST API client",
"version": "0.15.1",
"project_urls": {
"Bug Reports": "https://github.com/orthanc-team/python-orthanc-api-client/issues",
"Funding": "https://orthanc-team",
"Homepage": "https://github.com/orthanc-team/python-orthanc-api-client",
"Source": "https://github.com/orthanc-team/python-orthanc-api-client/"
},
"split_keywords": [
"orthanc",
" dicom",
" rest api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d6b42192fe50bd86a634a332bcf3a8801ac73ab4b999ce4900d3e6a7f598d36f",
"md5": "fa967e3556c94826304526621d34aba2",
"sha256": "a87f121625e9b8fb9613cfbf60f81c71f289614a6c9ee49d669b6e32a65957b2"
},
"downloads": -1,
"filename": "orthanc_api_client-0.15.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa967e3556c94826304526621d34aba2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 40381,
"upload_time": "2024-04-08T16:23:51",
"upload_time_iso_8601": "2024-04-08T16:23:51.002794Z",
"url": "https://files.pythonhosted.org/packages/d6/b4/2192fe50bd86a634a332bcf3a8801ac73ab4b999ce4900d3e6a7f598d36f/orthanc_api_client-0.15.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f2a579a96699b6b8de560bf2b481a674bd4bdce7dcc1088ee9318f482dfbcf62",
"md5": "d96ea3aac1d99f7c0bea73f27168a28d",
"sha256": "0c3f58965018ef1167dd042c13938feb753b4bccc479cfbe59811b4d8fe7d2f7"
},
"downloads": -1,
"filename": "orthanc_api_client-0.15.1.tar.gz",
"has_sig": false,
"md5_digest": "d96ea3aac1d99f7c0bea73f27168a28d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 44312,
"upload_time": "2024-04-08T16:23:53",
"upload_time_iso_8601": "2024-04-08T16:23:53.679647Z",
"url": "https://files.pythonhosted.org/packages/f2/a5/79a96699b6b8de560bf2b481a674bd4bdce7dcc1088ee9318f482dfbcf62/orthanc_api_client-0.15.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-08 16:23:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "orthanc-team",
"github_project": "python-orthanc-api-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "orthanc-api-client"
}
JSON
