Mercurial > hg > orthanc-stone

comparison Applications/Samples/README.md @ 1538:d1806b4e4839

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
moving OrthancStone/Samples/ as Applications/Samples/
author Sebastien Jodogne <s.jodogne@gmail.com>
date Tue, 11 Aug 2020 13:24:38 +0200
parents OrthancStone/Samples/README.md@4c4b267e4004
children 9b69970fbdb5
comparison
equal deleted inserted replaced
1537:de8cf5859e84 1538:d1806b4e4839
1 General
2 =======
3 These samples assume that a recent version of Orthanc is checked out in an
4 `orthanc` folder next to the `orthanc-stone` folder. Let's call the top folder
5 the `devroot` folder. This name does not matter and is not used anywhere.
6
7 Here's the directory layout that we suggest:
8
9 ```
10 devroot/
11 |
12 +- orthanc/
13 |
14 +- orthanc-stone/
15 |
16 ...
17 ```
18
19 Orthanc can be retrieved with:
20 ```
21 hg clone https://hg.orthanc-server.com/orthanc
22 ```
23
24 Furthermore, the samples usually assume that an Orthanc is running locally,
25 without authentication, on port 8042. The samples can easily be tweaked if
26 your setup is different.
27
28 When Dicom resources are to be displayed, their IDs can be supplied in the
29 various ways suitable for the platform (command-line arguments, URL parameters
30 or through the GUI)
31
32
33 This repo contains two sample projects:
34
35 SingleFrameViewer
36 -----------------
37
38 This sample application displays a single frame of a Dicom instance that can
39 be loaded from Orthanc, either by using the Orthanc REST API or through the
40 Dicomweb server functionality of Orthanc.
41
42 RtViewer
43 --------
44
45 This sample application displays set of Radiotherapy data:
46 - a CT scan
47 - an RT-Dose
48 - an RT-Struct
49
50 The WebAssembly version displays 3 viewports with MPR data
51 while the SDL sample displays a single viewport.
52
53
54 WebAssembly samples
55 ===================
56
57 Building the WebAssembly samples require the Emscripten SDK
58 (https://emscripten.org/). This SDK goes far beyond the simple compilation to
59 the wasm (Web Assembly) bytecode and provides a comprehensive library that
60 eases porting native C and C++ programs and libraries. The Emscripten SDK also
61 makes it easy to generate the companion Javascript files requires to use a
62 wasm module in a web application.
63
64 Although Emscripten runs on all major platforms, Stone of Orthanc is developed
65 and tested with the Linux version of Emscripten.
66
67 Emscripten runs perfectly fine under the Windows Subsystem for Linux (that is
68 the environment used quite often by the Stone of Orthanc team)
69
70 **Important note:** The following examples **and the build scripts** will
71 assume that you have installed the Emscripten SDK in `~/apps/emsdk`.
72
73 The following packages should get you going (a Debian-like distribution such
74 as Debian or Ubuntu is assumed)
75
76 ```
77 sudo apt-get update
78 sudo apt-get install -y build-essential curl wget git python cmake pkg-config
79 sudo apt-get install -y mercurial unzip npm ninja-build p7zip-full gettext-base
80 ```
81
82 To build the Wasm samples, just launch the `build-wasm-samples.sh` script from
83 this folder. Optionaly, you can pass the build type as an argument.
84 We suggest that you do *not* use the `Debug` configuration unless you really
85 need it, for the additional checks that are made will lead to a very long
86 build time and much slower execution (more severe than with a native non-wasm
87 target)
88
89 In order to run the sample, you may serve it with the ServeFolders plugin.
90 You can i.e: add such a section in your orthanc configuration file:
91
92 ```
93 {
94 "Plugins" : ["LibServeFolders.so],
95 "ServeFolders" : {
96 "/single-frame-viewer" : "..../out/install-stone-wasm-samples-RelWithDebInfo/SingleFrameViewer",
97 "/rt-viewer": "..../out/install-stone-wasm-samples-RelWithDebInfo/RtViewer"
98 }
99 }
100 ```
101
102 You'll then be able to open the single-frame-viewer demo at `http://localhost:8042/single-frame-viewer/index.html`
103
104 The rt-viewer demo at
105 `http://localhost:8044/rt-viewer/index.html?ctseries=a04ecf01-79b2fc33-58239f7e-ad9db983-28e81afa&rtdose=eac822ef-a395f94e-e8121fe0-8411fef8-1f7bffad&rtstruct=54460695-ba3885ee-ddf61ac0-f028e31d-a6e474d9`. Note that you must provide 3 ids in the url:
106
107 - the CT series Orthanc ID
108 - the RT-Dose instance Orthanc ID
109 - the RT-Struct instance Orthanc ID
110
111
112 RtViewer
113 -----------------
114
115 This sample application displays three MPR views of a CT+RTDOSE+RTSTRUCT dataset, loaded from Orthanc. The Orthanc IDs of the dataset must be supplied as URL parameters like:
116
117 ```
118 http://localhost:9979/stone-rtviewer/index.html?loglevel=info&ctseries=a04ecf01-79b2fc33-58239f7e-ad9db983-28e81afa&rtdose=830a69ff-8e4b5ee3-b7f966c8-bccc20fb-d322dceb&rtstruct=54460695-ba3885ee-ddf61ac0-f028e31d-a6e474d9
119 ```
120
121 (notice the loglevel parameter that can be `warning`, `info` or `trace`, in increasing verbosity order)
122
123 This sample uses plain Javascript and requires the
124 Emscripten toolchain and cmake, in addition to a few standard packages.
125
126 To build it, just launch the `build-wasm-RtViewer.sh` script from
127 this folder. Optionaly, you can pass the build type as an argument.
128 We suggest that you do *not* use the `Debug` configuration unless you really
129 need it, for the additional checks that are made will lead to a very long
130 build time and much slower execution (more severe than with a native non-wasm
131 target)
132
133 In order to run the sample, you may serve it with the ServeFolders plugin.
134 You can i.e: add such a section in your orthanc configuration file:
135
136 ```
137 {
138 "Plugins" : ["LibServeFolders.so],
139 "ServeFolders" : {
140 "/rt-viewer" : "..../out/install-stone-wasm-RtViewer-RelWithDebInfo"
141 }
142 }
143 ```
144
145 You'll then be able to open the demo at `http://localhost:8042/rt-viewer/index.html`
146
147
148 RtViewerPlugin
149 ---------------
150 This C++ plugin allows to extend the Orthanc Explorer to add a button labeled "Stone RT Viewer"
151 in the series page.
152
153 It also embeds and serves the RT Viewer files and is thus a standalone way of using this viewer.
154
155 Please note that building this plugin requires that the RtViewer be built inside the wasm-binaries
156 folder of the repo.
157
158 This will automatically be the case if you use the `<REPO-ROOT>/OrthancStone/Samples/WebAssembly/docker-build.sh` script.
159
160 If you use the `build-wasm-samples.sh` script above, you will have the copy `RtViewer` **folder**
161 from `<REPO-ROOT>/out/install-stone-wasm-RtViewer-RelWithDebInfo` to `<REPO-ROOT>/wasm-binaries/`.
162
163 TL;DR: Build like this (assuming `~/orthanc-stone` is the repo ):
164
165 ```
166 ~/orthanc-stone/OrthancStone/Samples/WebAssembly/docker-build.sh
167 ~/orthanc-stone/OrthancStone/Samples/RtViewerPlugin/docker-build.sh
168 ```
169
170 Once this is done, the plugin can be found in:
171
172 ```
173 ~/orthanc-stone/wasm-binaries/share/orthanc/plugins/libRtViewerPlugin.so
174 ```
175
176 Add this path to the `"Plugins"` section of your Orthanc configuration, start Orthanc, and you
177 should now see a "Stone MPR RT Viewer" button in the Orthanc Explorer, at the *series* level.
178
179 Open it on a CT series, and the RTSTRUCT and RTDOSE series of the same study will be loaded in
180 the viewer.
181
182 Native samples
183 =================
184
185 ### Windows build
186
187 Here's how to build the SdlSimpleViewer example using Visual Studio 2019
188 (the shell is Powershell, but the legacy shell can also be used with some
189 tweaks). This example is meant to be launched from the folder above
190 orthanc-stone.
191
192 ```
193 # create the build folder and navigate to it
194 $buildDir = "build-stone-sdlviewer-msvc16-x64"
195
196 if (-not (Test-Path $buildDir)) {
197 mkdir -p $buildDir | Out-Null
198 }
199
200 cd $buildDir
201
202 # perform the configuration
203 cmake -G "Visual Studio 16 2019" -A x64 `
204 -DMSVC_MULTIPLE_PROCESSES=ON `
205 -DALLOW_DOWNLOADS=ON `
206 -DSTATIC_BUILD=ON `
207 -DOPENSSL_NO_CAPIENG=ON `
208 ../orthanc-stone/OrthancStone/Samples/Sdl
209
210 $solutionPath = ls -filter *.sln
211 Write-Host "Solution file(s) available at: $solutionPath"
212 ```
213
214 The initial configuration step will be quite lengthy, for CMake needs to
215 setup its internal cache based on your environment and build tools.
216
217 Subsequent runs will be several orders of magnitude faster!
218
219 One the solution (.sln) file is ready, you can open it using the Visual Studio
220 IDE and choose Build --> Build solution.
221
222 An alternative is to execute `cmake --build .` in the build folder created by
223 the script.
224
225 In order to run the sample, make sure you've an Orthanc server running i.e. on
226 port 8042 and launch:
227
228 ```
229 ./SdlSimpleViewer --orthanc http://localhost:8042 --instance 7fc84013-abef174e-3354ca83-b9cdb2a4-f1a74368
230
231 ./RtViewerSdl --orthanc http://localhost:8042 --ctseries a04ecf01-79b2fc33-58239f7e-ad9db983-28e81afa --rtdose 830a69ff-8e4b5ee3-b7f966c8-bccc20fb-d322dceb --rtstruct 54460695-ba3885ee-ddf61ac0-f028e31d-a6e474d9
232 ```
233
234 RtViewer
235 ---------------
236
237 ### Windows build
238
239 Here's how to build the SdlSimpleViewer example using Visual Studio 2019
240 (the shell is Powershell, but the legacy shell can also be used with some
241 tweaks). This example is meant to be launched from the folder above
242 orthanc-stone.
243
244 ```
245 $buildRootDir = "out"
246 $buildDirName = "build-stone-sdl-RtViewer-msvc16-x64"
247 $buildDir = Join-Path -Path $buildRootDir -ChildPath $buildDirName
248
249 if (-not (Test-Path $buildDir)) {
250 mkdir -p $buildDir | Out-Null
251 }
252
253 cd $buildDir
254
255 cmake -G "Visual Studio 16 2019" -A x64 `
256 -DMSVC_MULTIPLE_PROCESSES=ON `
257 -DALLOW_DOWNLOADS=ON `
258 -DSTATIC_BUILD=ON `
259 -DOPENSSL_NO_CAPIENG=ON `
260 ../../orthanc-stone/OrthancStone/Samples/Sdl/RtViewer
261 ```
262
263 Executing `cmake --build .` in the build folder will launch the Microsoft
264 builder on the solution.
265
266 Alternatively, you can open and build the solution using Visual Studio 2019.
267