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