Orthanc-Tools-Js

Documentation Guide

Salim Kanoun
[email protected]
I. Architecture

Orthanc Tools JS software is built on the top of Orthanc and extending its capabilities by:

- Providing a super user-friendly interface to perform complex DICOM operations

- Adding feature to Orthanc such as
o Role based access control
o Automation in Retrieve, Anonymization to perform batches of DICOM operations
o Integration of third party app such as viewers like OHIF or StoneOfOrthanc

Technically, OrthancToolsJS create a Restful API server on the top of Orthanc, this server extends Orthanc
capabilities of Orthanc by adding additional high level APIs for some features while it act as a simple reverse
proxy for other DICOM features that fully rely on Orthanc built’in features.

The built-in web Front end which is a React web app that can be accessed with any browser, the backend is
written on NodeJS/ExpressJS.

OrthancToolsJS licence is Affero General Public Licence v3. This license guarantees the free use of this software
for any purpose, without any restrictions (neither time nor number of installations).

Pay attention that according to the license terms

- No warranty are associated with the software

- Modification of the source code must be redistributed under the same license and this even if your changes
are for your own usage only.
- Software solutions that will be dependent of OrthancToolsJS are prone to be affected by this copyleft licence
and must also disclose its source code.

More information about licensing is available at https://www.fsf.org/

At this stage we do not provide offers of services for OrthancToolsJS, however if you have needs of support
service or need of a license exception feel free to contact the maintainer ([email protected])
II. Installation & upgrade

a. Installation
The only supported installation process is through Docker which now have a full support for Windows 10 in addition
to the historic Linux support.

The Docker Image name is hosted in DockerHub: salimkanoun/orthanctoolsjs:{version_name}

Orthanc Tools JS needs the following software in the environement

- HTTPS reverse proxy

o With a SSL certificate
o Add the X-Forwarded-For header for client ip logs
o Could be Nginx, Apache, Traefik …
- Redis
- Postgres database
- Orthanc (obviously)
o You can choose to install orthanc through Docker or as standalone app or even in a third party server
(All of this doesn’t matter as long as OrthancToolsJS can join Orthanc’s APIs)
o It’s recommended to install a database for Orthanc (which will be distinct from OrthancToolsJS
database)

A docker compose sample for deployment of Orthanc and OrthancToolsJs is available here:
https://github.com/salimkanoun/Orthanc-Tools-JS/blob/master/docker-compose.yml

The /data folder need to be mounted to a persistant volume (as it contain the sqlite database, storage for SSL
certificate for external upload etc…)

See the docker-compose to set the environment variable

To Benefit for AET/Peers declaration from OrthancToolsJS and to benefit for OHIF integration, edit the following
settings in orthanc JSON

- ORTHANC__DICOM_MODALITIES_IN_DATABASE: "true"
- ORTHANC__ORTHANC_PEERS_IN_DATABASE: "true"
- ORTHANC__DICOM_WEB__ENABLE: "true"
- ORTHANC__DICOM_WEB__ROOT: "/dicom-web/"
- ORTHANC__DICOM_WEB__ENABLEWADO: "true"
- ORTHANC__DICOM_WEB__WADOROOT: "/wado"
- ORTHANC__DICOM_WEB__STUDIESMETADATA: "MainDicomTags"
- ORTHANC__DICOM_WEB__SERIESMETADATA: "Full"
Italicized item are for OHIF integration

b. Upgrade
Until we will reach a stable version >1.0.0 the database schema will not be stable nor upgradable, so you will need
to wipe all previous install and do a fresh install (in practice, wipe the persistence storage of OrthancToolsJS)

To upgrade simply upgrade the container version.

 c. Other kind of installations
It would be theorically possible to run Orthanc Tools JS in Windows, Linux, MacOS without docker.

However we choose do to not support these install as it will rely on unofficial port of some component (such as
windows version of Redis).

If you have skills to package software for this OS you are more than welcome to contribute by building those
packages and / or writing documentation for these installs.
III. Login
Default Access :
Login : admin
Password : admin

IV. Orthanc Server declaration

By default the Orthanc server connexion settings is set to http://localhost:8042, with no login or password.
If you have a different Orthanc location or if you add login / password, go to Options -> General and fill the
form accordingly, click “update” to apply new connexion settings.
Press “test connexion” to check that your Orthanc server can be correctly reached
V. Main features

a. Orthanc Content
The Orthanc Content tab, allows you to search for resources in your Orthanc Server.

You can use the search form to search for specific queries (done at Study level).

The results appears in dynamic table, the left column displays the Patient / Study level, at a study click the right
column displays the series level.

At each Level an “Action” button gives you access to additional functionalities such as:

- Modify (Dicom Edition, all levels)

- Delete (all levels)
- View on OHIF (Study level)
- Metadata (Series level)
 b. Import Dicom files
To import local dicom in Orthanc Server, simply drag and drop the dicoms files and folder in the dropzone.

The import is recursive in all folders and non dicoms files will not break import.

c. Anonymize / Export / Delete

At the right upper corner of Orthanc Tools JS you will see three tools: Anonymize, Export, Delete.

These tools can be seen as “baskets” to perform the anonymzation, export or deletion action on a batch of
resources.

You can add ressources (patients, studies) from many other modules of Orthanc Tools JS using the “To Anon List”,
“To Export List”, “To Delete List” that you will find in several place of the software, allowing the dicom ressources to
jump from a tool to another.
 i. Anonymize

You can define a list of anonymisation, the anonymization is done at study level.

The GUI shows the patient level at the left table and study level in the right table.

The tables are editable to define, new patient name, patient ID, study description.

The Anonymization process follows the NEMA 2017c Guideline.

Two anonymization profiles are predefined in Orthanc Tools JS:

- Full Anonymization will follow the full Nema 2017c guideline

- Default Anonymization will keep body characteristics (weight, height…) and dates (acquisition date …)
this profile is recommended to anonymize nuclear medicine procedures (NM and PT).

Once done, a result table will be shown allowing pushing anonymized resources to Export / Delete tool.

ii. Export
The export is a list of resources that can be export to:

- A simple browser download with transcoding capabilities

- To an AET
- To an Orthanc Peer
- To a FTP/SFTP/WebDav server (not yet ready)
 iii. Delete
The deletion tool is a simple list a resource that will be deleted when the deletion process will be triggered.
 d. Query / Retrieve
Using a similar way to Orthanc Content you can do Query / Retrieve in your declared AETs.

The Study results are expandable to display related series.

e. Auto Retrieve
This feature allows you to make mass retrieve of DICOM from a PACS.

You can predefine a list of query to be done and retrieved and schedule it to be started outside working hour.

A robot will retrieve resources one by one to your Orthanc Server.

In the Query tab, define the list of queries you want to do:

- Click the “Add” button to open a new line and edit the wanted filed
- The table can be saved / imported using CSV file
By clicking the “Query” Button, the defined queries will be done and results shown in the “results” tab.

If you want to see series level click “filter series”, each query will be reprocessed at series level.

You can use the filters, search function of this table to search for your wanted resources. Remove all
unwanted results, using the “delete selected” button.

At the bottom of this table you can define a project name and click “Add to Robot” the resources listed in
the results table will be scheduled for automatic retrieve.
You retrieve robot is scheduled. It needs to be validated by the administration (see administration panel).

It will start at the time set by the administrator.

Once retrieved the resources status will be marked “Retrieved” and you will be allowed to send retrieved resources
to the anonymization / export tools of Orthanc Tools JS
 f. CD Burner – Epson / Primera DiscProducers
This feature allows you to automatically trigger CD/DVD burning in commercial DiscProducers such as Epson (PP100,
PP100N…) or Primera (SE, SE-3, II, Pro…)

The software can send burning request at the study (1 study per CD/DVD) or Patient level (multiple Study of a
patient per CD/DVD). The burning request is automatically triggered when the dicom is stored in Orthanc (60
seconds after the last Dicom reception, see “StableAge” in Orthanc configuration if needed).

Along with Dicom files you can specify a viewer folder distribution to be associated with DICOM (such as Radiant for
instance), and you can specify your own label to be printed in the CD/DVD which can include tags such as
PatientName etc…

i. Setting up burning solution

To setup your burning solution, first go into the options tab and define:

- The Monitored Folder (Folder monitored by Epson or Primera application)

- The Viewer Folder containing viewer files to be included with Dicoms
- The Label File (see Epson/Primera template editor)
- The Transfer Syntax of Dicoms (if you want to burn a specific Dicom transfert syntax)
- The CD Burner Manufacturer (Epson or Primera)
- The monitoring Level (Study or Patient level)
- The Support Type (CD/DVD/Auto)
- If you want to automatically delete resources from Orthanc once sent to CD/Burner (to avoid infinity
usage of disk space in Orthanc Server)
For CD/DVD labels templates:
Use Epson / Primera software to generate your CD/DVD printing and save it (.tdd file for Epson, .std for Primera) you
can Include the following tags (for Epson) or their respective position (for Primera)

“{patientName}” - Position 1

“{patientId}” – Position 2

“{studyDate}” - Position 3

“{studyDescription}” – Position 4

“ {patientDOB}” – Position 5

“ {accessionNumber}” – Position 6

to automatically print their respective value in the label.

ii. Starting burning service

Go do “CD-Burner” main tab and Start CD Burner Service, each time Orthanc will recieve a Study / Patient, a burning
request will be triggered and will appear in the interface (the burning service will continue to run even if the browser
is closed)
VI. Administration of Orthanc-Tools-JS

a. User Access
Two kinds of user definitions can be used

- Local users defined in the local database

- Distant users defined in an Active Directory

For each user a Role needs to be defined.

You can create how many Roles you want in the Role panel, each role is attached with a set of permission for each
functionality of Orthanc-Tools-JS

In the “Local User” tab you can define your local user, declared in database
Last you can declare an Active Directory server, from with user will be granted access.

The Role definition is made by mapping the “Group Name” of the AD to one of your defined Role in Orthanc Tools JS.

In the case of an user identified in multiple LDAP groups having a OrthancToolsJS role correspondence, the union of
the permissions of these roles will be granted when the user sign in.

b. AET / Orthanc Peers Declaration

You can simply define / remove AET and Orthanc Peer in the Orthanc Server using the administration panel
 c. Orthanc Jobs / Plugins
This interface allows you to see Orthanc asynchronous Jobs (and pause / cancel / resubmit them)

The plugin page list the available plugin in the current orthanc installation

d. Auto Retrieve Robot

You can see robot request for automatic retrieve, asked by users.

The robot needs to be validated to be executed, during the validation, OrthancToolsJS will check that each query
request provide only 1 answer in the PACS (to avoid too general queries that could lead to infinite retrieve).

You can see the robot query details and modify it if needed. You can also erase a retrieve job.

Last you can define the schedule hour in which the retrieve procedure will start (the retrieve are sequential)