Mercurial > hg > orthanc-book
comparison Sphinx/source/plugins/wsi.rst @ 85:13dd3f20a00a
wsi rest api
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Fri, 16 Dec 2016 13:01:24 +0100 |
parents | 0752d8518623 |
children | f8aa67501041 |
comparison
equal
deleted
inserted
replaced
84:9ceb0e13dff9 | 85:13dd3f20a00a |
---|---|
1 .. _wsi: | 1 .. _wsi: |
2 | 2 |
3 | 3 |
4 Whole-Slide Microscopic Imaging | 4 Whole-slide microscopic imaging |
5 =============================== | 5 =============================== |
6 | 6 |
7 .. contents:: | 7 .. contents:: |
8 | 8 |
9 The Orthanc project provides three **official tools** to support DICOM | 9 The Orthanc project provides three **official tools** to support DICOM |
22 | 22 |
23 | 23 |
24 Compilation | 24 Compilation |
25 ----------- | 25 ----------- |
26 | 26 |
27 .. highlight:: bash | 27 .. highlight:: text |
28 | 28 |
29 The procedure to compile the WSI framework is similar of that for the | 29 The procedure to compile the WSI framework is similar of that for the |
30 :ref:`core of Orthanc <binaries>`. The following commands should work | 30 :ref:`core of Orthanc <binaries>`. The following commands should work |
31 for every UNIX-like distribution (including GNU/Linux):: | 31 for every UNIX-like distribution (including GNU/Linux):: |
32 | 32 |
33 # Firstly, compile the command-line tools | 33 # Firstly, compile the command-line tools |
34 $ mkdir Applications/Build | 34 $ mkdir Applications/Build |
35 $ cd Applications/Build | 35 $ cd Applications/Build |
36 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release | 36 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release |
37 $ make | 37 $ make |
38 # Secondly, compile the plugin | 38 # Secondly, compile the viewer plugin |
39 $ mkdir ../../ViewerPlugin/Build | 39 $ mkdir ../../ViewerPlugin/Build |
40 $ cd ../../ViewerPlugin/Build | 40 $ cd ../../ViewerPlugin/Build |
41 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release | 41 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release |
42 $ make | 42 $ make |
43 | 43 |
49 | 49 |
50 Note that pre-compiled binaries for Microsoft Windows `are available | 50 Note that pre-compiled binaries for Microsoft Windows `are available |
51 <http://www.orthanc-server.com/browse.php?path=/whole-slide-imaging>`__. | 51 <http://www.orthanc-server.com/browse.php?path=/whole-slide-imaging>`__. |
52 | 52 |
53 | 53 |
54 Installation of the plugin | 54 Usage of the plugin |
55 -------------------------- | 55 ------------------- |
56 | 56 |
57 .. highlight:: json | 57 .. highlight:: json |
58 | 58 |
59 You of course first have to :ref:`install Orthanc <compiling>`. Once | 59 You of course first have to :ref:`install Orthanc <compiling>`. Once |
60 Orthanc is installed, you must change the :ref:`configuration file | 60 Orthanc is installed, you must change the :ref:`configuration file |
61 <configuration>` to tell Orthanc where it can find the plugin: This is | 61 <configuration>` to tell Orthanc where it can find the plugin: This is |
62 done by properly modifying the ``Plugins`` option. You could for | 62 done by properly modifying the ``Plugins`` configuration option. You |
63 instance use the following configuration file:: | 63 could for instance use the following configuration file under |
64 GNU/Linux:: | |
64 | 65 |
65 { | 66 { |
66 "Name" : "MyOrthanc", | 67 "Name" : "MyOrthanc", |
67 [...] | 68 [...] |
68 "Plugins" : [ | 69 "Plugins" : [ |
72 | 73 |
73 Orthanc must of course be restarted after the modification of its | 74 Orthanc must of course be restarted after the modification of its |
74 configuration file. The WSI plugin has no specific configuration | 75 configuration file. The WSI plugin has no specific configuration |
75 option. | 76 option. |
76 | 77 |
77 Once a :ref:`DICOM series <model-world>` is opened using Orthanc | 78 Once a :ref:`DICOM series <model-world>` is opened using :ref:`Orthanc |
78 Explorer, a yellow button entitled ``Whole-Slide Imaging Viewer`` will | 79 Explorer <orthanc-explorer>`, a yellow button entitled ``Whole-Slide |
79 show up for series corresponding to whole-slide images. This button | 80 Imaging Viewer`` will show up for series corresponding to whole-slide |
80 will open the WSI viewer for that particular series. This behavior can | 81 images. This button will open the WSI viewer for that particular |
81 be seen on the Orthanc Explorer running on our `WSI demonstration | 82 series. This behavior can be seen on the Orthanc Explorer interface |
82 server <http://wsi.orthanc-server.com/orthanc/app/explorer.html>`__. | 83 running on our `WSI demonstration server |
84 <http://wsi.orthanc-server.com/orthanc/app/explorer.html>`__. | |
83 | 85 |
84 | 86 |
85 | 87 |
86 Command-line tools | 88 Command-line tools |
87 ------------------ | 89 ------------------ |
88 | 90 |
89 .. highlight:: bash | 91 .. highlight:: text |
90 | 92 |
91 The command-line tools ``OrthancWSIDicomizer`` and | 93 The command-line tools ``OrthancWSIDicomizer`` and |
92 ``OrthancWSIDicomToTiff`` provide documentation of all their options | 94 ``OrthancWSIDicomToTiff`` provide documentation of all their options |
93 if started with the ``--help`` parameter:: | 95 if started with the ``--help`` parameter:: |
94 | 96 |
95 $ OrthancWSIDicomizer --help | 97 $ ./OrthancWSIDicomizer --help |
96 $ OrthancWSIDicomToTiff --help | 98 $ ./OrthancWSIDicomToTiff --help |
97 | 99 |
98 In this section, we review the most common usages of these tools. | 100 In this section, we review the most common usages of these tools. |
99 | 101 |
100 | 102 |
101 Transcoding a DICOM image | 103 Transcoding a DICOM image |
102 ^^^^^^^^^^^^^^^^^^^^^^^^^ | 104 ^^^^^^^^^^^^^^^^^^^^^^^^^ |
103 | 105 |
104 The most simple usage consists in converting some whole-slide image to | 106 The most simple usage consists in converting some whole-slide image to |
105 DICOM, then uploading it to Orthanc:: | 107 DICOM, then uploading it to Orthanc:: |
106 | 108 |
107 $ OrthancWSIDicomizer Source.tif | 109 $ ./OrthancWSIDicomizer Source.tif |
108 | 110 |
109 This command will transcode some `hierarchical, tiled TIFF | 111 This command will transcode some `hierarchical, tiled TIFF |
110 <https://en.wikipedia.org/wiki/TIFF>`__ image called ``Source.tif``, | 112 <https://en.wikipedia.org/wiki/TIFF>`__ image called ``Source.tif``, |
111 and push the output DICOM files to the default Orthanc server (running | 113 and push the generated DICOM files to the default Orthanc server |
112 on ``localhost`` and listening to HTTP port ``8042``) using its | 114 (running on ``localhost`` and listening to HTTP port ``8042``) using |
113 :ref:`REST API <rest>`. This operation is fast, as no re-encoding | 115 its :ref:`REST API <rest>`. The log of the command will give you the |
114 takes place: If the source TIFF image contains JPEG tiles, these tiles | 116 :ref:`identifier of the generated series <orthanc-ids>`, so that you |
115 will be written as such. | 117 can locate it in Orthanc Explorer. This conversion is fast, as no |
116 | 118 re-encoding takes place: If the source TIFF image contains JPEG tiles, |
117 Obviously, you can specify the parameters of your Orthanc server:: | 119 these tiles will be simply written as such. |
118 | 120 |
119 $ OrthancWSIDicomizer Source.tif --orthanc=http://localhost:8042/ --username=orthanc --password=orthanc | 121 Obviously, you can specify the parameters of the REST API of your |
120 | 122 target Orthanc server:: |
121 It is also possible to write the DICOM instance directly onto some | 123 |
124 $ ./OrthancWSIDicomizer Source.tif --orthanc=http://localhost:8042/ --username=orthanc --password=orthanc | |
125 | |
126 It is also possible to write the DICOM instances directly onto some | |
122 folder of the filesystem (the target folder must be existing):: | 127 folder of the filesystem (the target folder must be existing):: |
123 | 128 |
124 $ OrthancWSIDicomizer Source.tif --folder=/tmp/dicomized/ | 129 $ ./OrthancWSIDicomizer Source.tif --folder=/tmp/dicomized/ |
125 | 130 |
131 This command will create a set of files entitled like | |
132 ``/tmp/dicomized/wsi-XXXXXX.dcm``. You can modify this pattern using | |
133 the command-line option ``--folder-pattern``. | |
134 | |
135 By default, the DICOM-izer will spread the output series as a set of | |
136 DICOM files whose size stays below 10MB. This prevents the appearance | |
137 of huge files, which speeds up further processing. This behavior can | |
138 be controlled using the ``--max-size`` command-line option. | |
126 | 139 |
127 | 140 |
128 Re-encoding a DICOM image | 141 Re-encoding a DICOM image |
129 ^^^^^^^^^^^^^^^^^^^^^^^^^ | 142 ^^^^^^^^^^^^^^^^^^^^^^^^^ |
130 | 143 |
144 The section above explained how to transcode whole-slide images, | |
145 without modifying the compression scheme of their individual tiles | |
146 (which is most commonly JPEG). You can instruct the DICOM-izer to | |
147 re-encode each and every individual tile as follows:: | |
148 | |
149 $ ./OrthancWSIDicomizer Source.tif --reencode=1 --compression=jpeg2000 | |
150 | |
151 This example would create a series of DICOM instances encoded using | |
152 the JPEG2k transfer syntax (whose UID is ``1.2.840.10008.1.2.4.90``). | |
153 As JPEG2k is not natively supported by many Web browsers, the Web | |
154 viewer plugin would transparently convert such JPEG2k-encoded tiles to | |
155 PNG images. | |
156 | |
157 It is also possible to re-encode the image so as to reduce disk space | |
158 consumption by changing the JPEG quality:: | |
159 | |
160 $ ./OrthancWSIDicomizer Source.tif --reencode=1 --compression=jpeg --jpeg-quality=10 | |
161 | |
162 The DICOM-izer also allows to re-generate all the multi-resolution | |
163 pyramid. This is extremely importantly to enhance the user experience | |
164 of the Web interface, if the source image only features the finest | |
165 zoom level of the whole-slide image:: | |
166 | |
167 $ ./OrthancWSIDicomizer Source.tif --pyramid=1 --smooth=1 | |
168 | |
169 The number of levels in the pyramid can be controlled using the | |
170 ``--levels`` command-line option. The ``--smooth=1`` option tells the | |
171 DICOM-izer to apply `Gaussian smoothing | |
172 <https://en.wikipedia.org/wiki/Gaussian_blur>`__ when re-scaling the | |
173 image, in order to avoid the appearance of aliasing in the | |
174 multi-resolution pyramid. This produces nicer images, at the price of | |
175 higher computation time. | |
176 | |
177 All the examples described in this section are obviously much more | |
178 CPU-intensive than simple transcoding. The DICOM-izer takes advantage | |
179 in multi-threading to reduce the computation time. By default, it will | |
180 use half the number of logical CPU cores that are available. This | |
181 behavior can be fine-tuned using command-line option ``--threads``. | |
131 | 182 |
132 | 183 |
133 | 184 |
134 Proprietary file formats | 185 Proprietary file formats |
135 ^^^^^^^^^^^^^^^^^^^^^^^^ | 186 ^^^^^^^^^^^^^^^^^^^^^^^^ |
136 | 187 |
137 Out-of-the-box, the DICOM-izer supports standard hierarchical TIFF | 188 Out-of-the-box, the DICOM-izer supports standard hierarchical TIFF |
138 images. Some commonplace image formats (PNG and JPEG) can be | 189 images. Some commonplace image formats (PNG and JPEG) can be |
139 DICOM-ized as well. However, whole-slide images can come in many | 190 DICOM-ized as well. However, whole-slide images can come in many |
140 proprietary file formats. To transcode such images, the DICOM-izer | 191 proprietary file formats. To re-encode such images, the DICOM-izer |
141 relies upon the `OpenSlide toolbox <http://openslide.org/>`__. | 192 relies upon the `OpenSlide toolbox <http://openslide.org/>`__. |
142 | 193 |
143 For this feature to work, you have to tell the command-line tool where | 194 For this feature to work, you have to tell the command-line tool where |
144 it can find the OpenSlide shared library. GNU/Linux distributions | 195 it can find the OpenSlide shared library. GNU/Linux distributions |
145 generally provide packages containing the OpenSlide shared library | 196 generally provide packages containing the OpenSlide shared library |
146 (under Debian/Ubuntu, simply install the ``libopenslide0`` package):: | 197 (e.g. under Debian/Ubuntu, simply install the ``libopenslide0`` |
147 | 198 package):: |
148 $ OrthancWSIDicomizer --openslide=libopenslide.so CMU-1-JP2K-33005.svs | 199 |
149 | 200 $ ./OrthancWSIDicomizer --openslide=libopenslide.so CMU-1-JP2K-33005.svs |
150 Precompiled Microsoft Windows binaries of this shared library can be | 201 |
202 Pre-compiled Microsoft Windows binaries of this shared library can be | |
151 found on the `OpenSlide homepage <http://openslide.org/download/>`__:: | 203 found on the `OpenSlide homepage <http://openslide.org/download/>`__:: |
152 | 204 |
153 $ OrthancWSIDicomizer --openslide=libopenslide-0.dll CMU-1-JP2K-33005.svs | 205 $ ./OrthancWSIDicomizer --openslide=libopenslide-0.dll CMU-1-JP2K-33005.svs |
154 | 206 |
155 Note that this operation implies the re-encoding of the source image | 207 Note that this operation implies the re-encoding of the source image |
156 from the proprietary file format, which is much more time-consuming | 208 from the proprietary file format, which is much more time-consuming |
157 than simply transcoding a TIFF image. | 209 than simply transcoding a TIFF image. |
158 | 210 |
159 | 211 |
160 | |
161 Specifying a DICOM dataset | 212 Specifying a DICOM dataset |
162 ^^^^^^^^^^^^^^^^^^^^^^^^^^ | 213 ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
163 | 214 |
215 So far, we have only been discussing the whole-slide image by itself, | |
216 and not the :ref:`medical information <dicom-tags>` that is associated | |
217 with each DICOM file. The DICOM tags that must be embedded inside the | |
218 generated DICOM series can be specified using the user-friendly JSON | |
219 file format. You would first generate a minimal, sample JSON dataset | |
220 as follows:: | |
221 | |
222 $ ./OrthancWSIDicomizer --sample-dataset > dataset.json | |
223 | |
224 Secondly, you would edit the just-generated ``dataset.json`` file | |
225 using any text editor (or any script interfaced with your RIS), so as | |
226 to encode medical information associated with the image | |
227 acquisition. Finally, tell the DICOM-izer where it can find the | |
228 dataset when re-encoding or transcoding the image:: | |
229 | |
230 $ ./OrthancWSIDicomizer Source.tif --dataset=dataset.json | |
231 | |
232 Note that it is always a good idea to check whether all the required | |
233 DICOM tags have been properly provided, e.g. by running the | |
234 ``dciodvfy`` command-line tool provided by `David Clunie | |
235 <http://www.dclunie.com/dicom3tools.html>`__ that checks the | |
236 compliance of DICOM files. | |
237 | |
164 | 238 |
165 Converting DICOM to TIFF | 239 Converting DICOM to TIFF |
166 ^^^^^^^^^^^^^^^^^^^^^^^^ | 240 ^^^^^^^^^^^^^^^^^^^^^^^^ |
167 | 241 |
242 The whole-slide imaging framework for Orthanc also provides a | |
243 command-line tool that converts some DICOM series, as a standard | |
244 hierarchical, tiled TIFF image. This is important if you wish to | |
245 export some DICOM file to a framework that does not support DICOM | |
246 Supplement 145. | |
247 | |
248 Here is how you would convert a whole-slide image stored in the | |
249 default Orthanc server:: | |
250 | |
251 $ ./OrthancWSIDicomToTiff fdf53e42-06d7377a-c24c59fd-3704e72d-f4c75b68 Target.tif | |
252 | |
253 You just have to provide the :ref:`Orthanc identifier <orthanc-ids>` | |
254 of the series of interest (that can be retrieved using :ref:`Orthanc | |
255 Explorer <orthanc-explorer>` or the :ref:`REST API <rest>`), and the | |
256 path to the target TIFF file. | |
257 | |
258 Similarly to the DICOM-izer, the command-line options ``--orthanc``, | |
259 ``--username`` and ``--password`` can be used to specify the | |
260 parameters of your Orthanc server. | |
261 | |
168 | 262 |
169 REST API | 263 REST API |
170 -------- | 264 -------- |
171 | 265 |
266 Besides providing an user interface, the plugin for whole-slide | |
267 imaging also enrich the :ref:`REST API <rest>` of Orthanc with some | |
268 new URIs, that are described in this section. | |
269 | |
270 Note that the Web interface of the plugin exclusively relies upon this | |
271 enriched REST API in order to display whole-slide images using the | |
272 `OpenLayers 3 <https://openlayers.org/>`__ JavaScript library. | |
273 | |
274 | |
275 Information about a whole-slide image | |
276 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
277 | |
278 You can check whether a DICOM series associated with some known | |
279 :ref:`Orthanc ID <orthanc-ids>` ``id`` corresponds to a whole-slide | |
280 image by calling the ``/wsi/pyramids/{id}`` URI. A HTTP status code | |
281 404 is returned if the series is *not* a whole-slide image:: | |
282 | |
283 $ curl -v http://localhost:8042/wsi/pyramids/ca2cc2ef-2dd8be12-0a4506ae-d565b7e1-a4ca9068 | |
284 [...] | |
285 < HTTP/1.1 404 Not Found | |
286 | |
287 However, if the identifier corresponds to a valid whole-slide image, | |
288 you will get information about its multi-resolution pyramid, formatted | |
289 using JSON:: | |
290 | |
291 $ curl http://localhost:8042/wsi/pyramids/f0ed5846-2ce36a70-d27bb5d3-6ed9dac2-ee638d85 | |
292 { | |
293 "ID" : "f0ed5846-2ce36a70-d27bb5d3-6ed9dac2-ee638d85", | |
294 "Resolutions" : [ 1, 2, 4, 8, 16 ], | |
295 "Sizes" : [ | |
296 [ 10800, 5400 ], | |
297 [ 5400, 2700 ], | |
298 [ 2700, 1350 ], | |
299 [ 1350, 675 ], | |
300 [ 675, 338 ] | |
301 ], | |
302 "TileHeight" : 512, | |
303 "TileWidth" : 512, | |
304 "TilesCount" : [ | |
305 [ 22, 11 ], | |
306 [ 11, 6 ], | |
307 [ 6, 3 ], | |
308 [ 3, 2 ], | |
309 [ 2, 1 ] | |
310 ], | |
311 "TotalHeight" : 5400, | |
312 "TotalWidth" : 10800 | |
313 } | |
314 | |
315 The size of the finest level of the pyramid is verbatim available from | |
316 this output (in the example above, ``10,800 x 5,400`` pixels), as well | |
317 as the size of each individual tile (``512 x 512`` pixels). The | |
318 ``TilesCount`` gives, for each level of the pyramid (sorted in | |
319 decreasing resolutions), the number of tiles along each dimension: In | |
320 the example above, the coarsest level contains 2 tiles along the X | |
321 axis, and 1 tile along the Y. | |
322 | |
323 Note that the interpretation of the whole-slide image is done | |
324 transparently by the plugin, which frees the user from parsing each | |
325 and every DICOM instance in the series. | |
326 | |
327 The medical information associated with the series or its instances | |
328 can as usual be retrieved using the core :ref:`REST API <rest>` of | |
329 Orthanc. | |
330 | |
331 | |
332 Decoding the individual tiles | |
333 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
334 | |
335 As discussed above, the ``/wsi/pyramids/{id}`` gives information about | |
336 the number of tiles in each level of the multi-resolution pyramid | |
337 associated with series ``id``. | |
338 | |
339 You can then retrieve the individual tiles of each level using the | |
340 ``/wsi/tiles/{id}/{z}/{x}/{y}`` URI, where ``z`` corresponds to the | |
341 level of interest, and (``x``, ``y``) the index of the tile of | |
342 interest at this level. All of these indices start at zero, the level | |
343 ``z=0`` corresponding to the finest level. | |
344 | |
345 For instance, here is how to retrieve the central tile of the finest | |
346 level of the pyramid (that contains ``22 x 11`` tiles in our example):: | |
347 | |
348 $ curl http://localhost:8042/wsi/tiles/f0ed5846-2ce36a70-d27bb5d3-6ed9dac2-ee638d85/0/11/5 > tile.jpg | |
349 $ identify ./tile.jpg | |
350 ./tile.jpg JPEG 512x512 512x512+0+0 8-bit DirectClass 88.5KB 0.000u 0:00.000 | |
351 | |
352 As can be seen, the plugin has returned a JPEG image of size ``512 x | |
353 512``, which corresponds to the size of the tiles in this sample | |
354 image. If trying to access a tile outside the image, the plugin will | |
355 return with an HTTP status code that is not ``200 OK``. Similarly, | |
356 here is how to retrieve a tile at the coarsest level (the pyramid has | |
357 5 levels in our example):: | |
358 | |
359 $ curl http://localhost:8042/wsi/tiles/f0ed5846-2ce36a70-d27bb5d3-6ed9dac2-ee638d85/4/0/0 > tile.jpg | |
360 | |
361 Depending upon the transfer syntax of the DICOM instances, the tile | |
362 might not be encoded using JPEG. Indeed, if the transfer syntax is | |
363 uncompressed (UID ``1.2.840.10008.1.2`` and friends) or JPEG2k | |
364 lossless (UID ``1.2.840.10008.1.2.4.90``), the plugin will | |
365 transparently re-encode the tile to PNG in order to avoid any | |
366 destructive compression. |