# HG changeset patch # User Sebastien Jodogne # Date 1568281110 -7200 # Node ID d96894c0c554861d343992279825d6deec1c1230 # Parent da9aed65d9f62128da96b5d5e5b0b4be7bcf7f09# Parent 234092ecf82ed56524bfb51458a2e4ad72e2d9cf merge diff -r da9aed65d9f6 -r d96894c0c554 .hgignore --- a/.hgignore Thu Sep 12 11:38:10 2019 +0200 +++ b/.hgignore Thu Sep 12 11:38:30 2019 +0200 @@ -1,3 +1,5 @@ +syntax: glob Sphinx/build Sphinx/env .vscode/ +*~ diff -r da9aed65d9f6 -r d96894c0c554 OpenAPI/orthanc-openapi.yaml --- a/OpenAPI/orthanc-openapi.yaml Thu Sep 12 11:38:10 2019 +0200 +++ b/OpenAPI/orthanc-openapi.yaml Thu Sep 12 11:38:30 2019 +0200 @@ -4,7 +4,7 @@ version: 1.0.0 description: >- One of the major strengths of Orthanc lies in its built-in RESTful API, that can be used to drive Orthanc from external applications, independently of the programming language that is used to develop these applications. The REST API of Orthanc gives a full programmatic access to all the core features of Orthanc. Importantly, Orthanc Explorer (the embedded administrative interface of Orthanc) entirely resorts to this REST API for all its features. This implies that anything that can be done through Orthanc Explorer, can also be done through REST queries.

- This documentation is work-in-progress: The entire REST API is not covered yet. Please contribute by improving the source code of the documenation: https://bitbucket.org/sjodogne/orthanc-book/src/default/ + This documentation is work-in-progress: The entire REST API is not covered yet. Please contribute by improving the source code of the documentation: https://bitbucket.org/sjodogne/orthanc-book/src/default/ servers: - url: 'https://demo.orthanc-server.com' components: diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/faq.rst --- a/Sphinx/source/faq.rst Thu Sep 12 11:38:10 2019 +0200 +++ b/Sphinx/source/faq.rst Thu Sep 12 11:38:30 2019 +0200 @@ -56,4 +56,5 @@ faq/orthanc-storage.rst faq/authentication.rst faq/crash.rst + faq/transcoding.rst faq/why-orthanc.rst diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/faq/authentication.rst --- a/Sphinx/source/faq/authentication.rst Thu Sep 12 11:38:10 2019 +0200 +++ b/Sphinx/source/faq/authentication.rst Thu Sep 12 11:38:30 2019 +0200 @@ -43,3 +43,5 @@ * Create a :ref:`new Web user interface ` on the top of the REST API of Orthanc, using your favorite framework (Meteor, AngularJS, Ember.js, Node.js...). +* Pass an :ref:`authorization token ` + in the url search params when opening the Orthanc Explorer. diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/faq/features.rst --- a/Sphinx/source/faq/features.rst Thu Sep 12 11:38:10 2019 +0200 +++ b/Sphinx/source/faq/features.rst Thu Sep 12 11:38:30 2019 +0200 @@ -38,9 +38,9 @@ time inside Orthanc can be automatically deleted when the disk space used by Orthanc grows above a threshold, or when the number of stored patients grows above a threshold. This feature enables the automated -control of the disk space dedicated to Orthanc. Note that pushing a -new study for an existing patient will not change its position in the -recycling order. +control of the disk space dedicated to Orthanc. Note that each time +a new instance is received for an existing patient, the patient will +be marked as the most recent one in the recycling order. Recycling is controlled by the ``MaximumStorageSize`` and the ``MaximumPatientCount`` options in the :ref:`Orthanc configuration diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/faq/transcoding.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/faq/transcoding.rst Thu Sep 12 11:38:30 2019 +0200 @@ -0,0 +1,133 @@ +.. _transcoding: + +Transcoding of DICOM files +========================== + +General information +------------------- + +As of release 1.5.7, Orthanc does not feature support for transcoding +DICOM instances yet. In other words, the Orthanc core never changes +the :ref:`transfer syntax ` of some DICOM instance +when it has to send it to another modality using the DICOM protocol. + +Adding support for transcoding is one of the features that is pending +on `our roadmap +`__, and for which +we are looking for industrial sponsors. + + +Motivation for transcoding +-------------------------- + +Let's consider the following basic workflow, in which some imaging +workstation must access a medical image that originates from a PACS +and that is served through an Orthanc proxy: + +.. image:: ../images/Transcoding1.svg + :align: center + :width: 700px + +This is quite a common situation, e.g. in university hospitals where +researchers must access medical images without having authorization to +log in the clinical PACS. It is also common if the main PACS restricts +the number of workstations that can directly be connected to it, or if +Orthanc acts as gateway through Internet. + +The problem is that the software running on workstations might not be +able to display some DICOM transfer syntaxes. This is especially true +in research software, that is often limited to uncompressed transfer +syntaxes. For instance, let's consider the following scenario where a +workstation wants to access an image from the PACS: + +.. image:: ../images/Transcoding2.svg + :align: center + :width: 700px + +A typical PACS system will decide, when requested to export an image +using DICOM C-Store, to compress the image in order to reduce the +network bandwidth and the storage requirements. Orthanc is fine with +it: As a vendor neutral archive, Orthanc can basically +receive/store/transmit any DICOM transfer syntax. Unfortunately, this +might not be the case of the target workstation, that is often limited +to some selected transfer syntaxes. As a consequence, the workstation +will complain about not being to read the DICOM file (in the situation +depicted above, because the PACS has decided to send the DICOM image +using the JPEG2k transfer syntax). + + +Solutions +--------- + +There are basically 4 solutions to this issue. The first one, as +stated above, would be to **implement transcoding in Orthanc**. Feel +free to `get in touch with us +`__ if you want to +sponsor this development. + +The second solution consists in making Orthanc **refuse to accept the +transfer syntaxes** that are not supported by the workstation. This +is depicted in the following diagram: + +.. image:: ../images/Transcoding3.svg + :align: center + :width: 700px + +.. highlight:: json + +If Orthanc tells the PACS that is doesn't accept, say, DICOM JPEG2k, +the source PACS will be aware of this, and will transcode the DICOM +file before it is sent to Orthanc. This is the role of the following +:ref:`configuration options ` that specifies which +transfer syntaxes are accepted by Orthanc:: + + { + "DeflatedTransferSyntaxAccepted" : true, + "JpegTransferSyntaxAccepted" : true, + "Jpeg2000TransferSyntaxAccepted" : true, + "JpegLosslessTransferSyntaxAccepted" : true, + "JpipTransferSyntaxAccepted" : true, + "Mpeg2TransferSyntaxAccepted" : true, + "RleTransferSyntaxAccepted" : true, + "UnknownSopClassAccepted" : false + } + +If all of those options are set to ``false``, Orthanc will only +receive uncompressed transfer syntaxes (obviously provided that the +source PACS supports DICOM transcoding). + +The third solution consists in **applying an external conversion +tool** to every DICOM image that is received by Orthanc. The standard +command-line tools ``gdcmconv`` from `GDCM +`__ or ``dcmconv`` +from `DCMTK `__ can be +used to change the transfer syntax of a given DICOM file. These tools +can be invoked from a :ref:`Lua script ` (check out +``OnStoredInstance()`` callback) or from an :ref:`Orthanc plugin +` (check out +``OrthancPluginRegisterOnStoredInstanceCallback()`` function). A +sample Lua script that converts every incoming DICOM file to the +JPEG2k transfer syntax is `part of the Orthanc sources +`__. + + +Finally, as a fourth solution, it is possible to **combine two Orthanc +servers**, the first one being configured to accept any transfer +syntax, and the second one being responsible to serve the DICOM files +after conversion to uncompressed transfer syntax (which should be +compatible with any workstation): + +.. image:: ../images/Transcoding4.svg + :align: center + :width: 700px + +In this solution, a plugin or an external script continuously monitors +the content of the first Orthanc server thanks to its :ref:`REST API +`. Whenever a DICOM instance is received by the first Orthanc, +the plugin/script uses external conversion tools to convert the +instance to an uncompressed transfer syntax, then forward it to a +second Orthanc server. In other words, the first Orthanc server acts +as a transient buffer for decompression. Contrarily to the third +solution, this solution has the advantage of better scalability (as +decompression implemented in a Lua callback blocks Orthanc as long as +the Lua script has not returned). diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/faq/video.rst --- a/Sphinx/source/faq/video.rst Thu Sep 12 11:38:10 2019 +0200 +++ b/Sphinx/source/faq/video.rst Thu Sep 12 11:38:30 2019 +0200 @@ -20,11 +20,13 @@ distinction is also discussed in :ref:`another FAQ entry `. -If you also want to **play** the videos, to the best of our knowledge, -there is currently no Orthanc plugin for H.264 or MPEG2 (though such a -plugin should be developed in the future). However, if your video is a -2D+t (cine) sequence, Orthanc can already display it inside a Web -browser by at least 2 different means: +If you also want to **play** the videos, the `Osimis WebViewer plugin +`__ is able to play +H.264 (MPEG4) videos and 2D+t (cine) sequences but not MPEG2 videos that +currently can not be played by Web browsers. + +If your video is a 2D+t (cine) sequence, Orthanc can also display it inside +a Web browser by at least 2 different means: 1. The built-in, administrative interface called :ref:`Orthanc Explorer ` is able to display the individual @@ -34,6 +36,6 @@ allow you to use the mouse scroll wheel to display the successive frames of the video. -To summarize, if your video is not encoded with MPEG2 or H264, OR if +To summarize, if your video is not encoded with MPEG2, OR if you do not need to play the video within a Web browser, Orthanc -actually supports video. +actually supports video if the Osimis Web viewer plugin is installed. diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/images/Transcoding1.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/images/Transcoding1.svg Thu Sep 12 11:38:30 2019 +0200 @@ -0,0 +1,219 @@ + + diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/images/Transcoding2.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/images/Transcoding2.svg Thu Sep 12 11:38:30 2019 +0200 @@ -0,0 +1,259 @@ + + diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/images/Transcoding3.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/images/Transcoding3.svg Thu Sep 12 11:38:30 2019 +0200 @@ -0,0 +1,279 @@ + + diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/images/Transcoding4.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/images/Transcoding4.svg Thu Sep 12 11:38:30 2019 +0200 @@ -0,0 +1,301 @@ + + diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/index.rst --- a/Sphinx/source/index.rst Thu Sep 12 11:38:10 2019 +0200 +++ b/Sphinx/source/index.rst Thu Sep 12 11:38:30 2019 +0200 @@ -1,3 +1,5 @@ +.. _orthanc-book: + Welcome to the Orthanc Book! ============================ diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/plugins/authorization.rst --- a/Sphinx/source/plugins/authorization.rst Thu Sep 12 11:38:10 2019 +0200 +++ b/Sphinx/source/plugins/authorization.rst Thu Sep 12 11:38:30 2019 +0200 @@ -310,4 +310,23 @@ service. Think for instance about an authorization mechanism that simply associates its studies to a set of granted users: In this case, the series and instance levels can be ignored. - + + +.. _orthanc-explorer-authorization: + +Integration with the Orthanc Explorer +------------------------------------- + +Starting from Orthanc 1.5.8, you can pass authorization tokens in the url +search params when opening the Orthanc explorer i.e. +http://localhost:8042/app/explorer.html?token=1234. This token will be +included as an HTTP header in every request sent to the Orthanc Rest API. +It will also be included in the url search params when opening the Orthanc +or Osimis viewer. + +Only 3 tokens name will be recognized and forwarded: ``token``, ``auth-token`` +and ``authorization``. + +Please note that the Orthanc Explorer has not been designed to handle +the authorization so, when an authorization is not granted, it will simply +display an empty page or an error message. diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/users/rest.rst --- a/Sphinx/source/users/rest.rst Thu Sep 12 11:38:10 2019 +0200 +++ b/Sphinx/source/users/rest.rst Thu Sep 12 11:38:30 2019 +0200 @@ -937,3 +937,5 @@ Web site `__ (click on the *Reference of the REST API* button). +* A documentation of the REST API in the OpenAPI/Swagger format is + `available as work-in-progress `__. diff -r da9aed65d9f6 -r d96894c0c554 Sphinx/source/users/support.rst --- a/Sphinx/source/users/support.rst Thu Sep 12 11:38:10 2019 +0200 +++ b/Sphinx/source/users/support.rst Thu Sep 12 11:38:30 2019 +0200 @@ -11,26 +11,29 @@ When you face a problem, you should first check out the following resources: -1. Make sure to :ref:`understand the basics of DICOM `. -2. Follow the :ref:`general troubleshooting guide `. -3. If the problem is related to the DICOM network protocol, follow +1. Make sure to :ref:`check all the content of the Orthanc Book + `, and notably to :ref:`understand the basics of + DICOM `. +2. Carefully read your :ref:`log files in verbose mode `. +3. Follow the :ref:`general troubleshooting guide `. +4. If the problem is related to the DICOM network protocol, follow the :ref:`DICOM troubleshooting guide `. -4. Have a look at **all** the :ref:`frequently asked questions (FAQs) +5. Have a look at **all** the :ref:`frequently asked questions (FAQs) ` that are already available in the Orthanc Book. -5. Make a search for similar problem previously discussed in the +6. Make a search for similar problem previously discussed in the `Orthanc Users discussion forum `__. -6. Check out the ``Pending changes in the mainline`` section of the +7. Check out the ``Pending changes in the mainline`` section of the `NEWS file `__, as your issue might already be solved in the mainline of Orthanc (i.e. in the cutting-edge version of Orthanc since the last stable official release). -7. Carefully read the `TODO file +8. Carefully read the `TODO file `__ that contains our roadmap, as you might be requesting a feature that is currently pending in our backlog (i.e. not implemented yet). -8. Have a look for the issue in the `official bug tracker +9. Have a look for the issue in the `official bug tracker `__ (click on the ``All`` button, as your issue might already been solved).