Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/wsi.rst @ 85:13dd3f20a00a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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.