Stone of Orthanc
================


General Information
-------------------

This repository contains the source code of the Stone of Orthanc.

Stone of Orthanc is a lightweight, cross-platform C++ framework for
the CPU-based rendering of medical images. It notably features support
for MPR (multiplanar reconstruction of volume images), PET-CT fusion,
and accurate physical world coordinates.

Stone of Orthanc comes bundled with its own software-based rendering
engine (based upon pixman). This engine will use CPU hardware
acceleration if available (notably SSE2, SSSE3, and NEON instruction
sets), but not the GPU. This makes Stone a highly versatile framework
that can run even on low-performance platforms. Note that Stone is
able to display DICOM series without having to entirely store them in
the RAM (i.e. frame by frame).

Thanks to its standalone rendering engine, Stone of Orthanc is also
compatible with any GUI framework (such as Qt, wxWidgets, MFC...). The
provided sample applications use the SDL framework.

Stone is conceived as a companion toolbox to the Orthanc VNA (vendor
neutral archive, i.e. DICOM server). As a consequence, Stone will
smoothly interface with Orthanc out of the box. Interestingly, Stone
does not contain any DICOM toolkit: It entirely relies on the REST API
of Orthanc to parse/decode DICOM images. However, thanks to the
object-oriented architecture of Stone, it is possible to avoid this
dependency upon Orthanc, e.g. to download DICOM datasets using
DICOMweb.


Comparison
----------

Pay attention to the fact that Stone of Orthanc is a toolkit, and not
a fully-featured application for the visualization of medical images
(such as Horos/OsiriX or Ginkgo CADx). However, such applications
could be built on the top of Stone of Orthanc.

Stone of Orthanc is quite similar to two other well-known toolkits:

* Cornerstone, a client-side JavaScript toolkit to display medical
  images in Web browsers, by Chris Hafey <chafey@gmail.com>:
  https://github.com/chafey/cornerstone

  Contrarily to Cornerstone, Stone of Orthanc can be embedded into
  native, heavyweight applications.

* VTK, a C++ toolkit for scientific visualization, by Kitware:
  http://www.vtk.org/

  Contrarily to VTK, Stone of Orthanc is focused on CPU-based, 2D
  rendering: The GPU will not be used.


Dependencies
------------

Stone of Orthanc is based upon the following projects:

* Orthanc, a lightweight Vendor Neutral Archive (DICOM server):
  http://www.orthanc-server.com/

* Cairo and pixman, a cross-platform 2D graphics library:
  https://www.cairographics.org/

* Optionally, SDL, a cross-platform multimedia library:
  https://www.libsdl.org/

Prerequisites to compile on Ubuntu: 
```
sudo apt-get install -y libcairo-dev libpixman-1-dev libsdl2-dev
```

Installation and usage
----------------------

Build instructions are similar to that of Orthanc:
https://orthanc.chu.ulg.ac.be/book/faq/compiling.html

Usage details are available as part of the Orthanc Book:
http://book.orthanc-server.com/developers/stone.html

Stone of Orthanc comes with several sample applications in the
"Samples" folder. These samples can be compiled into Web Assembly
or into native SDL applications.

to build the WASM samples:
-------------------------
```
cd ~/orthanc-stone/Applications/Samples
./build-wasm.sh
```

to serve the WASM samples:
```
# launch an Orthanc listening on 8042 port:
Orthanc

# launch an nginx that will serve the WASM static files and reverse proxy Orthanc
sudo nginx -p $(pwd) -c nginx.local.conf
```
Now, you can open the samples in http://localhost:9977

to build the SDL native samples (SimpleViewer only):
-------------------------------
```
mkdir -p ~/builds/orthanc-stone-build
cd ~/builds/orthanc-stone-build
cmake -DALLOW_DOWNLOADS=ON -DENABLE_SDL=ON ~/orthanc-stone/Applications/Samples/
cmake --build . --target OrthancStoneSimpleViewer -- -j 5
```

to execute the native samples:
```
# launch an Orthanc listening on 8042 port:
Orthanc

# launch the sample
./OrthancStoneSimpleViewer --studyId=XX
``` 

to build the Qt native samples on Windows:
-----------------------------------------

In a VS2015 x64 Native Tools Command Prompt:

```
mkdir -p C:\Users\alain\osimis\builds\orthanc-stone-build
cd C:\Users\alain\osimis\builds\orthanc-stone-build
cmake -G Ninja -DSTATIC_BUILD=ON -DORTHANC_FRAMEWORK_SOURCE=path -DORTHANC_FRAMEWORK_ROOT=C:\Users\alain\osimis\orthanc -DCMAKE_PREFIX_PATH=C:\Qt\5.9.3\msvc2015_64 ..\..\orthanc-stone\Applications\Samples

cmake -G Ninja -DALLOW_DOWNLOADS=ON -DENABLE_QT=ON ~/orthanc-stone/Applications/Samples/
cmake --build . --target OrthancStoneSimpleViewer -- -j 5
```


Licensing
---------

Stone of Orthanc is licensed under the AGPL license.

We also kindly ask scientific works and clinical studies that make
use of Orthanc to cite Orthanc in their associated publications.
Similarly, we ask open-source and closed-source products that make
use of Orthanc to warn us about this use. You can cite our work
using the following BibTeX entry:

@Article{Jodogne2018,
  author="Jodogne, S{\'e}bastien",
  title="The {O}rthanc Ecosystem for Medical Imaging",
  journal="Journal of Digital Imaging",
  year="2018",
  month="Jun",
  day="01",
  volume="31",
  number="3",
  pages="341--352",
  issn="1618-727X",
  doi="10.1007/s10278-018-0082-y",
  url="https://doi.org/10.1007/s10278-018-0082-y"
}