Mercurial > hg > orthanc-stone
diff Applications/Samples/README.md @ 1538:d1806b4e4839
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 |
line wrap: on
line diff
--- /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. +