--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Applications/Samples/README.md	Tue Aug 11 13:24:38 2020 +0200
@@ -0,0 +1,267 @@
+General
+=======
+These samples assume that a recent version of Orthanc is checked out in an
+`orthanc` folder next to the `orthanc-stone` folder. Let's call the top folder
+the `devroot` folder. This name does not matter and is not used anywhere.
+
+Here's the directory layout that we suggest:
+
+```
+devroot/
+ |
+ +- orthanc/
+ |
+ +- orthanc-stone/
+ |
+ ...
+```
+
+ Orthanc can be retrieved with:
+ ```
+ hg clone https://hg.orthanc-server.com/orthanc
+ ```
+
+Furthermore, the samples usually assume that an Orthanc is running locally,
+without authentication, on port 8042. The samples can easily be tweaked if 
+your setup is different.
+
+When Dicom resources are to be displayed, their IDs can be supplied in the 
+various ways suitable for the platform (command-line arguments, URL parameters
+or through the GUI)
+
+
+This repo contains two sample projects:
+
+SingleFrameViewer
+-----------------
+
+This sample application displays a single frame of a Dicom instance that can
+be loaded from Orthanc, either by using the Orthanc REST API or through the 
+Dicomweb server functionality of Orthanc.
+
+RtViewer
+--------
+
+This sample application displays set of Radiotherapy data:
+- a CT scan
+- an RT-Dose
+- an RT-Struct
+
+The WebAssembly version displays 3 viewports with MPR data
+while the SDL sample displays a single viewport.
+
+ 
+WebAssembly samples
+===================
+
+Building the WebAssembly samples require the Emscripten SDK 
+(https://emscripten.org/). This SDK goes far beyond the simple compilation to
+the wasm (Web Assembly) bytecode and provides a comprehensive library that 
+eases porting native C and C++ programs and libraries. The Emscripten SDK also
+makes it easy to generate the companion Javascript files requires to use a 
+wasm module in a web application.
+
+Although Emscripten runs on all major platforms, Stone of Orthanc is developed
+and tested with the Linux version of Emscripten.
+
+Emscripten runs perfectly fine under the Windows Subsystem for Linux (that is
+the environment used quite often by the Stone of Orthanc team)
+
+**Important note:** The following examples **and the build scripts** will 
+assume that you have installed the Emscripten SDK in `~/apps/emsdk`.
+
+The following packages should get you going (a Debian-like distribution such 
+as Debian or Ubuntu is assumed)
+
+```
+sudo apt-get update 
+sudo apt-get install -y build-essential curl wget git python cmake pkg-config
+sudo apt-get install -y mercurial unzip npm ninja-build p7zip-full gettext-base 
+```
+
+To build the Wasm samples, just launch the `build-wasm-samples.sh` script from
+this folder.  Optionaly, you can pass the build type as an argument.
+We suggest that you do *not* use the `Debug` configuration unless you really 
+need it, for the additional checks that are made will lead to a very long 
+build time and much slower execution (more severe than with a native non-wasm
+target)
+
+In order to run the sample, you may serve it with the ServeFolders plugin.
+You can i.e: add such a section in your orthanc configuration file:
+
+```
+{
+  "Plugins" : ["LibServeFolders.so],
+  "ServeFolders" : {
+    "/single-frame-viewer" : "..../out/install-stone-wasm-samples-RelWithDebInfo/SingleFrameViewer",
+    "/rt-viewer": "..../out/install-stone-wasm-samples-RelWithDebInfo/RtViewer"
+  }
+}
+```
+
+You'll then be able to open the single-frame-viewer demo at `http://localhost:8042/single-frame-viewer/index.html` 
+
+The rt-viewer demo at
+`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:
+
+- the CT series Orthanc ID
+- the RT-Dose instance Orthanc ID
+- the RT-Struct instance Orthanc ID
+
+
+RtViewer
+-----------------
+
+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:
+
+```
+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
+```
+
+(notice the loglevel parameter that can be `warning`, `info` or `trace`, in increasing verbosity order)
+
+This sample uses plain Javascript and requires the 
+Emscripten toolchain and cmake, in addition to a few standard packages.
+
+To build it, just launch the `build-wasm-RtViewer.sh` script from
+this folder.  Optionaly, you can pass the build type as an argument.
+We suggest that you do *not* use the `Debug` configuration unless you really 
+need it, for the additional checks that are made will lead to a very long 
+build time and much slower execution (more severe than with a native non-wasm
+target)
+
+In order to run the sample, you may serve it with the ServeFolders plugin.
+You can i.e: add such a section in your orthanc configuration file:
+
+```
+{
+  "Plugins" : ["LibServeFolders.so],
+  "ServeFolders" : {
+    "/rt-viewer" : "..../out/install-stone-wasm-RtViewer-RelWithDebInfo"
+  }
+}
+```
+
+You'll then be able to open the demo at `http://localhost:8042/rt-viewer/index.html`
+
+
+RtViewerPlugin
+---------------
+This C++ plugin allows to extend the Orthanc Explorer to add a button labeled "Stone RT Viewer" 
+in the series page. 
+
+It also embeds and serves the RT Viewer files and is thus a standalone way of using this viewer.
+
+Please note that building this plugin requires that the RtViewer be built inside the wasm-binaries 
+folder of the repo.
+
+This will automatically be the case if you use the `<REPO-ROOT>/OrthancStone/Samples/WebAssembly/docker-build.sh` script.
+
+If you use the `build-wasm-samples.sh` script above, you will have the copy `RtViewer` **folder**
+from `<REPO-ROOT>/out/install-stone-wasm-RtViewer-RelWithDebInfo` to `<REPO-ROOT>/wasm-binaries/`.
+
+TL;DR: Build like this (assuming `~/orthanc-stone` is the repo ):
+
+```
+~/orthanc-stone/OrthancStone/Samples/WebAssembly/docker-build.sh
+~/orthanc-stone/OrthancStone/Samples/RtViewerPlugin/docker-build.sh
+```
+
+Once this is done, the plugin can be found in:
+
+```
+~/orthanc-stone/wasm-binaries/share/orthanc/plugins/libRtViewerPlugin.so
+```
+
+Add this path to the `"Plugins"` section of your Orthanc configuration, start Orthanc, and you 
+should now see a "Stone MPR RT Viewer" button in the Orthanc Explorer, at the *series* level.
+
+Open it on a CT series, and the RTSTRUCT and RTDOSE series of the same study will be loaded in
+the viewer.
+
+Native samples
+=================
+
+### Windows build 
+
+Here's how to build the SdlSimpleViewer example using Visual Studio 2019
+(the shell is Powershell, but the legacy shell can also be used with some 
+tweaks). This example is meant to be launched from the folder above 
+orthanc-stone.
+
+```
+  # create the build folder and navigate to it
+  $buildDir = "build-stone-sdlviewer-msvc16-x64"
+
+  if (-not (Test-Path $buildDir)) {
+    mkdir -p $buildDir | Out-Null
+  }
+  
+  cd $buildDir
+  
+  # perform the configuration
+  cmake -G "Visual Studio 16 2019" -A x64 `
+    -DMSVC_MULTIPLE_PROCESSES=ON `
+    -DALLOW_DOWNLOADS=ON `
+    -DSTATIC_BUILD=ON `
+    -DOPENSSL_NO_CAPIENG=ON `
+    ../orthanc-stone/OrthancStone/Samples/Sdl
+  
+  $solutionPath = ls -filter *.sln
+  Write-Host "Solution file(s) available at: $solutionPath"
+```
+
+The initial configuration step will be quite lengthy, for CMake needs to 
+setup its internal cache based on your environment and build tools.
+
+Subsequent runs will be several orders of magnitude faster!
+
+One the solution (.sln) file is ready, you can open it using the Visual Studio
+IDE and choose Build --> Build solution.
+
+An alternative is to execute `cmake --build .` in the build folder created by
+the script.
+
+In order to run the sample, make sure you've an Orthanc server running i.e. on 
+port 8042 and launch:
+
+```
+./SdlSimpleViewer --orthanc http://localhost:8042 --instance 7fc84013-abef174e-3354ca83-b9cdb2a4-f1a74368
+
+./RtViewerSdl --orthanc http://localhost:8042 --ctseries a04ecf01-79b2fc33-58239f7e-ad9db983-28e81afa --rtdose 830a69ff-8e4b5ee3-b7f966c8-bccc20fb-d322dceb --rtstruct 54460695-ba3885ee-ddf61ac0-f028e31d-a6e474d9
+```
+
+RtViewer
+---------------
+
+### Windows build 
+
+Here's how to build the SdlSimpleViewer example using Visual Studio 2019
+(the shell is Powershell, but the legacy shell can also be used with some 
+tweaks). This example is meant to be launched from the folder above 
+orthanc-stone.
+
+```
+  $buildRootDir = "out"
+  $buildDirName = "build-stone-sdl-RtViewer-msvc16-x64"
+  $buildDir = Join-Path -Path $buildRootDir -ChildPath $buildDirName
+
+  if (-not (Test-Path $buildDir)) {
+    mkdir -p $buildDir | Out-Null
+  }
+  
+  cd $buildDir
+  
+  cmake -G "Visual Studio 16 2019" -A x64 `
+    -DMSVC_MULTIPLE_PROCESSES=ON `
+    -DALLOW_DOWNLOADS=ON `
+    -DSTATIC_BUILD=ON `
+    -DOPENSSL_NO_CAPIENG=ON `
+    ../../orthanc-stone/OrthancStone/Samples/Sdl/RtViewer
+```
+
+Executing `cmake --build .` in the build folder will launch the Microsoft 
+builder on the solution.
+
+Alternatively, you can open and build the solution using Visual Studio 2019.
+