Contents
This official plugin extends Orthanc with support of the DICOMweb protocols. More precisely, the plugin introduces a basic, reference implementation of WADO-URI, WADO-RS, QIDO-RS and STOW-RS, following DICOM PS3.18. The plugin simultaneously turns Orthanc into a DICOMweb server and into a DICOMweb client.
For general information, check out the official homepage of the plugins.
The full standard is not implemented yet, the supported features are tracked in the repository.
The procedure to compile this plugin is similar of that for the core of Orthanc. The following commands should work for most UNIX-like distribution (including GNU/Linux):
$ mkdir Build
$ cd Build
$ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
$ make
The compilation will produce a shared library OrthancDicomWeb
that
contains the DICOMweb plugin. Pre-compiled binaries for Microsoft
Windows are also available,
and are included in the Windows installers. A package
for Apple’s Mac OS X is
available courtesy of Osimis.
Remark: Some older build instructions are also available in the source distribution.
You of course first have to install Orthanc. Once
Orthanc is installed, you must change the configuration file to tell Orthanc where it can find the plugin: This is
done by properly modifying the Plugins
option. For GNU/Linux, you
could for instance use the following configuration file:
{
"Name" : "MyOrthanc",
[...]
"Plugins" : [
"/home/user/OrthancDicomWeb/Build/libOrthancDicomWeb.so"
]
}
Or, for Windows:
{
"Name" : "MyOrthanc",
[...]
"Plugins" : [
"c:/Temp/OrthancDicomWeb.dll"
]
}
Note that the DICOMweb server will share all the parameters of the Orthanc HTTP server, notably wrt. authentication and HTTPS encryption. For this reason, you will most probably have to enable the remote access to the Orthanc HTTP server:
{
[...]
"RemoteAccessEnabled" : true,
[...]
}
Once Orthanc has restarted, the root of the DICOMweb REST API is
accessible at http://localhost:8042/dicom-web/
.
The options StudiesMetadata
and SeriesMetadata
were introduced
in release 1.1 of the DICOMweb plugin. These options specify how the
calls to /dicom-web/studies/.../metadata
and
/dicom-web/studies/.../series/.../metadata
(i.e. WADO-RS Retrieve
Metadata)
are processed:
Full
mode is used, the plugin will read all the DICOM
instances of the study/series of interest from the storage
area, which gives fully accurate results but
requires all the individual instances to be read and parsed from the
filesystem, leading to slow performance (cf. issue 162). This is
the default mode.MainDicomTags
mode is used, the plugin will only report the
main DICOM tags that are indexed by the Orthanc database. The DICOM
files are not read from the disk, which provides best
performance. However, this is a small subset of all the tags that
would be retrieved if using the Full
mode: A DICOMweb viewer
might need more tags. Important Note: From Orthanc 1.11.0 and DICOMweb plugin 1.8,
you may store more MainDicomTags in DB.
By correctly setting these tags, the MainDicomTags
mode can
become faster than the Extrapolate
mode with the same accuracy
as the Full
mode. Note that, if the ExtraMainDicomTags
are not
set correctly or have not been collected on all instances, the
Stone Web viewer will not work correctly.Extrapolate
mode is used, the plugin will read up to 3 DICOM
instances at random that belong to the study/series of interest. It
will then test whether the majority of these instances share the
same value for a predefined subset of DICOM tags. If so, this value
is added to the metadata response; otherwise, the tag is not
reported. In other words, this mode extrapolates the value of some
predefined tags by assuming that these tags should be constant
across all the instances of the study/series. This mode is a
compromise between MainDicomTags
(focus on speed) and Full
(focus on accuracy).StudiesMetadata
to MainDicomTags
and SeriesMetadata
to MainDicomTags
as demonstrated in this sample.If using the Extrapolate
mode, the predefined tags are provided
using the StudiesMetadataExtrapolatedTags
and
SeriesMetadataExtrapolatedTags
configuration options as follows:
{
[...]
"DicomWeb" : {
[...]
"StudiesMetadata" : "Extrapolate",
"StudiesMetadataExtrapolatedTags" : [
"AcquisitionDate"
],
"SeriesMetadata" : "Extrapolate",
"SeriesMetadataExtrapolatedTags" : [
"BitsAllocated",
"BitsStored",
"Columns",
"HighBit",
"PhotometricInterpretation",
"PixelSpacing",
"PlanarConfiguration",
"RescaleIntercept",
"RescaleSlope",
"Rows",
"SOPClassUID",
"SamplesPerPixel",
"SliceThickness"
]
}
}
Starting with version 1.0 of the DICOMweb plugin, a Web interface is provided to use Orthanc as a DICOMweb client. Simply click on the “Open DICOMweb client” button at the bottom of the welcome screen of Orthanc Explorer.
Here is a direct link to the DICOMweb client running on our demo server: https://demo.orthanc-server.com/dicom-web/app/client/index.html
Once your Orthanc server is properly configured (see above), you can
make REST calls to the API of the DICOMweb server. For demonstration
purpose, this section makes the assumption that the VIX
dataset
provided by OsiriX has
been uploaded to Orthanc.
Here is a proper WADO-URI (previously known simply as WADO) request to render one slice of the VIX dataset as a JPEG image:
http://localhost:8042/wado?objectUID=1.3.12.2.1107.5.1.4.54693.30000006100507010800000005466&requestType=WADO
The objectUID
corresponds to the SOPInstanceUID
DICOM tag of
some instance in the VIX
dataset. Given the Orthanc identifier of
an instance from VIX
(e.g. 14b4db2c-065edecb-6a767936-7068293a-92fcb080
), the latter
tag can be obtained from the MainDicomTags
field:
$ curl http://localhost:8042/instances/14b4db2c-065edecb-6a767936-7068293a-92fcb080
Regarding QIDO-RS (querying the content of a remote DICOMweb server), here is how to obtain the list of studies stored by Orthanc:
$ curl http://localhost:8042/dicom-web/studies
Note that the /dicom-web/
prefix comes from the configuration
option Root
of the DicomWeb
section. Filtering the studies is
possible as follows:
$ curl http://localhost:8042/dicom-web/studies?PatientName=VIX
A study can be retrieved through WADO-RS. Here is a sample using the VIX dataset:
$ curl http://localhost:8042/dicom-web/studies/2.16.840.1.113669.632.20.1211.10000315526/
This answer is a multipart stream of
application/dicom
DICOM instances, so a Web browser will not be
able to display it (. You will have to use either AJAX (JavaScript) or a
command-line tool (such as cURL).
You can render one individual frame as a plain PNG image as follows:
$ curl http://localhost:8042/dicom-web/studies/2.16.840.1.113669.632.20.1211.10000315526/series/1.3.12.2.1107.5.1.4.54693.30000006100507010800000005268/instances/1.3.12.2.1107.5.1.4.54693.30000006100507010800000005466/frames/1/rendered -H 'accept: image/png'
This page only provides some very basic examples about the use of a DICOMweb server. Please check out the full reference of the DICOMweb API for more information.
Also, check out the section about additional samples that notably provides example of STOW-RS clients in JavaScript and Python.
The list of the remote DICOMweb servers that are known to the DICOMweb plugin can be obtained as follows:
$ curl http://localhost:8042/dicom-web/servers/
[ "sample" ]
In this case, a single server called sample
is configured.
In Orthanc, the URI /{dicom-web-root}/servers/{name}/get
allows to
make a HTTP GET call against a DICOMweb server. This can be used to
issue a QIDO-RS or WADO-RS command. Orthanc will take care of properly
encoding the URL and authenticating the client. For instance, here is
a sample QIDO-RS search to query all the studies (using a bash
command-line):
$ curl http://localhost:8042/dicom-web/servers/sample/get -d @- << EOF
{
"Uri" : "/studies"
}
EOF
The result of this call is a JSON document formatted according to the DICOMweb standard. You do not have to specify the base URL of the remote DICOMweb server, as it is encoded in the configuration file.
As a more advanced example, here is how to search all the series associated with a given patient name, while requesting to use an XML format:
$ curl http://localhost:8042/dicom-web/servers/sample/get -d @- << EOF
{
"Uri" : "/series",
"HttpHeaders" : {
"Accept" : "application/dicom+xml"
},
"Arguments" : {
"00100010" : "KNIX"
}
}
EOF
The result of the command above is a multipart stream of XML documents describing each series.
Note how all the GET arguments to the QIDO-RS request must be
specified in the Arguments
field. Orthanc will take care of
properly encoding it as an URL.
An user-friendly reference of the features available in QIDO-RS and WADO-RS can be found on this site.
STOW-RS allows to send local DICOM resources to a remote DICOMweb
server. In Orthanc, the STOW-RS client primitive is available at URI
/{dicom-web-root}/servers/{name}/stow
. Here is a sample call:
$ curl http://localhost:8042/dicom-web/servers/sample/stow -X POST -d @- << EOF
{
"Resources" : [
"6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228"
]
}
EOF
Note that this primitive takes as its input a list of Orthanc identifiers corresponding to the resources (patients, studies, series and/or instances) to be exported.
Additional HTTP headers can be added with an optional HttpHeaders
argument as for QIDO-RS and WADO-RS. This might be useful e.g. for
cookie-based session management.
Internally, this call results in creating an Orthanc job that is executed synchronously (the REST call only returns once the STOW-RS request is finished). You can run the job in asynchronous mode as follows:
$ curl http://localhost:8042/dicom-web/servers/sample/stow -X POST -d @- << EOF
{
"Resources" : [
"6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228"
],
"Synchronous" : false,
"Priority" : 10
}
EOF
{
"ID" : "a7bd2a5c-291d-4ca5-977a-66502cab22a1",
"Path" : ".././../jobs/a7bd2a5c-291d-4ca5-977a-66502cab22a1"
}
Such a call ends immediately, and returns the ID of the job created by Orthanc. The status of the job can then be monitored using the Orthanc REST API.
Once DICOM resources of interest have been identified through a
QIDO-RS call to a remote DICOMweb server (cf. above), it is
interesting to download them locally with a WADO-RS call. You could do
it manually with a second call to the
/{dicom-web-root}/servers/{name}/get
URI, but Orthanc provides
another primitive .../retrieve
to automate this process, in order
to avoid the manual parsing of the multipart stream.
Here is how you would download one study, one series and one instance whose StudyInstanceUID (0020,000d), SeriesInstanceUID (0020,000e) are SOPInstanceUID (0008,0018) have been identified through a former QIDO-RS call:
$ curl http://localhost:8042/dicom-web/servers/sample/retrieve -X POST -d @- << EOF
{
"Resources" : [
{
"Study" : "1.3.51.0.1.1.192.168.29.133.1688840.1688819"
},
{
"Study" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732",
"Series" : "1.3.12.2.1107.5.2.33.37097.2012041613040617636372171.0.0.0"
},
{
"Study" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732",
"Series" : "1.3.12.2.1107.5.2.33.37097.2012041612474981424569674.0.0.0",
"Instance" : "1.3.12.2.1107.5.2.33.37097.2012041612485540185869716"
}
]
}
EOF
Orthanc will reply with the list of the Orthanc identifiers of all the DICOM instances that were downloaded from the remote server.
Remark 1: Contrarily to the .../stow
URI that uses Orthanc
identifiers, the .../retrieve
URI uses DICOM
identifiers.
Remark 2: The HttpHeaders
and Arguments
arguments are also
available, as for QIDO-RS, to fine-tune the parameters of the WADO-RS
request.
Remark 3: As for QIDO-RS, the request is run synchronously by default.
The Synchronous
and Priority
arguments can be used to
asynchronously run the request.
Samples of how to call DICOMweb services from standalone applications are available for Python and for JavaScript.
Integration tests are available separately, and provide samples for more advanced features of the REST API (such as dynamically adding/updating/removing remote DICOMweb servers using HTTP PUT and DELETE methods).