Mercurial > hg > orthanc-book
comparison Sphinx/source/plugins/wsi.rst @ 81:4eea0dc5f071
documenting wsi
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Thu, 15 Dec 2016 18:20:59 +0100 |
parents | 895b8ad53454 |
children | 0752d8518623 |
comparison
equal
deleted
inserted
replaced
80:0e8b85acf3e0 | 81:4eea0dc5f071 |
---|---|
1 .. _wsi: | 1 .. _wsi: |
2 | 2 |
3 | 3 |
4 Whole-Slide Imaging | 4 Whole-Slide Microscopic Imaging |
5 =================== | 5 =============================== |
6 | 6 |
7 .. contents:: | 7 .. contents:: |
8 | 8 |
9 This **official** plugin extends Orthanc with a Web viewer of whole-slide | 9 The Orthanc project provides three **official tools** to support DICOM |
10 images for digital pathology. | 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 | |
18 in Orthanc, to a standard hierarchical TIFF image. | |
11 | 19 |
12 For general information, check out the `official homepage of the | 20 For general information, check out the `official homepage of the |
13 framework <http://www.orthanc-server.com/static.php?page=wsi>`__. This | 21 framework <http://www.orthanc-server.com/static.php?page=wsi>`__. |
14 page is work-in-progress. | 22 |
23 | |
24 Compilation | |
25 ----------- | |
26 | |
27 .. highlight:: bash | |
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 | |
38 # Secondly, compile the plugin | |
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. | |
48 * ``ViewerPlugin/Build/OrthancWSI``, which is a shared library containing the plugin for Orthanc. | |
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 | |
54 Installation of the plugin | |
55 -------------------------- | |
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 | |
62 done by properly modifying the ``Plugins`` option. You could for | |
63 instance use the following configuration file:: | |
64 | |
65 { | |
66 "Name" : "MyOrthanc", | |
67 [...] | |
68 "Plugins" : [ | |
69 "/home/user/orthanc-wsi/ViewerPlugin/Build/libOrthancWSI.so" | |
70 ] | |
71 } | |
72 | |
73 Orthanc must of course be restarted after the modification of its | |
74 configuration file. The WSI plugin has no specific configuration | |
75 option. | |
76 | |
77 Once a :ref:`DICOM series <model-world>` is opened using Orthanc | |
78 Explorer, a yellow button entitled ``Whole-Slide Imaging Viewer`` will | |
79 show up for whole-slide images. It will open the WSI viewer for that | |
80 particular series. This behavior can be seen on the Orthanc Explorer | |
81 running on our `WSI demonstration server | |
82 <http://wsi.orthanc-server.com/orthanc/app/explorer.html>`__. | |
83 | |
84 | |
85 | |
86 Command-line tools | |
87 ------------------ | |
88 | |
89 .. highlight:: bash | |
90 | |
91 The command-line tools ``OrthancWSIDicomizer`` and | |
92 ``OrthancWSIDicomToTiff`` provide documentation of all their options | |
93 if started with the ``--help`` parameter:: | |
94 | |
95 $ OrthancWSIDicomizer --help | |
96 $ OrthancWSIDicomToTiff --help | |
97 | |
98 In this section, we review the most common usages of these tools. | |
99 | |
100 | |
101 Transcoding a DICOM image | |
102 ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
103 | |
104 The most simple usage consists in converting some whole-slide image to | |
105 DICOM, then uploading it to Orthanc:: | |
106 | |
107 $ OrthancWSIDicomizer Source.tif | |
108 | |
109 This command will transcode some `hierarchical, tiled TIFF | |
110 <https://en.wikipedia.org/wiki/TIFF>`__ image called ``Source.tif``, | |
111 and push the output DICOM files to the default Orthanc server (running | |
112 on ``localhost`` and listening to HTTP port ``8042``) using its | |
113 :ref:`REST API <rest>`. This operation is fast, as no re-encoding | |
114 takes place: If the source TIFF image contains JPEG tiles, these tiles | |
115 will be written as such. | |
116 | |
117 | |
118 Re-encoding a DICOM image | |
119 ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
120 | |
121 | |
122 | |
123 | |
124 Proprietary file formats | |
125 ^^^^^^^^^^^^^^^^^^^^^^^^ | |
126 | |
127 Out-of-the-box, the DICOM-izer supports standard hierarchical TIFF | |
128 images. Some commonplace image formats (PNG and JPEG) can be | |
129 DICOM-ized as well. However, whole-slide images can come in many | |
130 proprietary file formats. To transcode such images, the DICOM-izer | |
131 relies upon the `OpenSlide toolbox <http://openslide.org/>`__. | |
132 | |
133 For this feature to work, you have to tell the command-line tool where | |
134 it can find the OpenSlide shared library. GNU/Linux distributions | |
135 generally provide packages containing the OpenSlide shared library | |
136 (under Debian/Ubuntu, simply install the ``libopenslide0`` package):: | |
137 | |
138 $ OrthancWSIDicomizer --openslide=libopenslide.so CMU-1-JP2K-33005.svs | |
139 | |
140 Precompiled Microsoft Windows binaries of this shared library can be | |
141 found on the `OpenSlide homepage <http://openslide.org/download/>`__:: | |
142 | |
143 $ OrthancWSIDicomizer --openslide=libopenslide-0.dll CMU-1-JP2K-33005.svs | |
144 | |
145 Note that this operation implies the re-encoding of the source image | |
146 from the proprietary file format, which is much more time-consuming | |
147 than simply transcoding a TIFF image. | |
148 | |
149 | |
150 | |
151 Specifying a DICOM dataset | |
152 ^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
153 | |
154 | |
155 Converting DICOM to TIFF | |
156 ^^^^^^^^^^^^^^^^^^^^^^^^ | |
157 | |
158 | |
159 REST API | |
160 -------- | |
161 |