# python-orthanc-tools
A set of python tools to ease Orthanc scripting.
Functionalities are very limited now ! Backward compat will break a lot in the near future !
## Installation
```shell
pip3 install orthanc-tools
```
## cloning an Orthanc to another
The cloners copies everything that is currently in the source Orthanc into the destination Orthanc and,
once this is done continues the cloning process for every DICOM instance that is received by the source.
from a python script:
```python
from orthanc_tools import OrthancCloner, ClonerMode
from orthanc_api_client import OrthancApiClient
orthanc_a = OrthancApiClient('http://localhost:8042', user='orthanc', pwd='orthanc')
orthanc_b = OrthancApiClient('http://localhost:8043', user='orthanc', pwd='orthanc')
cloner = OrthancCloner(source=orthanc_a, destination=orthanc_b)
cloner.execute(existing_changes_only=False)
# if the destination is declared as a peer:
cloner = OrthancCloner(source=orthanc_a, destination_peer='orthanc-b', mode=ClonerMode.TRANSFER)
cloner.execute(existing_changes_only=False)
```
from a shell:
```shell
python3 -m orthanc_tools.orthanc_cloner --source_url=http://192.168.0.10:8042 --source_user=user --source_pwd=pwd --dest_url=http://192.168.0.10:8042 --dest_user=user --dest_pwd=pwd --run_only_at_night_and_weekend=true --night_start_hour=19 --night_end_hour=6
```
or, inside a docker-compose file:
```yaml
version: "3"
services:
orthanc-cloner:
image: orthancteam/python-orthanc-tools:0.6.0
volumes: ["orthanc-cloner:/status"]
environment:
RUN_ONLY_AT_NIGHT_AND_WEEKEND: "true"
NIGHT_START_HOUR: "15"
NIGHT_END_HOUR: "6"
SOURCE_URL: "http://orthanc-a:8042"
# SOURCE_USER: "user"
# SOURCE_PWD: "pwd"
DEST_URL: "http://orthanc-b:8042"
# DEST_USER: "user"
# DEST_PWD: "pwd"
MODE: "Default"
PERSIST_STATE_PATH: "/status/status.txt"
WORKERS_THREAD_COUNT: "6"
# VERBOSE_ENABLED: "true"
ERROR_FOLDER_PATH: "/status"
MAX_RETRIES: "3"
entrypoint: python -m orthanc_tools.orthanc_cloner
volumes:
orthanc-cloner:
```
### OrthancCloner performance
Here are a set of measures performed during a long transfer between 2 VMs running on Azure using OrthancCloner v 0.6.3.
The source Orthanc (v1.9.0) is running on a 4 vCPU VM with 16GB RAM. Postgresql is running on the same VM and DICOM files are stored on data disks are attached to the VM.
The destination Orthanc (v1.11.2) is running on a 4 vCPU VM with 16GB RAM. It is using a flexible managed Postgresql server and an object storage to store DICOM files.
| Cloner Mode | WorkersThreadCount | throughput [GB/h] | throughput [instances/h] |
|--------------------------------------------------|-------------------:|------------------:|-------------------------:|
| Default | 12 | 38 | ? |
| Default | 18 | 67 | 142.000 |
| Default | 24 | 66 | 160.000 |
| Transfer, Transfers.Threads=6, ConcurrentJobs=2 | 3 | 20 | ? |
| Transfer, Transfers.Threads=6, ConcurrentJobs=12 | 6 | 15 | ? |
## import files from a folder from a Docker container
```
$ docker exec -it xxxx bash
/# pip3 install orthanc-tools
/# python3 -m orthanc_tools.orthanc_folder_importer --folder=/import --url=http://localhost:8042 --user=test --password=test --skip_extensions=.cne,.bmp,.ini
```
## Implement a simple forwarder
The forwarder simply forwards the content of an Orthanc to another DICOM destination and then, deletes
the instances. This is usefull for, e.g. implementing an Inbox in front of a PACS that does some
`IngestTranscoding` and/or applies sanitization in a lua script or a python plugin.
from a shell:
```shell
python3 -m orthanc_tools.orthanc_forwarder --source_url=http://192.168.0.10:8042 --source_user=user --source_pwd=pwd --destination=target_modality_alias --trigger=StableStudy
```
## migrate DICOM Data from a modality to another
More info in the [PacsMigrator class](orthanc_tools/pacs_migrator.py)
```
$ docker exec -it xxxx bash
/# pip3 install orthanc-tools
/# python3 -m orthanc_tools.pacs_migrator --url=http://localhost:8042 --user=user --password=pwd --destination_modality=orthanc-debug --from_study_date=20000101 --to_study_date=20191231 --run_only_at_night_and_weekend --night_start_hour=18 --night_end_hour=6
```
## compare DICOM Data found in Orthanc and in a remote modality
Running in a Docker environment:
```
$ docker run -d --name comparator --network=mysetup_default python:3.9 bash -c "pip3 install orthanc-tools && python3 -u -m orthanc_tools.orthanc_comparator --level=Instance --url=http://pacs-2022:8042 --modality=pacs-2017 --from_study_date=20220201 --to_study_date=20220302 --transfer_missing_to_modality --ignore_missing_from_orthanc --run_only_at_night_and_weekend --night_start_hour=19 --night_end_hour=6"
```
## uploading a Test DB in Orthanc
The OrthancTestDbPopulator generates test images and uploads them in Orthanc.
All images have only 4 pixels and take a minimum amount of space on disk.
By default, the generator always generates the same data, use a different seed if you need variation.
From a shell:
```shell
python3 -m orthanc_tools.orthanc_test_db_populator --url=http://192.168.0.10:8042 --user=user --password=pwd --studies=5000 --seed=42
```
## purge old studies from an Orthanc
Allows to clean the Orthanc by deleting the oldest studies according to the labels applied on them.
With that sample, all studies with the LABEL1 and older than 6 weeks will be deleted
all studies with the LABEL2 and older than 12 weeks will be deleted.
```
LABEL1,6
LABEL2,12
```
The script will be executed every day at 2:30 (24 format!)
```shell
python3 -m orthanc_tools.orthanc_cleaner --url=http://localhost:8042 --user=orthanc --password=orthanc --execution_time=2:30 --labels_file_path=./tests/stimuli/labels.csv
```
## Deploy an HL7 server parsing ORM^O01 messages to create and store worklists files in a folder
```
hl7-server:
image: orthancteam/python-orthanc-tools:0.10.0
ports: ["2575:2575"]
volumes: ["/worklists:/worklists"]
restart: unless-stopped
entrypoint: ["python", "-m", "orthanc_tools.hl7_worklist_server_for_orthanc"]
```
Then, add this env var to Orthanc:
`ORTHANC__WORKLISTS__DATABASE: /var/lib/orthanc/worklists`
Raw data
{
"_id": null,
"home_page": "https://github.com/orthanc-team/python-orthanc-tools",
"name": "orthanc-tools",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "orthanc, dicom, rest api, hl7",
"author": "Orthanc Team",
"author_email": "info@orthanc.team",
"download_url": "https://files.pythonhosted.org/packages/12/1d/3b3671d07289ad8b4474d8d836f06fa9d477e5d8ae72833c78ea8bcb09c8/orthanc_tools-0.14.5.tar.gz",
"platform": null,
"description": "# python-orthanc-tools\n\nA set of python tools to ease Orthanc scripting.\n\nFunctionalities are very limited now ! Backward compat will break a lot in the near future !\n\n## Installation\n\n```shell\npip3 install orthanc-tools\n```\n\n\n## cloning an Orthanc to another\n\nThe cloners copies everything that is currently in the source Orthanc into the destination Orthanc and,\nonce this is done continues the cloning process for every DICOM instance that is received by the source.\n\nfrom a python script:\n\n```python\nfrom orthanc_tools import OrthancCloner, ClonerMode\nfrom orthanc_api_client import OrthancApiClient\n\northanc_a = OrthancApiClient('http://localhost:8042', user='orthanc', pwd='orthanc')\northanc_b = OrthancApiClient('http://localhost:8043', user='orthanc', pwd='orthanc')\n\ncloner = OrthancCloner(source=orthanc_a, destination=orthanc_b)\ncloner.execute(existing_changes_only=False)\n\n# if the destination is declared as a peer:\ncloner = OrthancCloner(source=orthanc_a, destination_peer='orthanc-b', mode=ClonerMode.TRANSFER)\ncloner.execute(existing_changes_only=False)\n\n```\n\nfrom a shell:\n\n```shell\npython3 -m orthanc_tools.orthanc_cloner --source_url=http://192.168.0.10:8042 --source_user=user --source_pwd=pwd --dest_url=http://192.168.0.10:8042 --dest_user=user --dest_pwd=pwd --run_only_at_night_and_weekend=true --night_start_hour=19 --night_end_hour=6\n```\n\nor, inside a docker-compose file:\n```yaml\nversion: \"3\"\nservices:\n orthanc-cloner:\n image: orthancteam/python-orthanc-tools:0.6.0\n volumes: [\"orthanc-cloner:/status\"]\n environment:\n RUN_ONLY_AT_NIGHT_AND_WEEKEND: \"true\"\n NIGHT_START_HOUR: \"15\"\n NIGHT_END_HOUR: \"6\"\n SOURCE_URL: \"http://orthanc-a:8042\"\n# SOURCE_USER: \"user\"\n# SOURCE_PWD: \"pwd\"\n DEST_URL: \"http://orthanc-b:8042\"\n# DEST_USER: \"user\"\n# DEST_PWD: \"pwd\"\n MODE: \"Default\"\n PERSIST_STATE_PATH: \"/status/status.txt\"\n WORKERS_THREAD_COUNT: \"6\"\n# VERBOSE_ENABLED: \"true\"\n ERROR_FOLDER_PATH: \"/status\"\n MAX_RETRIES: \"3\"\n entrypoint: python -m orthanc_tools.orthanc_cloner\nvolumes:\n orthanc-cloner: \n\n```\n\n### OrthancCloner performance\n\nHere are a set of measures performed during a long transfer between 2 VMs running on Azure using OrthancCloner v 0.6.3.\n\nThe source Orthanc (v1.9.0) is running on a 4 vCPU VM with 16GB RAM. Postgresql is running on the same VM and DICOM files are stored on data disks are attached to the VM.\n\nThe destination Orthanc (v1.11.2) is running on a 4 vCPU VM with 16GB RAM. It is using a flexible managed Postgresql server and an object storage to store DICOM files.\n\n| Cloner Mode | WorkersThreadCount | throughput [GB/h] | throughput [instances/h] |\n|--------------------------------------------------|-------------------:|------------------:|-------------------------:|\n| Default | 12 | 38 | ? |\n| Default | 18 | 67 | 142.000 |\n| Default | 24 | 66 | 160.000 |\n| Transfer, Transfers.Threads=6, ConcurrentJobs=2 | 3 | 20 | ? |\n| Transfer, Transfers.Threads=6, ConcurrentJobs=12 | 6 | 15 | ? | \n\n\n\n## import files from a folder from a Docker container\n\n```\n$ docker exec -it xxxx bash\n\n/# pip3 install orthanc-tools\n\n/# python3 -m orthanc_tools.orthanc_folder_importer --folder=/import --url=http://localhost:8042 --user=test --password=test --skip_extensions=.cne,.bmp,.ini\n\n```\n\n\n## Implement a simple forwarder\n\nThe forwarder simply forwards the content of an Orthanc to another DICOM destination and then, deletes\nthe instances. This is usefull for, e.g. implementing an Inbox in front of a PACS that does some\n`IngestTranscoding` and/or applies sanitization in a lua script or a python plugin.\n\nfrom a shell:\n\n```shell\npython3 -m orthanc_tools.orthanc_forwarder --source_url=http://192.168.0.10:8042 --source_user=user --source_pwd=pwd --destination=target_modality_alias --trigger=StableStudy\n```\n\n\n## migrate DICOM Data from a modality to another\n\nMore info in the [PacsMigrator class](orthanc_tools/pacs_migrator.py)\n```\n$ docker exec -it xxxx bash\n\n/# pip3 install orthanc-tools\n\n/# python3 -m orthanc_tools.pacs_migrator --url=http://localhost:8042 --user=user --password=pwd --destination_modality=orthanc-debug --from_study_date=20000101 --to_study_date=20191231 --run_only_at_night_and_weekend --night_start_hour=18 --night_end_hour=6\n\n```\n\n## compare DICOM Data found in Orthanc and in a remote modality\n\nRunning in a Docker environment:\n```\n$ docker run -d --name comparator --network=mysetup_default python:3.9 bash -c \"pip3 install orthanc-tools && python3 -u -m orthanc_tools.orthanc_comparator --level=Instance --url=http://pacs-2022:8042 --modality=pacs-2017 --from_study_date=20220201 --to_study_date=20220302 --transfer_missing_to_modality --ignore_missing_from_orthanc --run_only_at_night_and_weekend --night_start_hour=19 --night_end_hour=6\"\n\n```\n\n## uploading a Test DB in Orthanc \n\nThe OrthancTestDbPopulator generates test images and uploads them in Orthanc.\nAll images have only 4 pixels and take a minimum amount of space on disk. \nBy default, the generator always generates the same data, use a different seed if you need variation.\n\nFrom a shell:\n\n```shell\npython3 -m orthanc_tools.orthanc_test_db_populator --url=http://192.168.0.10:8042 --user=user --password=pwd --studies=5000 --seed=42\n```\n\n## purge old studies from an Orthanc\nAllows to clean the Orthanc by deleting the oldest studies according to the labels applied on them.\n\nWith that sample, all studies with the LABEL1 and older than 6 weeks will be deleted\nall studies with the LABEL2 and older than 12 weeks will be deleted.\n\n```\nLABEL1,6\nLABEL2,12\n```\nThe script will be executed every day at 2:30 (24 format!)\n\n```shell\npython3 -m orthanc_tools.orthanc_cleaner --url=http://localhost:8042 --user=orthanc --password=orthanc --execution_time=2:30 --labels_file_path=./tests/stimuli/labels.csv\n```\n\n## Deploy an HL7 server parsing ORM^O01 messages to create and store worklists files in a folder\n```\n hl7-server:\n image: orthancteam/python-orthanc-tools:0.10.0\n ports: [\"2575:2575\"]\n volumes: [\"/worklists:/worklists\"]\n restart: unless-stopped\n entrypoint: [\"python\", \"-m\", \"orthanc_tools.hl7_worklist_server_for_orthanc\"]\n```\nThen, add this env var to Orthanc:\n\n`ORTHANC__WORKLISTS__DATABASE: /var/lib/orthanc/worklists`\n",
"bugtrack_url": null,
"license": null,
"summary": "Python Orthanc Tools",
"version": "0.14.5",
"project_urls": {
"Bug Reports": "https://github.com/orthanc-team/python-orthanc-tools/issues",
"Funding": "https://orthanc.team",
"Homepage": "https://github.com/orthanc-team/python-orthanc-tools",
"Source": "https://github.com/orthanc-team/python-orthanc-tools/"
},
"split_keywords": [
"orthanc",
" dicom",
" rest api",
" hl7"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "23f99b8268b33e9807eb3ee8a2e54eb6d6ea7c9afdc3a2fde9f01035b2e43526",
"md5": "a89ae3515f9471761c4ff9833302ca82",
"sha256": "d109b09118686ff17623ba99c0f8c5a3c3e9ebded0b4392289ec291467792e9d"
},
"downloads": -1,
"filename": "orthanc_tools-0.14.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a89ae3515f9471761c4ff9833302ca82",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 187609,
"upload_time": "2025-01-06T14:29:18",
"upload_time_iso_8601": "2025-01-06T14:29:18.114065Z",
"url": "https://files.pythonhosted.org/packages/23/f9/9b8268b33e9807eb3ee8a2e54eb6d6ea7c9afdc3a2fde9f01035b2e43526/orthanc_tools-0.14.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "121d3b3671d07289ad8b4474d8d836f06fa9d477e5d8ae72833c78ea8bcb09c8",
"md5": "4e883726839591addf7b7365d6ff42fe",
"sha256": "5207063c1701815c811e68f0abac90b6f9c89a95086228a6813d0e6220bc2fef"
},
"downloads": -1,
"filename": "orthanc_tools-0.14.5.tar.gz",
"has_sig": false,
"md5_digest": "4e883726839591addf7b7365d6ff42fe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 185427,
"upload_time": "2025-01-06T14:29:22",
"upload_time_iso_8601": "2025-01-06T14:29:22.599904Z",
"url": "https://files.pythonhosted.org/packages/12/1d/3b3671d07289ad8b4474d8d836f06fa9d477e5d8ae72833c78ea8bcb09c8/orthanc_tools-0.14.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-06 14:29:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "orthanc-team",
"github_project": "python-orthanc-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "orthanc-api-client",
"specs": [
[
">=",
"0.16.0"
]
]
},
{
"name": "pydicom",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "hl7",
"specs": [
[
"==",
"0.4.2"
]
]
},
{
"name": "six",
"specs": []
},
{
"name": "schedule",
"specs": [
[
"==",
"1.2.0"
]
]
},
{
"name": "pika",
"specs": []
},
{
"name": "pathlib",
"specs": []
},
{
"name": "inquirer",
"specs": []
}
],
"tox": true,
"lcname": "orthanc-tools"
}
JSON
