|
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
|
|
81
|
21 framework <http://www.orthanc-server.com/static.php?page=wsi>`__.
|
|
|
22
|
|
|
23
|
|
|
24 Compilation
|
|
|
25 -----------
|
|
|
26
|
|
85
|
27 .. highlight:: text
|
|
81
|
28
|
|
|
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
|
|
|
31 for every UNIX-like distribution (including GNU/Linux)::
|
|
|
32
|
|
|
33 # Firstly, compile the command-line tools
|
|
|
34 $ mkdir Applications/Build
|
|
|
35 $ cd Applications/Build
|
|
|
36 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
|
|
|
37 $ make
|
|
85
|
38 # Secondly, compile the viewer plugin
|
|
81
|
39 $ mkdir ../../ViewerPlugin/Build
|
|
|
40 $ cd ../../ViewerPlugin/Build
|
|
|
41 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
|
|
|
42 $ make
|
|
|
43
|
|
|
44 The compilation will produce 3 binaries:
|
|
|
45
|
|
|
46 * ``Applications/Build/OrthancWSIDicomizer``, which contains the DICOM-izer.
|
|
|
47 * ``Applications/Build/OrthancWSIDicomToTiff``, which contains the DICOM-to-TIFF converter.
|
|
82
|
48 * ``ViewerPlugin/Build/OrthancWSI``, which is a shared library containing the viewer plugin for Orthanc.
|
|
81
|
49
|
|
|
50 Note that pre-compiled binaries for Microsoft Windows `are available
|
|
|
51 <http://www.orthanc-server.com/browse.php?path=/whole-slide-imaging>`__.
|
|
|
52
|
|
|
53
|
|
85
|
54 Usage of the plugin
|
|
|
55 -------------------
|
|
81
|
56
|
|
|
57 .. highlight:: json
|
|
|
58
|
|
|
59 You of course first have to :ref:`install Orthanc <compiling>`. Once
|
|
|
60 Orthanc is installed, you must change the :ref:`configuration file
|
|
|
61 <configuration>` to tell Orthanc where it can find the plugin: This is
|
|
85
|
62 done by properly modifying the ``Plugins`` configuration option. You
|
|
|
63 could for instance use the following configuration file under
|
|
|
64 GNU/Linux::
|
|
81
|
65
|
|
|
66 {
|
|
|
67 "Name" : "MyOrthanc",
|
|
|
68 [...]
|
|
|
69 "Plugins" : [
|
|
|
70 "/home/user/orthanc-wsi/ViewerPlugin/Build/libOrthancWSI.so"
|
|
|
71 ]
|
|
|
72 }
|
|
|
73
|
|
|
74 Orthanc must of course be restarted after the modification of its
|
|
|
75 configuration file. The WSI plugin has no specific configuration
|
|
|
76 option.
|
|
|
77
|
|
85
|
78 Once a :ref:`DICOM series <model-world>` is opened using :ref:`Orthanc
|
|
|
79 Explorer <orthanc-explorer>`, a yellow button entitled ``Whole-Slide
|
|
|
80 Imaging Viewer`` will show up for series corresponding to whole-slide
|
|
|
81 images. This button will open the WSI viewer for that particular
|
|
|
82 series. This behavior can be seen on the Orthanc Explorer interface
|
|
|
83 running on our `WSI demonstration server
|
|
|
84 <http://wsi.orthanc-server.com/orthanc/app/explorer.html>`__.
|
|
81
|
85
|
|
|
86
|
|
|
87
|
|
|
88 Command-line tools
|
|
|
89 ------------------
|
|
|
90
|
|
85
|
91 .. highlight:: text
|
|
81
|
92
|
|
|
93 The command-line tools ``OrthancWSIDicomizer`` and
|
|
|
94 ``OrthancWSIDicomToTiff`` provide documentation of all their options
|
|
|
95 if started with the ``--help`` parameter::
|
|
|
96
|
|
85
|
97 $ ./OrthancWSIDicomizer --help
|
|
|
98 $ ./OrthancWSIDicomToTiff --help
|
|
81
|
99
|
|
|
100 In this section, we review the most common usages of these tools.
|
|
|
101
|
|
|
102
|
|
|
103 Transcoding a DICOM image
|
|
|
104 ^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
105
|
|
|
106 The most simple usage consists in converting some whole-slide image to
|
|
|
107 DICOM, then uploading it to Orthanc::
|
|
|
108
|
|
85
|
109 $ ./OrthancWSIDicomizer Source.tif
|
|
81
|
110
|
|
|
111 This command will transcode some `hierarchical, tiled TIFF
|
|
|
112 <https://en.wikipedia.org/wiki/TIFF>`__ image called ``Source.tif``,
|
|
85
|
113 and push the generated DICOM files to the default Orthanc server
|
|
|
114 (running on ``localhost`` and listening to HTTP port ``8042``) using
|
|
|
115 its :ref:`REST API <rest>`. The log of the command will give you the
|
|
|
116 :ref:`identifier of the generated series <orthanc-ids>`, so that you
|
|
|
117 can locate it in Orthanc Explorer. This conversion is fast, as no
|
|
|
118 re-encoding takes place: If the source TIFF image contains JPEG tiles,
|
|
|
119 these tiles will be simply written as such.
|
|
81
|
120
|
|
85
|
121 Obviously, you can specify the parameters of the REST API of your
|
|
|
122 target Orthanc server::
|
|
82
|
123
|
|
85
|
124 $ ./OrthancWSIDicomizer Source.tif --orthanc=http://localhost:8042/ --username=orthanc --password=orthanc
|
|
82
|
125
|
|
85
|
126 It is also possible to write the DICOM instances directly onto some
|
|
82
|
127 folder of the filesystem (the target folder must be existing)::
|
|
|
128
|
|
85
|
129 $ ./OrthancWSIDicomizer Source.tif --folder=/tmp/dicomized/
|
|
82
|
130
|
|
85
|
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.
|
|
82
|
139
|
|
81
|
140
|
|
|
141 Re-encoding a DICOM image
|
|
|
142 ^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
143
|
|
85
|
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``.
|
|
81
|
182
|
|
|
183
|
|
|
184
|
|
|
185 Proprietary file formats
|
|
|
186 ^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
187
|
|
|
188 Out-of-the-box, the DICOM-izer supports standard hierarchical TIFF
|
|
|
189 images. Some commonplace image formats (PNG and JPEG) can be
|
|
|
190 DICOM-ized as well. However, whole-slide images can come in many
|
|
85
|
191 proprietary file formats. To re-encode such images, the DICOM-izer
|
|
|
192 relies upon the `OpenSlide toolbox <http://openslide.org/>`__.
|
|
81
|
193
|
|
|
194 For this feature to work, you have to tell the command-line tool where
|
|
|
195 it can find the OpenSlide shared library. GNU/Linux distributions
|
|
|
196 generally provide packages containing the OpenSlide shared library
|
|
85
|
197 (e.g. under Debian/Ubuntu, simply install the ``libopenslide0``
|
|
|
198 package)::
|
|
81
|
199
|
|
85
|
200 $ ./OrthancWSIDicomizer --openslide=libopenslide.so CMU-1-JP2K-33005.svs
|
|
81
|
201
|
|
85
|
202 Pre-compiled Microsoft Windows binaries of this shared library can be
|
|
81
|
203 found on the `OpenSlide homepage <http://openslide.org/download/>`__::
|
|
|
204
|
|
85
|
205 $ ./OrthancWSIDicomizer --openslide=libopenslide-0.dll CMU-1-JP2K-33005.svs
|
|
81
|
206
|
|
|
207 Note that this operation implies the re-encoding of the source image
|
|
|
208 from the proprietary file format, which is much more time-consuming
|
|
|
209 than simply transcoding a TIFF image.
|
|
|
210
|
|
|
211
|
|
|
212 Specifying a DICOM dataset
|
|
|
213 ^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
214
|
|
85
|
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
|
|
81
|
238
|
|
|
239 Converting DICOM to TIFF
|
|
|
240 ^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
241
|
|
85
|
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
|
|
81
|
262
|
|
|
263 REST API
|
|
|
264 --------
|
|
|
265
|
|
85
|
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.
|
