annotate Sphinx/source/plugins/wsi.rst @ 1113:a588960a72e5 default tip

spelling
author Alain Mazy <am@orthanc.team>
date Mon, 28 Oct 2024 09:23:08 +0100
parents ebe3214f3ab0
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
52
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _wsi:
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
4 Whole-slide microscopic imaging
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
5 ===============================
52
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
6
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 .. contents::
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
9 The Orthanc project provides three **official tools** to support DICOM
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
10 for whole-slide microscopic imaging (WSI):
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
11
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
12 1. A so-called "DICOM-izer" command-line tool that converts
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
13 whole-slide images to DICOM series, following `Supplement 145
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
14 <ftp://medical.nema.org/medical/dicom/final/sup145_ft.pdf>`__.
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
15 2. A plugin that extends Orthanc with a Web viewer of whole-slide
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
16 images for digital pathology.
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
17 3. Another command-line tool that converts a DICOM series stored
82
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 81
diff changeset
18 inside Orthanc, to a standard hierarchical TIFF image.
52
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19
1055
ebe3214f3ab0 added citation instructions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 993
diff changeset
20 Check out our `demonstration server
ebe3214f3ab0 added citation instructions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 993
diff changeset
21 <https://orthanc.uclouvain.be/wsi/>`__.
ebe3214f3ab0 added citation instructions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 993
diff changeset
22
ebe3214f3ab0 added citation instructions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 993
diff changeset
23 **For researchers**: `Please cite this paper
ebe3214f3ab0 added citation instructions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 993
diff changeset
24 <https://doi.org/10.5220/0006155100810087>`__.
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
25
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
26
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
27 Compilation
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
28 -----------
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
29
129
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
30 Static linking
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
31 ^^^^^^^^^^^^^^
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
32
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
33 .. highlight:: text
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
34
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
35 The procedure to compile the WSI framework is similar of that for the
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
36 :ref:`core of Orthanc <binaries>`. The following commands should work
761
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
37 for most UNIX-like distribution (including GNU/Linux)::
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
38
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
39 # Firstly, compile the command-line tools
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
40 $ mkdir Applications/Build
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
41 $ cd Applications/Build
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
42 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
43 $ make
129
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
44
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
45 # Secondly, compile the viewer plugin
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
46 $ mkdir ../../ViewerPlugin/Build
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
47 $ cd ../../ViewerPlugin/Build
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
48 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
49 $ make
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
50
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
51 The compilation will produce 3 binaries:
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
52
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
53 * ``Applications/Build/OrthancWSIDicomizer``, which contains the DICOM-izer.
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
54 * ``Applications/Build/OrthancWSIDicomToTiff``, which contains the DICOM-to-TIFF converter.
82
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 81
diff changeset
55 * ``ViewerPlugin/Build/OrthancWSI``, which is a shared library containing the viewer plugin for Orthanc.
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
56
129
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
57 Microsoft Windows
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
58 ^^^^^^^^^^^^^^^^^
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
59
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
60 Note that pre-compiled binaries for Microsoft Windows `are available
993
05b106383b2a migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 979
diff changeset
61 <https://orthanc.uclouvain.be/downloads/windows-32/orthanc-wsi/index.html>`__.
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
62
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
63
129
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
64 Dynamic linking
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
65 ^^^^^^^^^^^^^^^
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
66
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
67 .. highlight:: text
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
68
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
69 If static linking is not desired, here are build instructions for
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
70 Ubuntu 16.04 (provided build dependencies for the :ref:`core of
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
71 Orthanc <compiling>` have already been installed)::
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
72
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
73 $ sudo apt-get install libopenjpeg-dev
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
74
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
75 # Firstly, compile the command-line tools
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
76 $ mkdir Applications/Build
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
77 $ cd Applications/Build
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
78 $ cmake .. -DCMAKE_BUILD_TYPE=Release -DUSE_SYSTEM_ORTHANC_SDK=OFF
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
79 $ make
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
80
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
81 # Secondly, compile the viewer plugin
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
82 $ mkdir ../../ViewerPlugin/Build
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
83 $ cd ../../ViewerPlugin/Build
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
84 $ cmake .. -DCMAKE_BUILD_TYPE=Release -DUSE_SYSTEM_ORTHANC_SDK=OFF -DALLOW_DOWNLOADS=ON
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
85 $ make
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
86
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
87
61050d813d74 build wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 87
diff changeset
88
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
89 Usage of the plugin
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
90 -------------------
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
91
797
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
92 .. highlight:: text
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
93
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
94 You of course first have to :ref:`install Orthanc <compiling>`. Once
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
95 Orthanc is installed, you must change the :ref:`configuration file
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
96 <configuration>` to tell Orthanc where it can find the plugin: This is
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
97 done by properly modifying the ``Plugins`` configuration option. You
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
98 could for instance use the following configuration file under
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
99 GNU/Linux::
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
100
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
101 {
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
102 "Name" : "MyOrthanc",
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
103 [...]
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
104 "Plugins" : [
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
105 "/home/user/orthanc-wsi/ViewerPlugin/Build/libOrthancWSI.so"
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
106 ]
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
107 }
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
108
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
109 Orthanc must of course be restarted after the modification of its
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
110 configuration file. The WSI plugin has no specific configuration
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
111 option.
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
112
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
113 Once a :ref:`DICOM series <model-world>` is opened using :ref:`Orthanc
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
114 Explorer <orthanc-explorer>`, a yellow button entitled ``Whole-Slide
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
115 Imaging Viewer`` will show up for series corresponding to whole-slide
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
116 images. This button will open the WSI viewer for that particular
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
117 series. This behavior can be seen on the Orthanc Explorer interface
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
118 running on our `WSI demonstration server
993
05b106383b2a migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 979
diff changeset
119 <https://orthanc.uclouvain.be/wsi-orthanc/app/explorer.html>`__.
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
120
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
121
967
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
122 Support of IIIF
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
123 ---------------
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
124
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
125 Starting with its release 2.0, the WSI plugin can act as a data source
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
126 that follows the `IIIF specification
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
127 <https://en.wikipedia.org/wiki/International_Image_Interoperability_Framework>`__. This
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
128 turns Orthanc into a tool to deliver collection of high-resolutions
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
129 images over the web through IIIF, while simultaneously enabling a
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
130 standard, long-term preservation of those collections through `DICOM
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
131 vendor-neutral archiving <https://en.wikipedia.org/wiki/DICOM>`__.
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
132
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
133 REST API
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
134 ^^^^^^^^
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
135
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
136 The WSI plugin associates each of the **DICOM series** stored by
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
137 Orthanc whose :ref:`Orthanc identifier <orthanc-ids>` is ``seriesId``,
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
138 with a IIIF-compliant `Presentation API 3.0
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
139 <https://iiif.io/api/presentation/3.0/>`__ manifest located at URI
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
140 ``/wsi/iiif/series/{seriesId}/manifest.json`` in the Web server of
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
141 Orthanc. In turn, this manifest points to a IIIF-compliant `Image API
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
142 3.0 <https://iiif.io/api/image/3.0/>`__ data source to deliver the
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
143 DICOM series over the web.
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
144
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
145 Note that this data source is not only available for the whole-slide
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
146 microscopic series, but also for the other types of medical images,
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
147 which enables both telepathology and teleradiology workflows:
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
148
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
149 * In the case of a whole-slide image, the URI to the IIIF data source
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
150 is: ``/wsi/iiif/tiles/{seriesId}/info.json``.
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
151
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
152 * In the case of a regular radiology series, one IIIF data source is
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
153 associated with each frame of the DICOM series. Indeed, the
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
154 :ref:`DICOM model of the real-world <model-world>` specifies that a
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
155 single DICOM series can contain multiple instances, which in turn
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
156 can contain multiple frames. The URI to the IIIF data source
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
157 corresponding to one individual frame of interest is:
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
158 ``/wsi/iiif/frames/{seriesId}/{frameIndex}/info.json``, where
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
159 ``frameIndex`` is the index of the frame in the DICOM series. The
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
160 ``manifest.json`` of the parent DICOM series automatically
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
161 aggregates all the frames of the series as a single collection.
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
162
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
163
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
164 Web user interface
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
165 ^^^^^^^^^^^^^^^^^^
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
166
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
167 :ref:`Orthanc Explorer <orthanc-explorer>` contains a button to easily
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
168 copy/paste the URL of the IIIF manifest corresponding to a DICOM
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
169 series:
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
170
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
171 .. image:: ../images/2023-07-13-IIIF.png
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
172 :align: center
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
173 :width: 500px
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
174
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
175 |
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
176
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
177 Furthermore, as can be seen in the image above, buttons can be enabled
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
178 to test the opening of the IIIF data source using `Mirador
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
179 <https://projectmirador.org/>`__ and/or `OpenSeadragon
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
180 <https://openseadragon.github.io/>`__.
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
181
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
182 Pay attention to the fact that the assets of Mirador and OpenSeadragon
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
183 (notably JavaScript) are loaded from the `unpkg CDN
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
184 <https://www.unpkg.com/>`__, which necessitates an Internet
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
185 connection. For this reason, these assets are disabled by default.
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
186
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
187
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
188 Configuration options
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
189 ^^^^^^^^^^^^^^^^^^^^^
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
190
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
191 .. highlight:: json
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
192
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
193 The IIIF features can be configured using the following
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
194 :ref:`configuration file <configuration>` of Orthanc::
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
195
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
196 {
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
197 "Name" : "MyOrthanc",
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
198 [...]
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
199 "Plugins" : [
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
200 "/home/user/orthanc-wsi/ViewerPlugin/Build/libOrthancWSI.so"
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
201 ],
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
202 "WholeSlideImaging" : {
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
203 "EnableIIIF" : true, // Can be used to disable support of IIIF
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
204 "OrthancPublicURL" : "http://localhost:8042/",
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
205 "ServeMirador" : false, // Whether to show the "Test IIIF in Mirador" button
979
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 967
diff changeset
206 "ServeOpenSeadragon" : false, // Whether to show the "Test IIIF in OpenSeadragon" button
967
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
207 "ForcePowersOfTwoScaleFactors" : true // Can be used to disable the compatibility mode
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
208 }
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
209 }
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
210
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
211 A few remarks:
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
212
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
213 * The ``OrthancPublicURL`` option must be adapted if Orthanc is
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
214 branched behind a :ref:`reverse proxy <nginx>`.
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
215
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
216 * In the case of a whole-slide image, the
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
217 ``ForcePowersOfTwoScaleFactors`` option instruct the WSI plugin to
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
218 only publish the pyramid levels whose scale factors follow a
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
219 powers-of-two patterns (i.e., 1, 2, 4, 8, 16...). This provides
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
220 maximum compatibility with viewers (for instance, consider `this
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
221 issue
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
222 <https://github.com/openseadragon/openseadragon/issues/2379>`__),
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
223 but can break a smooth delivery of high-resolution images whose
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
224 pyramid is irregular. Compatibility mode is enabled by default.
2df3597eacc8 documentation of IIIF support
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 966
diff changeset
225
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
226
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
227 Command-line tools
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
228 ------------------
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
229
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
230 .. highlight:: text
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
231
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
232 The command-line tools ``OrthancWSIDicomizer`` and
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
233 ``OrthancWSIDicomToTiff`` provide documentation of all their options
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
234 if started with the ``--help`` parameter::
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
235
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
236 $ ./OrthancWSIDicomizer --help
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
237 $ ./OrthancWSIDicomToTiff --help
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
238
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
239 In this section, we review the most common usages of these tools.
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
240
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
241
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
242 Transcoding a DICOM image
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
243 ^^^^^^^^^^^^^^^^^^^^^^^^^
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
244
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
245 The most simple usage consists in converting some whole-slide image to
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
246 DICOM, then uploading it to Orthanc::
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
247
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
248 $ ./OrthancWSIDicomizer Source.tif
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
249
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
250 This command will transcode some `hierarchical, tiled TIFF
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
251 <https://en.wikipedia.org/wiki/TIFF>`__ image called ``Source.tif``,
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
252 and push the generated DICOM files to the default Orthanc server
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
253 (running on ``localhost`` and listening to HTTP port ``8042``) using
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
254 its :ref:`REST API <rest>`. The log of the command will give you the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
255 :ref:`identifier of the generated series <orthanc-ids>`, so that you
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
256 can locate it in Orthanc Explorer. This conversion is fast, as no
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
257 re-encoding takes place: If the source TIFF image contains JPEG tiles,
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
258 these tiles will be simply written as such.
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
259
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
260 Obviously, you can specify the parameters of the REST API of your
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
261 target Orthanc server::
82
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 81
diff changeset
262
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
263 $ ./OrthancWSIDicomizer Source.tif --orthanc=http://localhost:8042/ --username=orthanc --password=orthanc
82
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 81
diff changeset
264
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
265 It is also possible to write the DICOM instances directly onto some
82
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 81
diff changeset
266 folder of the filesystem (the target folder must be existing)::
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 81
diff changeset
267
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
268 $ ./OrthancWSIDicomizer Source.tif --folder=/tmp/dicomized/
82
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 81
diff changeset
269
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
270 This command will create a set of files entitled like
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
271 ``/tmp/dicomized/wsi-XXXXXX.dcm``. You can modify this pattern using
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
272 the command-line option ``--folder-pattern``.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
273
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
274 By default, the DICOM-izer will spread the output series as a set of
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
275 DICOM files whose size stays below 10MB. This prevents the appearance
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
276 of huge files, which speeds up further processing. This behavior can
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
277 be controlled using the ``--max-size`` command-line option.
82
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 81
diff changeset
278
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
279
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
280 Re-encoding a DICOM image
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
281 ^^^^^^^^^^^^^^^^^^^^^^^^^
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
282
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
283 The section above explained how to transcode whole-slide images,
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
284 without modifying the compression scheme of their individual tiles
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
285 (which is most commonly JPEG). You can instruct the DICOM-izer to
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
286 re-encode each and every individual tile as follows::
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
287
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
288 $ ./OrthancWSIDicomizer Source.tif --reencode=1 --compression=jpeg2000
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
289
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
290 This example would create a series of DICOM instances encoded using
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
291 the JPEG2k transfer syntax (whose UID is ``1.2.840.10008.1.2.4.90``).
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
292 As JPEG2k is not natively supported by many Web browsers, the Web
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
293 viewer plugin would transparently convert such JPEG2k-encoded tiles to
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
294 PNG images.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
295
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
296 It is also possible to re-encode the image so as to reduce disk space
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
297 consumption by changing the JPEG quality::
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
298
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
299 $ ./OrthancWSIDicomizer Source.tif --reencode=1 --compression=jpeg --jpeg-quality=10
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
300
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
301 The DICOM-izer also allows to re-generate all the multi-resolution
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
302 pyramid. This is extremely importantly to enhance the user experience
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
303 of the Web interface, if the source image only features the finest
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
304 zoom level of the whole-slide image::
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
305
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
306 $ ./OrthancWSIDicomizer Source.tif --pyramid=1 --smooth=1
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
307
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
308 The number of levels in the pyramid can be controlled using the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
309 ``--levels`` command-line option. The ``--smooth=1`` option tells the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
310 DICOM-izer to apply `Gaussian smoothing
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
311 <https://en.wikipedia.org/wiki/Gaussian_blur>`__ when re-scaling the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
312 image, in order to avoid the appearance of aliasing in the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
313 multi-resolution pyramid. This produces nicer images, at the price of
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
314 higher computation time.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
315
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
316 All the examples described in this section are obviously much more
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
317 CPU-intensive than simple transcoding. The DICOM-izer takes advantage
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
318 in multi-threading to reduce the computation time. By default, it will
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
319 use half the number of logical CPU cores that are available. This
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
320 behavior can be fine-tuned using command-line option ``--threads``.
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
321
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
322
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
323
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
324 Proprietary file formats
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
325 ^^^^^^^^^^^^^^^^^^^^^^^^
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
326
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
327 Out-of-the-box, the DICOM-izer supports standard hierarchical TIFF
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
328 images. Some commonplace image formats (PNG and JPEG) can be
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
329 DICOM-ized as well. However, whole-slide images can come in many
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
330 proprietary file formats. To re-encode such images, the DICOM-izer
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 129
diff changeset
331 relies upon the `OpenSlide toolbox <https://openslide.org/>`__.
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
332
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
333 For this feature to work, you have to tell the command-line tool where
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
334 it can find the OpenSlide shared library. GNU/Linux distributions
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
335 generally provide packages containing the OpenSlide shared library
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
336 (e.g. under Debian/Ubuntu, simply install the ``libopenslide0``
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
337 package)::
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
338
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
339 $ ./OrthancWSIDicomizer --openslide=libopenslide.so CMU-1-JP2K-33005.svs
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
340
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
341 Pre-compiled Microsoft Windows binaries of this shared library can be
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 129
diff changeset
342 found on the `OpenSlide homepage <https://openslide.org/download/>`__ (Note that
87
f8aa67501041 extra info for libOpenSlide Windows package
Alain Mazy <alain@mazy.be>
parents: 85
diff changeset
343 you should copy all .dll files from the OpenSlide package next to the OrthancWSIDicomizer
f8aa67501041 extra info for libOpenSlide Windows package
Alain Mazy <alain@mazy.be>
parents: 85
diff changeset
344 executable)::
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
345
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
346 $ ./OrthancWSIDicomizer --openslide=libopenslide-0.dll CMU-1-JP2K-33005.svs
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
347
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
348 Note that this operation implies the re-encoding of the source image
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
349 from the proprietary file format, which is much more time-consuming
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
350 than simply transcoding a TIFF image.
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
351
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
352
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
353 Specifying a DICOM dataset
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
354 ^^^^^^^^^^^^^^^^^^^^^^^^^^
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
355
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
356 So far, we have only been discussing the whole-slide image by itself,
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
357 and not the :ref:`medical information <dicom-tags>` that is associated
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
358 with each DICOM file. The DICOM tags that must be embedded inside the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
359 generated DICOM series can be specified using the user-friendly JSON
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
360 file format. You would first generate a minimal, sample JSON dataset
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
361 as follows::
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
362
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
363 $ ./OrthancWSIDicomizer --sample-dataset > dataset.json
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
364
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
365 Secondly, you would edit the just-generated ``dataset.json`` file
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
366 using any text editor (or any script interfaced with your RIS), so as
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
367 to encode medical information associated with the image
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
368 acquisition. Finally, tell the DICOM-izer where it can find the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
369 dataset when re-encoding or transcoding the image::
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
370
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
371 $ ./OrthancWSIDicomizer Source.tif --dataset=dataset.json
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
372
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
373 Note that it is always a good idea to check whether all the required
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
374 DICOM tags have been properly provided, e.g. by running the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
375 ``dciodvfy`` command-line tool provided by `David Clunie
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
376 <http://www.dclunie.com/dicom3tools.html>`__ that checks the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
377 compliance of DICOM files.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
378
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
379
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
380 Converting DICOM to TIFF
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
381 ^^^^^^^^^^^^^^^^^^^^^^^^
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
382
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
383 The whole-slide imaging framework for Orthanc also provides a
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
384 command-line tool that converts some DICOM series, as a standard
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
385 hierarchical, tiled TIFF image. This is important if you wish to
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
386 export some DICOM file to a framework that does not support DICOM
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
387 Supplement 145.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
388
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
389 Here is how you would convert a whole-slide image stored in the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
390 default Orthanc server::
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
391
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
392 $ ./OrthancWSIDicomToTiff fdf53e42-06d7377a-c24c59fd-3704e72d-f4c75b68 Target.tif
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
393
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
394 You just have to provide the :ref:`Orthanc identifier <orthanc-ids>`
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
395 of the series of interest (that can be retrieved using :ref:`Orthanc
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
396 Explorer <orthanc-explorer>` or the :ref:`REST API <rest>`), and the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
397 path to the target TIFF file.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
398
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
399 Similarly to the DICOM-izer, the command-line options ``--orthanc``,
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
400 ``--username`` and ``--password`` can be used to specify the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
401 parameters of your Orthanc server.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
402
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
403
797
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
404 Interface with Cytomine
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
405 -----------------------
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
406
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
407 `Cytomine <https://cytomine.be/>`__ is an "*open-source rich internet
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
408 application for collaborative analysis of multi-gigapixel images.*"
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
409 Starting with release 1.1 of the whole-slide imaging framework for
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
410 Orthanc, it is possible to exchange digital pathology images back and
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
411 forth between Orthanc and Cytomine according to the following
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
412 workflow:
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
413
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
414 .. image:: ../images/2021-12-12-Cytomine.png
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
415 :align: center
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
416 :width: 500px
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
417
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
418 |
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
419
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
420 As can be seen, ``OrthancWSIDicomizer`` imports the source image from
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
421 Cytomine using its REST API, then puts the converted DICOM instances
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
422 onto Orthanc using its REST API. Here is a minimalist sample call to
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
423 the ``OrthancWSIDicomizer`` command-line tool to convert an image from
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
424 a Cytomine server onto an Orthanc server listening on
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
425 ``localhost:8042`` with default parameters ::
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
426
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
427 $ ./OrthancWSIDicomizer --cytomine-url=http://XXX --cytomine-image=325 \
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
428 --cytomine-public-key=YYY --cytomine-private-key=ZZZ \
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
429 --threads=4 --pyramid=1 --username=orthanc --password=orthanc --verbose
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
430
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
431 The ``--cytomine-image`` parameter corresponds to the ID of the `Image
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
432 Instance <https://doc.uliege.cytomine.org/dev-guide/api/reference>`__
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
433 of interest. This ID can easily be retrieved from the Web interface of
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
434 Cytomine:
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
435
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
436 .. image:: ../images/Cytomine.png
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
437 :align: center
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
438 :width: 600px
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
439
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
440 |
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
441
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
442 The ``--cytomine-public-key`` and ``--cytomine-private-key``
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
443 parameters grant access to the REST API of Cytomine, and can be found
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
444 in the parameters of your account using the Web interface of Cytomine:
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
445
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
446 .. image:: ../images/CytomineKeys.png
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
447 :align: center
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
448 :width: 600px
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
449
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
450 |
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
451
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
452
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
453
4d431ad58521 cytomine
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 761
diff changeset
454
81
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
455 REST API
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
456 --------
4eea0dc5f071 documenting wsi
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 52
diff changeset
457
85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
458 Besides providing an user interface, the plugin for whole-slide
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
459 imaging also enrich the :ref:`REST API <rest>` of Orthanc with some
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
460 new URIs, that are described in this section.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
461
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
462 Note that the Web interface of the plugin exclusively relies upon this
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
463 enriched REST API in order to display whole-slide images using the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
464 `OpenLayers 3 <https://openlayers.org/>`__ JavaScript library.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
465
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
466
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
467 Information about a whole-slide image
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
468 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
469
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
470 You can check whether a DICOM series associated with some known
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
471 :ref:`Orthanc ID <orthanc-ids>` ``id`` corresponds to a whole-slide
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
472 image by calling the ``/wsi/pyramids/{id}`` URI. A HTTP status code
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
473 404 is returned if the series is *not* a whole-slide image::
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
474
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
475 $ curl -v http://localhost:8042/wsi/pyramids/ca2cc2ef-2dd8be12-0a4506ae-d565b7e1-a4ca9068
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
476 [...]
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
477 < HTTP/1.1 404 Not Found
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
478
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
479 However, if the identifier corresponds to a valid whole-slide image,
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
480 you will get information about its multi-resolution pyramid, formatted
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
481 using JSON::
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
482
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
483 $ curl http://localhost:8042/wsi/pyramids/f0ed5846-2ce36a70-d27bb5d3-6ed9dac2-ee638d85
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
484 {
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
485 "ID" : "f0ed5846-2ce36a70-d27bb5d3-6ed9dac2-ee638d85",
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
486 "Resolutions" : [ 1, 2, 4, 8, 16 ],
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
487 "Sizes" : [
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
488 [ 10800, 5400 ],
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
489 [ 5400, 2700 ],
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
490 [ 2700, 1350 ],
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
491 [ 1350, 675 ],
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
492 [ 675, 338 ]
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
493 ],
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
494 "TileHeight" : 512,
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
495 "TileWidth" : 512,
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
496 "TilesCount" : [
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
497 [ 22, 11 ],
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
498 [ 11, 6 ],
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
499 [ 6, 3 ],
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
500 [ 3, 2 ],
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
501 [ 2, 1 ]
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
502 ],
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
503 "TotalHeight" : 5400,
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
504 "TotalWidth" : 10800
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
505 }
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
506
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
507 The size of the finest level of the pyramid is verbatim available from
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
508 this output (in the example above, ``10,800 x 5,400`` pixels), as well
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
509 as the size of each individual tile (``512 x 512`` pixels). The
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
510 ``TilesCount`` gives, for each level of the pyramid (sorted in
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
511 decreasing resolutions), the number of tiles along each dimension: In
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
512 the example above, the coarsest level contains 2 tiles along the X
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
513 axis, and 1 tile along the Y.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
514
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
515 Note that the interpretation of the whole-slide image is done
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
516 transparently by the plugin, which frees the user from parsing each
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
517 and every DICOM instance in the series.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
518
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
519 The medical information associated with the series or its instances
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
520 can as usual be retrieved using the core :ref:`REST API <rest>` of
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
521 Orthanc.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
522
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
523
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
524 Decoding the individual tiles
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
525 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
526
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
527 As discussed above, the ``/wsi/pyramids/{id}`` gives information about
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
528 the number of tiles in each level of the multi-resolution pyramid
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
529 associated with series ``id``.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
530
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
531 You can then retrieve the individual tiles of each level using the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
532 ``/wsi/tiles/{id}/{z}/{x}/{y}`` URI, where ``z`` corresponds to the
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
533 level of interest, and (``x``, ``y``) the index of the tile of
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
534 interest at this level. All of these indices start at zero, the level
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
535 ``z=0`` corresponding to the finest level.
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
536
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
537 For instance, here is how to retrieve the central tile of the finest
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
538 level of the pyramid (that contains ``22 x 11`` tiles in our example)::
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
539
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
540 $ curl http://localhost:8042/wsi/tiles/f0ed5846-2ce36a70-d27bb5d3-6ed9dac2-ee638d85/0/11/5 > tile.jpg
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
541 $ identify ./tile.jpg
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
542 ./tile.jpg JPEG 512x512 512x512+0+0 8-bit DirectClass 88.5KB 0.000u 0:00.000
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
543
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
544 As can be seen, the plugin has returned a JPEG image of size ``512 x
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
545 512``, which corresponds to the size of the tiles in this sample
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
546 image. If trying to access a tile outside the image, the plugin will
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
547 return with an HTTP status code that is not ``200 OK``. Similarly,
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
548 here is how to retrieve a tile at the coarsest level (the pyramid has
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
549 5 levels in our example)::
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
550
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
551 $ curl http://localhost:8042/wsi/tiles/f0ed5846-2ce36a70-d27bb5d3-6ed9dac2-ee638d85/4/0/0 > tile.jpg
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
552
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
553 Depending upon the transfer syntax of the DICOM instances, the tile
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
554 might not be encoded using JPEG. Indeed, if the transfer syntax is
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
555 uncompressed (UID ``1.2.840.10008.1.2`` and friends) or JPEG2k
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
556 lossless (UID ``1.2.840.10008.1.2.4.90``), the plugin will
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
557 transparently re-encode the tile to PNG in order to avoid any
13dd3f20a00a wsi rest api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 82
diff changeset
558 destructive compression.
966
02121f3c7e65 note about the Accept header in WSI plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 797
diff changeset
559
02121f3c7e65 note about the Accept header in WSI plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 797
diff changeset
560 NB: Starting with version 2.0 of the WSI plugin, the
02121f3c7e65 note about the Accept header in WSI plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 797
diff changeset
561 ``/wsi/tiles/{id}/{z}/{x}/{y}`` route accepts the ``Accept`` HTTP
02121f3c7e65 note about the Accept header in WSI plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 797
diff changeset
562 header, which can be used to force the compression of the tile. The
02121f3c7e65 note about the Accept header in WSI plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 797
diff changeset
563 allowed values for ``Accept`` are: ``image/png``, ``image/jpeg``, and
02121f3c7e65 note about the Accept header in WSI plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 797
diff changeset
564 ``image/jp2`` (which corresponds to JPEG2k).