Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/wsi.rst @ 129:61050d813d74
build wsi
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Thu, 04 Jan 2018 11:06:35 +0100 |
| parents | f8aa67501041 |
| children | 011b01ccf52d |
| 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 | |
| 81 | 21 framework <http://www.orthanc-server.com/static.php?page=wsi>`__. |
| 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 | |
| 34 for every UNIX-like distribution (including GNU/Linux):: | |
| 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 |
| 58 <http://www.orthanc-server.com/browse.php?path=/whole-slide-imaging>`__. | |
| 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 |
| 89 .. highlight:: json | |
| 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 | |
| 116 <http://wsi.orthanc-server.com/orthanc/app/explorer.html>`__. | |
| 81 | 117 |
| 118 | |
| 119 | |
| 120 Command-line tools | |
| 121 ------------------ | |
| 122 | |
| 85 | 123 .. highlight:: text |
| 81 | 124 |
| 125 The command-line tools ``OrthancWSIDicomizer`` and | |
| 126 ``OrthancWSIDicomToTiff`` provide documentation of all their options | |
| 127 if started with the ``--help`` parameter:: | |
| 128 | |
| 85 | 129 $ ./OrthancWSIDicomizer --help |
| 130 $ ./OrthancWSIDicomToTiff --help | |
| 81 | 131 |
| 132 In this section, we review the most common usages of these tools. | |
| 133 | |
| 134 | |
| 135 Transcoding a DICOM image | |
| 136 ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 137 | |
| 138 The most simple usage consists in converting some whole-slide image to | |
| 139 DICOM, then uploading it to Orthanc:: | |
| 140 | |
| 85 | 141 $ ./OrthancWSIDicomizer Source.tif |
| 81 | 142 |
| 143 This command will transcode some `hierarchical, tiled TIFF | |
| 144 <https://en.wikipedia.org/wiki/TIFF>`__ image called ``Source.tif``, | |
| 85 | 145 and push the generated DICOM files to the default Orthanc server |
| 146 (running on ``localhost`` and listening to HTTP port ``8042``) using | |
| 147 its :ref:`REST API <rest>`. The log of the command will give you the | |
| 148 :ref:`identifier of the generated series <orthanc-ids>`, so that you | |
| 149 can locate it in Orthanc Explorer. This conversion is fast, as no | |
| 150 re-encoding takes place: If the source TIFF image contains JPEG tiles, | |
| 151 these tiles will be simply written as such. | |
| 81 | 152 |
| 85 | 153 Obviously, you can specify the parameters of the REST API of your |
| 154 target Orthanc server:: | |
| 82 | 155 |
| 85 | 156 $ ./OrthancWSIDicomizer Source.tif --orthanc=http://localhost:8042/ --username=orthanc --password=orthanc |
| 82 | 157 |
| 85 | 158 It is also possible to write the DICOM instances directly onto some |
| 82 | 159 folder of the filesystem (the target folder must be existing):: |
| 160 | |
| 85 | 161 $ ./OrthancWSIDicomizer Source.tif --folder=/tmp/dicomized/ |
| 82 | 162 |
| 85 | 163 This command will create a set of files entitled like |
| 164 ``/tmp/dicomized/wsi-XXXXXX.dcm``. You can modify this pattern using | |
| 165 the command-line option ``--folder-pattern``. | |
| 166 | |
| 167 By default, the DICOM-izer will spread the output series as a set of | |
| 168 DICOM files whose size stays below 10MB. This prevents the appearance | |
| 169 of huge files, which speeds up further processing. This behavior can | |
| 170 be controlled using the ``--max-size`` command-line option. | |
| 82 | 171 |
| 81 | 172 |
| 173 Re-encoding a DICOM image | |
| 174 ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 175 | |
| 85 | 176 The section above explained how to transcode whole-slide images, |
| 177 without modifying the compression scheme of their individual tiles | |
| 178 (which is most commonly JPEG). You can instruct the DICOM-izer to | |
| 179 re-encode each and every individual tile as follows:: | |
| 180 | |
| 181 $ ./OrthancWSIDicomizer Source.tif --reencode=1 --compression=jpeg2000 | |
| 182 | |
| 183 This example would create a series of DICOM instances encoded using | |
| 184 the JPEG2k transfer syntax (whose UID is ``1.2.840.10008.1.2.4.90``). | |
| 185 As JPEG2k is not natively supported by many Web browsers, the Web | |
| 186 viewer plugin would transparently convert such JPEG2k-encoded tiles to | |
| 187 PNG images. | |
| 188 | |
| 189 It is also possible to re-encode the image so as to reduce disk space | |
| 190 consumption by changing the JPEG quality:: | |
| 191 | |
| 192 $ ./OrthancWSIDicomizer Source.tif --reencode=1 --compression=jpeg --jpeg-quality=10 | |
| 193 | |
| 194 The DICOM-izer also allows to re-generate all the multi-resolution | |
| 195 pyramid. This is extremely importantly to enhance the user experience | |
| 196 of the Web interface, if the source image only features the finest | |
| 197 zoom level of the whole-slide image:: | |
| 198 | |
| 199 $ ./OrthancWSIDicomizer Source.tif --pyramid=1 --smooth=1 | |
| 200 | |
| 201 The number of levels in the pyramid can be controlled using the | |
| 202 ``--levels`` command-line option. The ``--smooth=1`` option tells the | |
| 203 DICOM-izer to apply `Gaussian smoothing | |
| 204 <https://en.wikipedia.org/wiki/Gaussian_blur>`__ when re-scaling the | |
| 205 image, in order to avoid the appearance of aliasing in the | |
| 206 multi-resolution pyramid. This produces nicer images, at the price of | |
| 207 higher computation time. | |
| 208 | |
| 209 All the examples described in this section are obviously much more | |
| 210 CPU-intensive than simple transcoding. The DICOM-izer takes advantage | |
| 211 in multi-threading to reduce the computation time. By default, it will | |
| 212 use half the number of logical CPU cores that are available. This | |
| 213 behavior can be fine-tuned using command-line option ``--threads``. | |
| 81 | 214 |
| 215 | |
| 216 | |
| 217 Proprietary file formats | |
| 218 ^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 219 | |
| 220 Out-of-the-box, the DICOM-izer supports standard hierarchical TIFF | |
| 221 images. Some commonplace image formats (PNG and JPEG) can be | |
| 222 DICOM-ized as well. However, whole-slide images can come in many | |
| 85 | 223 proprietary file formats. To re-encode such images, the DICOM-izer |
| 224 relies upon the `OpenSlide toolbox <http://openslide.org/>`__. | |
| 81 | 225 |
| 226 For this feature to work, you have to tell the command-line tool where | |
| 227 it can find the OpenSlide shared library. GNU/Linux distributions | |
| 228 generally provide packages containing the OpenSlide shared library | |
| 85 | 229 (e.g. under Debian/Ubuntu, simply install the ``libopenslide0`` |
| 230 package):: | |
| 81 | 231 |
| 85 | 232 $ ./OrthancWSIDicomizer --openslide=libopenslide.so CMU-1-JP2K-33005.svs |
| 81 | 233 |
| 85 | 234 Pre-compiled Microsoft Windows binaries of this shared library can be |
|
87
f8aa67501041
extra info for libOpenSlide Windows package
Alain Mazy <alain@mazy.be>
parents:
85
diff
changeset
|
235 found on the `OpenSlide homepage <http://openslide.org/download/>`__ (Note that |
|
f8aa67501041
extra info for libOpenSlide Windows package
Alain Mazy <alain@mazy.be>
parents:
85
diff
changeset
|
236 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
|
237 executable):: |
| 81 | 238 |
| 85 | 239 $ ./OrthancWSIDicomizer --openslide=libopenslide-0.dll CMU-1-JP2K-33005.svs |
| 81 | 240 |
| 241 Note that this operation implies the re-encoding of the source image | |
| 242 from the proprietary file format, which is much more time-consuming | |
| 243 than simply transcoding a TIFF image. | |
| 244 | |
| 245 | |
| 246 Specifying a DICOM dataset | |
| 247 ^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 248 | |
| 85 | 249 So far, we have only been discussing the whole-slide image by itself, |
| 250 and not the :ref:`medical information <dicom-tags>` that is associated | |
| 251 with each DICOM file. The DICOM tags that must be embedded inside the | |
| 252 generated DICOM series can be specified using the user-friendly JSON | |
| 253 file format. You would first generate a minimal, sample JSON dataset | |
| 254 as follows:: | |
| 255 | |
| 256 $ ./OrthancWSIDicomizer --sample-dataset > dataset.json | |
| 257 | |
| 258 Secondly, you would edit the just-generated ``dataset.json`` file | |
| 259 using any text editor (or any script interfaced with your RIS), so as | |
| 260 to encode medical information associated with the image | |
| 261 acquisition. Finally, tell the DICOM-izer where it can find the | |
| 262 dataset when re-encoding or transcoding the image:: | |
| 263 | |
| 264 $ ./OrthancWSIDicomizer Source.tif --dataset=dataset.json | |
| 265 | |
| 266 Note that it is always a good idea to check whether all the required | |
| 267 DICOM tags have been properly provided, e.g. by running the | |
| 268 ``dciodvfy`` command-line tool provided by `David Clunie | |
| 269 <http://www.dclunie.com/dicom3tools.html>`__ that checks the | |
| 270 compliance of DICOM files. | |
| 271 | |
| 81 | 272 |
| 273 Converting DICOM to TIFF | |
| 274 ^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 275 | |
| 85 | 276 The whole-slide imaging framework for Orthanc also provides a |
| 277 command-line tool that converts some DICOM series, as a standard | |
| 278 hierarchical, tiled TIFF image. This is important if you wish to | |
| 279 export some DICOM file to a framework that does not support DICOM | |
| 280 Supplement 145. | |
| 281 | |
| 282 Here is how you would convert a whole-slide image stored in the | |
| 283 default Orthanc server:: | |
| 284 | |
| 285 $ ./OrthancWSIDicomToTiff fdf53e42-06d7377a-c24c59fd-3704e72d-f4c75b68 Target.tif | |
| 286 | |
| 287 You just have to provide the :ref:`Orthanc identifier <orthanc-ids>` | |
| 288 of the series of interest (that can be retrieved using :ref:`Orthanc | |
| 289 Explorer <orthanc-explorer>` or the :ref:`REST API <rest>`), and the | |
| 290 path to the target TIFF file. | |
| 291 | |
| 292 Similarly to the DICOM-izer, the command-line options ``--orthanc``, | |
| 293 ``--username`` and ``--password`` can be used to specify the | |
| 294 parameters of your Orthanc server. | |
| 295 | |
| 81 | 296 |
| 297 REST API | |
| 298 -------- | |
| 299 | |
| 85 | 300 Besides providing an user interface, the plugin for whole-slide |
| 301 imaging also enrich the :ref:`REST API <rest>` of Orthanc with some | |
| 302 new URIs, that are described in this section. | |
| 303 | |
| 304 Note that the Web interface of the plugin exclusively relies upon this | |
| 305 enriched REST API in order to display whole-slide images using the | |
| 306 `OpenLayers 3 <https://openlayers.org/>`__ JavaScript library. | |
| 307 | |
| 308 | |
| 309 Information about a whole-slide image | |
| 310 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 311 | |
| 312 You can check whether a DICOM series associated with some known | |
| 313 :ref:`Orthanc ID <orthanc-ids>` ``id`` corresponds to a whole-slide | |
| 314 image by calling the ``/wsi/pyramids/{id}`` URI. A HTTP status code | |
| 315 404 is returned if the series is *not* a whole-slide image:: | |
| 316 | |
| 317 $ curl -v http://localhost:8042/wsi/pyramids/ca2cc2ef-2dd8be12-0a4506ae-d565b7e1-a4ca9068 | |
| 318 [...] | |
| 319 < HTTP/1.1 404 Not Found | |
| 320 | |
| 321 However, if the identifier corresponds to a valid whole-slide image, | |
| 322 you will get information about its multi-resolution pyramid, formatted | |
| 323 using JSON:: | |
| 324 | |
| 325 $ curl http://localhost:8042/wsi/pyramids/f0ed5846-2ce36a70-d27bb5d3-6ed9dac2-ee638d85 | |
| 326 { | |
| 327 "ID" : "f0ed5846-2ce36a70-d27bb5d3-6ed9dac2-ee638d85", | |
| 328 "Resolutions" : [ 1, 2, 4, 8, 16 ], | |
| 329 "Sizes" : [ | |
| 330 [ 10800, 5400 ], | |
| 331 [ 5400, 2700 ], | |
| 332 [ 2700, 1350 ], | |
| 333 [ 1350, 675 ], | |
| 334 [ 675, 338 ] | |
| 335 ], | |
| 336 "TileHeight" : 512, | |
| 337 "TileWidth" : 512, | |
| 338 "TilesCount" : [ | |
| 339 [ 22, 11 ], | |
| 340 [ 11, 6 ], | |
| 341 [ 6, 3 ], | |
| 342 [ 3, 2 ], | |
| 343 [ 2, 1 ] | |
| 344 ], | |
| 345 "TotalHeight" : 5400, | |
| 346 "TotalWidth" : 10800 | |
| 347 } | |
| 348 | |
| 349 The size of the finest level of the pyramid is verbatim available from | |
| 350 this output (in the example above, ``10,800 x 5,400`` pixels), as well | |
| 351 as the size of each individual tile (``512 x 512`` pixels). The | |
| 352 ``TilesCount`` gives, for each level of the pyramid (sorted in | |
| 353 decreasing resolutions), the number of tiles along each dimension: In | |
| 354 the example above, the coarsest level contains 2 tiles along the X | |
| 355 axis, and 1 tile along the Y. | |
| 356 | |
| 357 Note that the interpretation of the whole-slide image is done | |
| 358 transparently by the plugin, which frees the user from parsing each | |
| 359 and every DICOM instance in the series. | |
| 360 | |
| 361 The medical information associated with the series or its instances | |
| 362 can as usual be retrieved using the core :ref:`REST API <rest>` of | |
| 363 Orthanc. | |
| 364 | |
| 365 | |
| 366 Decoding the individual tiles | |
| 367 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 368 | |
| 369 As discussed above, the ``/wsi/pyramids/{id}`` gives information about | |
| 370 the number of tiles in each level of the multi-resolution pyramid | |
| 371 associated with series ``id``. | |
| 372 | |
| 373 You can then retrieve the individual tiles of each level using the | |
| 374 ``/wsi/tiles/{id}/{z}/{x}/{y}`` URI, where ``z`` corresponds to the | |
| 375 level of interest, and (``x``, ``y``) the index of the tile of | |
| 376 interest at this level. All of these indices start at zero, the level | |
| 377 ``z=0`` corresponding to the finest level. | |
| 378 | |
| 379 For instance, here is how to retrieve the central tile of the finest | |
| 380 level of the pyramid (that contains ``22 x 11`` tiles in our example):: | |
| 381 | |
| 382 $ curl http://localhost:8042/wsi/tiles/f0ed5846-2ce36a70-d27bb5d3-6ed9dac2-ee638d85/0/11/5 > tile.jpg | |
| 383 $ identify ./tile.jpg | |
| 384 ./tile.jpg JPEG 512x512 512x512+0+0 8-bit DirectClass 88.5KB 0.000u 0:00.000 | |
| 385 | |
| 386 As can be seen, the plugin has returned a JPEG image of size ``512 x | |
| 387 512``, which corresponds to the size of the tiles in this sample | |
| 388 image. If trying to access a tile outside the image, the plugin will | |
| 389 return with an HTTP status code that is not ``200 OK``. Similarly, | |
| 390 here is how to retrieve a tile at the coarsest level (the pyramid has | |
| 391 5 levels in our example):: | |
| 392 | |
| 393 $ curl http://localhost:8042/wsi/tiles/f0ed5846-2ce36a70-d27bb5d3-6ed9dac2-ee638d85/4/0/0 > tile.jpg | |
| 394 | |
| 395 Depending upon the transfer syntax of the DICOM instances, the tile | |
| 396 might not be encoded using JPEG. Indeed, if the transfer syntax is | |
| 397 uncompressed (UID ``1.2.840.10008.1.2`` and friends) or JPEG2k | |
| 398 lossless (UID ``1.2.840.10008.1.2.4.90``), the plugin will | |
| 399 transparently re-encode the tile to PNG in order to avoid any | |
| 400 destructive compression. |