FW4SPL documentation¶

Features¶

• Reader/Writer

  • DICOM reader/writer

    • PACS connection
    • 3D mesh segmentation reader/writer
    • DICOM filter for reader

  • VTK (images and meshes)

  • ITK

  • Atoms (our custom in-out data format)

• Visualisation

  • 2D and 3D multi-planar reconstruction
  • volume rendering
  • 3D meshes

Application¶

VRRender is a medical image and segmentation viewer, containing all the previous features.

Main VRRender view.

MPR view of a medical 3D image.

3D view of surfacic meshes.

Volume rendering

Volume rendering mixed with 3D surfacic meshes.

Tutorials¶

You can find some tutorials to explain fw4spl concept.

Examples¶

Features¶

This repository brings features for Augmented Reality:

• webcam, network video and local video playing based on QtMultimedia,
• mono and stereo camera calibration,
• ArUco optical markers tracking,
• openIGTLink support through clients and servers services,
• TimeLine data, allowing to store buffers of various data (video, matrices, markers, etc...). These can be used to synchronize these data accross time.

Applications¶

ARCalibration¶

ARCalibration is a user-friendly application to calibrate mono and stereo cameras. This software is a must-have since camera calibration is a mandatory step in any AR application.

Mono camera intrinsic calibration.

Stereo camera extrinsic calibration.

Features¶

• regular surfacic meshes rendering for reconstruction,
• 2D and 3D negato medical image display with transfer function support,
• Order-independent transparency (several techniques implemented such as Depth-peeling, Weighted-blended order independent transparency, and Hybrid Transparency),
• customizable shaders and parameters edition.

Application¶

OgreViewer is a demonstration application to show the rendering features of the Ogre3D backend.

Features¶

• navigation along a spline
• new mesher using the CGoGN library
• ...

Application¶

VRRenderExt is an application containing the VRRender features and also the additional fw4spl-ext features.

Proofs of concept¶

Prerequisites for Windows users¶

If not already installed:

1. Install git
2. Optionally you can install TortoiseHg
3. Install Visual Studio 2013 Community
4. Install Python 2.7
5. Install CMake
6. Install jom
7. Install ninja

Qt is an external library used in FW4SPL. For the successful compilation of Qt for FW4SPL, please see the following requirements:

• http://wiki.qt.io/Building_Qt_5_from_Git

FW4SPL installation¶

Good practice in FW4SPL recommend to separate source files, build and install folders. So to prepare the development environment:

• Create a development folder (Dev)

• Create a build folder (Dev\Build)

  • Add a sub folder for Debug and Release.

• Create a source folder (Dev\Src)

• Create a install folder (Dev\Install)

  • Add a sub folder for Debug and Release.

To prepare the third party environment:

• Create a third party folder (BinPkgs)

• Create a build folder (BinPkgs\Build)

  • Add a sub folder for Debug and Release.

• Create a source folder (BinPkgs\Src)

• Create an install folder (BinPkgs\Install)

  • Add a sub folder for Debug and Release.

• Set the environment for a x64 version. To compile BinPkgs and sources, you must use the ‘VS2013 x64 Native Tools Command Prompt’

Launch an application¶

After an successful compilation the application can be launched with the fwlauncher.exe from FW4SPL. Therefore the profile.xml of the application in the build folder has to be passed as argument.

Extensions¶

fw4spl has two main extension repositories:

• fw4spl-ar: extension of fw4spl repository, contains functionalities for augmented reality (video tracking for instance).
• fw4spl-ogre: another extension of fw4spl, contains a 3D backend using Ogre3D.

If you want to use them, clone them first in the (Dev) source folder. Then modify ADDITIONAL_PROJECTS in cmake-gui to set the source location of fw4spl-ar and fw4spl-ogre separated by ‘;’. Last, re-generate the code and compile with ninja.

Recommended software¶

The following programs may be helpful for your developments:

• Eclipse CDT: Eclipse is a multi-OS Integrated Development Environment (IDE) for computer programming.
• Notepad++: Notepad++ is a free source code editor, which is designed with syntax highlighting functionality.
• ConsoleZ: ConsoleZ is an alternative command prompt for Windows, adding more capabilities to the default Windows command prompt. To compile FW4SPL with the console the windows command prompt has to be set in the tab settings.

Prerequisites for Linux users¶

If not already installed:

1. Install git
2. Install gcc The minimal version required is 4.8 or clang The minimal version required is 3.5
3. Install Python 2.7
4. Install CMake. The minimal version required is 3.7 if you want to compile with precompiled headers (build twice faster, enabled by default). Otherwise you can use a 3.1 version.
5. Install Ninja

Depending on which linux distribution you use, for example on Debian/Ubuntu/Mint you can do:

$ apt-get install build-essential ninja-build python2.7 git cmake

# ~/.bashrc
export PATH=/home/login/software/cmake/bin:$PATH

Qt is an external library used in FW4SPL. For the successful compilation of Qt with FW4SPL, please see the following requirements:

• http://wiki.qt.io/Building_Qt_5_from_Git

Follow the instructions there to install the necessary packages on your system for Build essentials, libxcb and QtMultimedia. For the latter, please note that we use gstreamer-1.0 by default, so please replace libgstreamer0.10-dev and libgstreamer-plugins-base0.10-dev by libgstreamer1.0-dev and libgstreamer-plugins-base1.0-dev. You can safely ignore instructions for QtWebKit and QtWebEngine, we don’t build them. Since we build Qt with openssl support you also need to install libssl-dev (be sure that the version is equal or upper to 1.0.0). Last for VTK we also need the X Toolkit Intrinsics library headers, that you can easily install for instance on a Debian-based distribution with the package libxt-dev.

FW4SPL installation¶

FW4SPL uses CMake as build system.

We strongly recommend to build FW4SPL by separating source files, build files and install files. So we propose the following folders layout :

• Deps/Build/Debug
• Deps/Build/Release
• Deps/Src
• Deps/Install/Debug
• Deps/Install/Release
• Dev/Build/Debug
• Dev/Build/Release
• Dev/Src
• Dev/Install/Debug
• Dev/Install/Release

Of course you can name the folders as you wish, or choose a different layout, but keep in mind to not build inside the source directory. This is strongly discouraged by CMake authors.

Here are the details, if you need some help to create this folders hierarchy :

• Create a third party folder (Deps)

$ mkdir Deps

• Create into “Deps” the source, build and install directories

$ mkdir Deps/Src Deps/Build Deps/Install

• Create sub-folders to separate Debug and Release compilations

$ mkdir Deps/Build/Debug Deps/Build/Release Deps/Install/Debug Deps/Install/Release

• Then create a “Dev” directory, for FW4SPL

$ mkdir Dev

• Create into “Dev” the source, build and install directories

$ mkdir Dev/Src Dev/Build Dev/Install

• Create sub-folders to separate Debug and Release compilations

$ mkdir Dev/Build/Debug Dev/Build/Release Dev/Install/Debug Dev/Install/Release

Dependencies¶

We need first to build the third-party librairies. We will now fetch the scripts that allow to build them and then launch the compilation.

• Clone the repository into your source directory of Deps:

$ cd Deps/Src
$ git clone https://github.com/fw4spl-org/fw4spl-deps.git fw4spl-deps

• Go into fw4spl-deps folder and update to the latest stable version:

$ cd fw4spl-deps
$ git checkout fw4spl_0.11.0

• Go into your Build directory (Debug or Release) : here an example if you want to compile in DEBUG

$ cd ../../..
$ cd Deps/Build/Debug

Project configuration¶

To build the dependencies, you must configure the project with CMake into the Build folder. As any CMake based project, there are three different ways to perform that.

1. Command-line¶

In this case, you give all the necessary variables on the command-line in one shot :

$ cd ~/Deps/Build/Debug
$ cmake ../../Src/fw4spl-deps -DCMAKE_INSTALL_PREFIX=~/Deps/Install/Debug -DCMAKE_BUILD_TYPE=Debug

2. NCurses based editor¶

This editor allows to set the required each variable in a more interactive way :

$ cd ~/Deps/Build/Debug
$ ccmake ../../Src/fw4spl-deps

Then change the following CMake variables:

• CMAKE_INSTALL_PREFIX: set the install location, here ~/Deps/Install/Debug
• CMAKE_BUILD_TYPE: set the build type ‘Debug’ or ‘Release’

Press “c” to configure and then “g” to generate the makefiles.

3. Qt based gui¶

$ cd ~/Deps/Build/Debug
$ cmake-gui ../../Src/fw4spl-deps

Like ccmake, change the following CMake variables:

• CMAKE_INSTALL_PREFIX: set the install location, here ~/Deps/Install/Debug
• CMAKE_BUILD_TYPE: set the build type ‘Debug’ or ‘Release’

Click on “configure” then “generate”.

Warning

Do not compile debug and release with the same Build and Install folders. If you followed the recommended folder layout, this should be fine.

Compilation¶

Now you can compile the FW4SPL dependencies with make in the console, it will automaticaly download, build and install each dependency.

# Adjust the number of cores depending of the CPU cores and the RAM available on your computer
$ make -j4

Warning

Do NOT use ninja to compile the dependencies, it causes conflict with qt compilation.

If you get compilation errors at this step, please ensure you installed all the requirements, especially those for Qt.

Source¶

• Clone fw4spl repository into your source directory:

$ cd Dev/Src
$ git clone https://github.com/fw4spl-org/fw4spl.git fw4spl

• Go into fw4spl folder and update to the latest stable version:

$ cd fw4spl
$ git checkout fw4spl_0.11.0

• Go into your Build directory (Debug or Release) : here an example if you want to compile in debug:

$ cd Dev/Build/Debug

• Now you have to configure the project. You can use one of the three tools explained above.

Also, for FW4SPL, we recommend to use the Ninja generator. It builds faster, and it is much better for everyday use because it is fast as hell to check the files you need to compile. In other words, with Ninja the compilation starts instantly whereas Make spends a dozen of seconds to check what should be compiled before actually compiling something. So if you plan to develop with FW4SPL, go with Ninja. If you only want to give a single try, you can live with the standard “Unix Makefiles” generator.

To use make, here with ccmake :

$ ccmake ../../Src/fw4spl

To use ninja :

$ ccmake -G Ninja ../../Src/fw4spl

• Change the following cmake arguments

  • CMAKE_INSTALL_PREFIX: set the install location (~/Dev/Install/Debug or Release)
  • CMAKE_BUILD_TYPE: set to Debug or Release
  • EXTERNAL_LIBRARIES: set the install path of the third party libraries you compiled before.(ex : ~/Deps/Install/Debug)
  • PROJECT_TO_BUILD: set the list of the projects you want to build (ex: VRRender, Tuto01Basic ...), each project should be separated by ”;”
  • PROJECT_TO_INSTALL: set the name of the application to install

Note

• If PROJECT_TO_BUILD is empty, all application will be compiled
• If PROJECT_TO_INSTALL is empty, no application will be installed

Press “c” to configure and then “g” to generate the makefiles.

Note

To generate the projects in release mode, change CMake argument CMAKE_BUILD_TYPE to Release both for fw4spl and fw4spl-deps

Then, according to the generator you chose, build FW4SPL with make :

# Adjust the number of cores depending of the CPU cores and the RAM available on your computer
$ make -j4

Or with ninja:

$ ninja

If you didn’t specify anything in PROJECT_TO_BUILD you may also build specific targets, for instance:

$ ninja Tuto01Basic VRRender

Launch an application¶

After a successful compilation the application can be launched with the fwlauncher program from FW4SPL. The profile.xml of the application in the build folder has to be passed as argument to the fwlauncher call in the console.

$ bin/fwlauncher Bundles/MyApplication_Version/profile.xml

Example:

$ cd /Dev/Build/Debug
$ bin/fwlauncher Bundles/VRRender_0-9/profile.xml

Extensions¶

FW4SPL has two main extension repositories:

• fw4spl-ar: extension of fw4spl repository, contains functionalities for augmented reality (video tracking for instance).

$ cd Dev/Src
$ git clone https://github.com/fw4spl-org/fw4spl-ar.git fw4spl-ar
$ cd fw4spl-ar
$ git checkout fw4spl_0.11.0

• fw4spl-ogre: another extension of fw4spl, contains a 3D backend using Ogre3D.

  $ cd Dev/Src $ git clone https://github.com/fw4spl-org/fw4spl-ogre.git fw4spl-ogre $ cd fw4spl-ogre $ git checkout fw4spl_0.11.0

Then you have to reconfigure your CMake project:

$ cd ../../Build/Debug
$ ccmake .

Modify `̀ ADDITIONAL_PROJECTS`̀ : set the source location of fw4spl-ar and fw4spl-ogre separated by a semi-colon.

~/Dev/Src/fw4spl-ar/;~/Dev/Src/fw4spl-ogre/

Recommended software¶

The following programs may be helpful for your developments:

• Eclipse CDT
• QtCreator

Prerequisites for MacOSX users¶

If not already installed:

1. Install Xcode
2. Install git
3. Install Python 2.7
4. Install CMake. The minimal version required is 3.7 if you want to compile with precompiled headers (build twice faster, enabled by default). Otherwise you can use a 3.1 version.
5. Install Ninja : to use instead of make.

For an easy install, you can use the Hombrew project to install missing packages.

$ brew install git
$ brew install python
$ brew install cmake
$ brew install ninja

FW4SPL installation¶

FW4SPL uses CMake as build system.

We strongly recommend to build FW4SPL by separating source files, build files and install files. So we propose the following folders layout :

• Deps/Build/Debug
• Deps/Build/Release
• Deps/Src
• Deps/Install/Debug
• Deps/Install/Release
• Dev/Build/Debug
• Dev/Build/Release
• Dev/Src
• Dev/Install/Debug
• Dev/Install/Release

Of course you can name the folders as you wish, or choose a different layout, but keep in mind to not build inside the source directory. This is strongly discouraged by CMake authors.

Here are the details, if you need some help to create this folders hierarchy :

• Create a third party folder (Deps)

$ mkdir Deps

• Create into “Deps” the source, build and install directories

$ mkdir Deps/Src Deps/Build Deps/Install

• Create sub-folders to separate Debug and Release compilations

$ mkdir Deps/Build/Debug Deps/Build/Release Deps/Install/Debug Deps/Install/Release

• Then create a “Dev” directory, for FW4SPL

$ mkdir Dev

• Create into “Dev” the source, build and install directories

$ mkdir Dev/Src Dev/Build Dev/Install

• Create sub-folders to separate Debug and Release compilations

$ mkdir Dev/Build/Debug Dev/Build/Release Dev/Install/Debug Dev/Install/Release

Dependencies¶

We need first to build the third-party librairies. We will now fetch the scripts that allow to build them and then launch the compilation.

• Clone the repository into your source directory of Deps:

$ cd Deps/Src
$ git clone https://github.com/fw4spl-org/fw4spl-deps.git fw4spl-deps

• Go into fw4spl-deps folder and update to the latest stable version:

$ cd fw4spl-deps
$ git checkout fw4spl_0.11.0

• Go into your Build directory (Debug or Release) : here an example if you want to compile in DEBUG

$ cd ../../..
$ cd Deps/Build/Debug

Project configuration¶

To build the dependencies, you must configure the project with CMake into the Build folder. As any CMake based project, there are three different ways to perform that.

1. Command-line¶

In this case, you give all the necessary variables on the command-line in one shot :

$ cd ~/Deps/Build/Debug
$ cmake ../../Src/fw4spl-deps -DCMAKE_INSTALL_PREFIX=~/Deps/Install/Debug -DCMAKE_BUILD_TYPE=Debug

2. NCurses based editor¶

This editor allows to set the required each variable in a more interactive way :

$ cd ~/Deps/Build/Debug
$ ccmake ../../Src/fw4spl-deps

Then change the following CMake variables:

• CMAKE_INSTALL_PREFIX: set the install location, here ~/Deps/Install/Debug
• CMAKE_BUILD_TYPE: set the build type ‘Debug’ or ‘Release’

Press “c” to configure and then “g” to generate the makefiles.

3. Qt based gui¶

$ cd ~/Deps/Build/Debug
$ cmake-gui ../../Src/fw4spl-deps

Like ccmake, change the following CMake variables:

• CMAKE_INSTALL_PREFIX: set the install location, here ~/Deps/Install/Debug
• CMAKE_BUILD_TYPE: set the build type ‘Debug’ or ‘Release’

Click on “configure” then “generate”.

Warning

Do not compile debug and release with the same Build and Install folders. If you followed the recommended folder layout, this should be fine.

Compilation¶

Now you can compile the FW4SPL dependencies with make in the console, it will automaticaly download, build and install each dependency.

$ make all
$ make install_tool

Warning

Do NOT use ninja to compile the dependencies, it causes conflict with qt compilation.

If you get compilation errors at this step, please ensure you installed all the requirements, especially those for Qt.

Source¶

• Clone fw4spl repository into your source directory:

$ cd Dev/Src
$ git clone https://github.com/fw4spl-org/fw4spl.git fw4spl

• Go into fw4spl folder and update to the latest stable version:

$ cd fw4spl
$ git checkout fw4spl_0.11.0

• Go into your Build directory (Debug or Release) : here an example if you want to compile in debug:

$ cd Dev/Build/Debug

• Now you have to configure the project. You can use one of the three tools explained above.

Also, for FW4SPL, we recommend to use the Ninja generator. It builds faster, and it is much better for everyday use because it is fast as hell to check the files you need to compile. In other words, with Ninja the compilation starts instantly whereas Make spends a dozen of seconds to check what should be compiled before actually compiling something. So if you plan to develop with FW4SPL, go with Ninja. If you only want to give a single try, you can live with the standard “Unix Makefiles” generator.

To use make, here with ccmake :

$ ccmake ../../Src/fw4spl

To use ninja :

$ ccmake -G Ninja ../../Src/fw4spl

• Change the following cmake arguments

  • CMAKE_INSTALL_PREFIX: set the install location (~/Dev/Install/Debug or Release)
  • CMAKE_BUILD_TYPE: set to Debug or Release
  • EXTERNAL_LIBRARIES: set the install path of the third party libraries you compiled before.(ex : ~/Deps/Install/Debug)
  • PROJECT_TO_BUILD: set the list of the projects you want to build (ex: VRRender, Tuto01Basic ...), each project should be separated by ”;”
  • PROJECT_TO_INSTALL: set the name of the application to install

Note

• If PROJECT_TO_BUILD is empty, all application will be compiled
• If PROJECT_TO_INSTALL is empty, no application will be installed

Press “c” to configure and then “g” to generate the makefiles.

Note

To generate the projects in release mode, change CMake argument CMAKE_BUILD_TYPE to Release both for fw4spl and fw4spl-deps

Then, according to the generator you chose, build FW4SPL with make :

# Adjust the number of cores depending of the CPU cores and the RAM available on your computer
$ make -j4

Or with ninja:

$ ninja

If you didn’t specify anything in PROJECT_TO_BUILD you may also build specific targets, for instance:

$ ninja Tuto01Basic VRRender

Launch an application¶

After a successful compilation the application can be launched with the fwlauncher program from FW4SPL. The profile.xml of the application in the build folder has to be passed as argument to the fwlauncher call in the console.

$ bin/fwlauncher Bundles/MyApplication_Version/profile.xml

Example:

$ cd /Dev/Build/Debug
$ bin/fwlauncher Bundles/VRRender_0-9/profile.xml

Extensions¶

FW4SPL has two main extension repositories:

• fw4spl-ar: extension of fw4spl repository, contains functionalities for augmented reality (video tracking for instance).

$ cd Dev/Src
$ git clone https://github.com/fw4spl-org/fw4spl-ar.git fw4spl-ar
$ cd fw4spl-ar
$ git checkout fw4spl_0.11.0

• fw4spl-ogre: another extension of fw4spl, contains a 3D backend using Ogre3D.

  $ cd Dev/Src $ git clone https://github.com/fw4spl-org/fw4spl-ogre.git fw4spl-ogre $ cd fw4spl-ogre $ git checkout fw4spl_0.11.0

Then you have to reconfigure your CMake project:

$ cd ../../Build/Debug
$ ccmake .

Modify `̀ ADDITIONAL_PROJECTS`̀ : set the source location of fw4spl-ar and fw4spl-ogre separated by a semi-colon.

~/Dev/Src/fw4spl-ar/;~/Dev/Src/fw4spl-ogre/

Recommended software¶

The following programs may be helpful for your developments:

• IDE:

  • Qt creator
  • Eclipse CDT.

• Versioning tools:

  • SourceTree

Android environnement¶

The following tools are necessary:

• JDK >= 6 (JRE only is not sufficient)
• Gradle 2.13 ou more recent

SDK install¶

The SDK is a set of libraries and development tools necessary to build, test and debug and Android application. The initial archive you will download contains only the basic tools of the SDK. It doesn’t contain any version of the API (Android Platform) and doesn’t provide the whole set of tools you actually need to develop an application.

• Download the SDK archive:

  • OSX
  • Linux
  • Windows

• Extract the archive

• Set the environment variable ANDROID_SDK to its actual path

# i.e for Linux and OSX
export ANDROID_SDK=/ABSOLUTE/PATH/TO/THE/ANDROID_SDK

• The SDK Manager tool ease the downloading and the management of the different SDK versions, as well as the downloading of the development tools:

  • On Windows, SDK Manager.exe is located in the SDK root folder
  • On Linux and OSX, launch the following command in the SDK root folder :

./tools/android sdk

• You can also update the sdk directly through the command line:

./tools/android update sdk —no-ui

After that, you have to download at least one version of the API and one Platform-tools version. The latter contains the build tools (adb, etc...) and are updated independently of the SDK. More informations can be found here.

NDK install¶

The NDK is the tool allowing people to develop some parts of your application using native code (C/C ++). It also contains the system headers necessary to link successfully your librairies with the latest releases :

• libc (C library) headers
• libm (math library) headers
• JNI interface headers
• libz (Zlib compression) headers
• liblog (Android logging) header
• OpenGL ES 1.1 and OpenGL ES 2.0 (3D graphics libraries) headers
• libjnigraphics (Pixel buffer access) header (for Android 2.2 and above).
• A Minimal set of headers for C++ support
• OpenSL ES native audio libraries
• Android native application APIS

The NDK also provides a build system which will allow you to compile your source code without taking care of the toolchain/platform/CPU/ABI (ABI = Application Binary Interface). You have to ensure to have the latest version of the SDK. Indeed, the NDK is compatible with the previous versions of the Android API, but this is not the case for the Platform tools.

• Download the NDK for your host platfom here and extract the zip archive.

More informations can be found here.

Configuration for FW4SPL¶

In order to obtain an Android development environment compatible with FW4SPL and its third-party libraries, you must fulfill the conditions below.

The APIs <= 8 (Froyo) are not supported because of compilation error in boost. Thus it is recommended to install the SDK Manager with the following versions versions:

• Tools:

  • Android SDK Tools >= 23.0.5.
  • Android SDK Platform-Tools >= 21.
  • Android SDL Build-tools >= 21.0.2.

• Android 4.4.2 (API 21):

  • SDK Platform >= 21.

• On top of that, Qt 5.x does need multiple versions of the API (only download the SDK Platform):

  • API 10 and 11 for QtMultimedia.
  • API 16 for QtBase.

So don’t forget to install them before building the FW4SPL deps.

You must also add the following environment variables.

ANDROID_NDK=/PATH/TO/NDK
ANDROID_SDK=/PATH/TO/SDK
JAVA_HOME=/PATH/TO/JDK

Please remember that JAVA_HOME is the root folder of the JDK and not the binary folder.

FW4SPL installation¶

FW4SPL uses CMake as build system.

We strongly recommend to build FW4SPL by separating source files, build files and install files. So we propose the following folders layout :

• Deps/Build/Debug
• Deps/Build/Release
• Deps/Src
• Deps/Install/Debug
• Deps/Install/Release
• Dev/Build/Debug
• Dev/Build/Release
• Dev/Src
• Dev/Install/Debug
• Dev/Install/Release

Of course you can name the folders as you wish, or choose a different layout, but keep in mind to not build inside the source directory. This is strongly discouraged by CMake authors.

Here are the details, if you need some help to create this folders hierarchy :

• Create a third party folder (Deps)

$ mkdir Deps

• Create into “Deps” the source, build and install directories

$ mkdir Deps/Src Deps/Build Deps/Install

• Create sub-folders to separate Debug and Release compilations

$ mkdir Deps/Build/Debug Deps/Build/Release Deps/Install/Debug Deps/Install/Release

• Then create a “Dev” directory, for FW4SPL

$ mkdir Dev

• Create into “Dev” the source, build and install directories

$ mkdir Dev/Src Dev/Build Dev/Install

• Create sub-folders to separate Debug and Release compilations

$ mkdir Dev/Build/Debug Dev/Build/Release Dev/Install/Debug Dev/Install/Release

$ cd Deps/Src
$ git clone https://github.com/fw4spl-org/fw4spl-deps.git fw4spl-deps

$ cd fw4spl-deps
$ git checkout fw4spl_0.11.0

$ cd ../../..
$ cd Deps/Build/Debug

git clone https://github.com/fw4spl-org/android-cmake.git ~/Dev/Droid

Project configuration¶

To build the dependencies, you must configure the project with CMake into the Build folder. As any CMake based project, there are three different ways to perform that.

1. Command-line¶

In this case, you give all the necessary variables on the command-line in one shot :

$ cd ~/Dev/Deps/Build/Debug
$ cmake ../Src/fw4spl-deps -DCMAKE_INSTALL_PREFIX=~/Dev/Deps/Install/Debug -DCMAKE_BUILD_TYPE=Debug -DCROSS_COMPILING=ON -DANDROID_NATIVE_API_LEVEL=21 -DCMAKE_TOOLCHAIN_FILE=~/Dev/Droid/android.toolchain.cmake

2. NCurses based editor¶

This editor allows to set the required each variable in a more interactive way :

$ cd ~/Dev/Deps/Build/Debug
$ ccmake ../Src/fw4spl-deps

Then change the following CMake variables:

• CMAKE_INSTALL_PREFIX: set the install location, here ~/Dev/Deps/Install/Debug
• CMAKE_BUILD_TYPE: set the build type ‘Debug’ or ‘Release’
• CROSS_COMPILING: set to ‘ON’

Press “c” to configure. Now you have got two new variables to set:

• ANDROID_NATIVE_API_LEVEL: set to ‘21’
• CMAKE_TOOLCHAIN_FILE: set to ~/Dev/Droid/android.toolchain.cmake

Press “c” to configure and then “g” to generate the makefiles.

3. Qt based gui¶

$ cd ~/Dev/Deps/Build/Debug
$ cmake-gui ../Src/fw4spl-deps

Like ccmake, change the following CMake variables:

• CMAKE_INSTALL_PREFIX: set the install location, here ~/Dev/Deps/Install/Debug
• CMAKE_BUILD_TYPE: set the build type ‘Debug’ or ‘Release’
• CROSS_COMPILING: set to ‘ON’

Press “c” to configure. Now you have got two new variables to set:

• ANDROID_NATIVE_API_LEVEL: set to ‘21’
• CMAKE_TOOLCHAIN_FILE: set to ~/Dev/Droid/android.toolchain.cmake

Click on “configure” then “generate”.

Warning

Do not compile debug and release with the same Build and Install folders. If you followed the recommended folder layout, this should be fine.

Warning

For Windows host platform, do not put the bin/ folder of git in the PATH of your build terminal. It may cause troubles with Qt compilation (some Makefiles are badly generated with simple quotes).

Warning

Do NOT use ninja to compile the dependencies, it causes conflict with qt compilation.

If you get compilation errors at this step, please ensure you installed all the requirements, especially those for Qt.

Source¶

• Clone fw4spl repository into your source directory:

$ cd Dev/Src
$ git clone https://github.com/fw4spl-org/fw4spl.git fw4spl

• Go into fw4spl folder and update to the latest stable version:

$ cd fw4spl
$ git checkout fw4spl_0.11.0

• Clone fw4spl-droid repository into your source directory:

$ cd ..
$ git clone https://github.com/fw4spl-org/fw4spl-droid.git fw4spl-droid
$ cd fw4spl-droid
$ git checkout fw4spl_0.11.0

• Go into your Build directory (Debug or Release) : here an example if you want to compile in debug:

$ cd Dev/Build/Debug

• Now you have to configure the project. You can use one of the three tools explained above.

Also, for FW4SPL, we recommend to use the Ninja generator. It builds faster, and it is much better for everyday use because it is fast as hell to check the files you need to compile. In other words, with Ninja the compilation starts instantly whereas Make spends a dozen of seconds to check what should be compiled before actually compiling something. So if you plan to develop with FW4SPL, go with Ninja. If you only want to give a single try, you can live with the standard “Unix Makefiles” generator.

To use make, here with ccmake :

$ ccmake ../../Src/fw4spl

To use ninja :

$ ccmake -G Ninja ../../Src/fw4spl

• Change the following cmake arguments

  • CMAKE_INSTALL_PREFIX: set the install location (~/Dev/Install/Debug or Release)
  • CMAKE_BUILD_TYPE: set to Debug or Release
  • EXTERNAL_LIBRARIES: set the install path of the third party libraries you compiled before.(ex : ~/Dev/Deps/Install/Debug)
  • PROJECT_TO_BUILD: set the list of the projects you want to build (ex: PoC09Android, ...), each project should be separated by ”;”
  • PROJECT_TO_INSTALL: set the name of the application to install
  • CROSS_COMPILING: set to ‘ON’

Press “c” to configure. Now you have got two new variables to set:

• ANDROID_NATIVE_API_LEVEL: set to ‘21’
• CMAKE_TOOLCHAIN_FILE: set to ~/Dev/Droid/android.toolchain.cmake

Note

• If PROJECT_TO_BUILD is empty, all application will be compiled
• If PROJECT_TO_INSTALL is empty, no application will be installed

Press “c” to configure and then “g” to generate the makefiles.

Note

To generate the projects in release mode, change CMake argument CMAKE_BUILD_TYPE to Release both for fw4spl and fw4spl-deps

Then, according to the generator you chose, build FW4SPL with make :

# Adjust the number of cores depending of the CPU cores and the RAM available on your computer
$ make -j4

Or with ninja:

$ ninja

If you didn’t specify anything in PROJECT_TO_BUILD you may also build specific targets, for instance:

$ ninja PoC09Android

To deploy the application, connect your Android device to the USB port, be sure that it is in developer mode and that USB debugging is enabled. Then run:

$ ninja install

Thanks to Gradle and adb, the application will be packaged and copied automatically to your device.

Introduction¶

The framework FW4SPL (FrameWork for Software Production) is an open-source framework, developed by IRCAD (research institute against cancer and disease). The purpose of FW4SPL is to ease the creation of applications in the medical imaging field. Therefore it provides features like digital image processing in 2D and 3D, visualization or simulation of medical interactions.

FW4SPL is based on a component architecture composed of C++ libraries. The three main concepts of the architecture, explained in the following sections, are:

• object-service concept
• component approach
• signal-slot communication

The framework is multi-platform and runs under Windows, Linux, MacOS and Android. Building an application with FW4SPL only requires to write one or several XML files. Its functionalities can be also extended by writing new components in C++, which is the coding language of the framework.

This document will introduce the general architecture of FW4SPL.

Introduction¶

In the Object Oriented Programming (OOP) paradigm, an object is an instance of a class which contains the data and the algorithms. For instance, a class Image contains the image buffer, the size and format attributes, along with the methods to process the image, such as reading, writing, visualizing, analysing, etc.

This design works well, but has some drawbacks. First the code of the class implementation can become very big if you put everything in it, making collaborative work harder. Then if you use different third-party libraries in your methods (for instance DCMTK for I/O, VTK for visualization, OpenCV or ITK for the filtering methods), your class becomes dependent of all of these libraries even if you only need one or two functionalities. If we want something modular, that does not work. Last, because of the two previous points, the maintenance of source code is quite tough.

Instead, FW4SPL proposes an Object-Service paradigm where data and algorithms are separated into different code units.

Object¶

Objects represent data used in the framework. They can be simple (boolean, integer, string, etc.) or advanced structures (image, mesh, video, patient, etc.). They are generic, which means they do not depend on the original input format or the future output format. This way they can used with different third-party libraries, and we provide helper methods to convert them into the corresponding formats.

These object classes contain only data features and their corresponding getter/setter methods.

For instance, the Image object:

• contains a buffer pointer, a buffer size, the image’s dimension and origin,
• has public setter/getter methods to access these members,
• does not have methods such as reading or writing a buffer

The fwData library contains the standard simple and advanced data. It is the main data library of FW4SPL. There is also the fwMedData library which contains several structures to store medical data. A data list with a brief description is available in the appendixes.

class MyData : public ::fwData::Object
{

public :
    fwCoreClassDefinitionsWithFactoryMacro( (MyData)(::fwData::Object),
        (()), ::fwData::factory::New< MyData >) ;


    // Private constructor, required for data factory
    MyData(::fwData::Object::Key key);

    /// Destructor, required for all data
    virtual ~MyData();

    /// Defines shallow copy, required for all data
    void shallowCopy( const Object::csptr& _source );

    /// Defines deep copy, required for all data
    void cachedDeepCopy(const Object::csptr& _source,
                            DeepCopyCacheType &cache);

};

fwDataRegisterMacro( MyData );

Service¶

A service represents a functionality which uses or modifies data. It is associated with one or several objects. For example, a service working on a single image could be a reader, a writer, or a visualization service. A service working on two images could be a filtering service, or a service working on a image and a mesh, a mesher.

MyData::sptr myData = MyData::New();
MyService::sptr mySrv = MyService::New();
mySrv->setObject(myData);

mySrv->setConfiguration( ... ); // set parameters
mySrv->configure(); // check parameters
mySrv->start(); // start the service
mySrv->update(); // update the service
mySrv->stop(); // stop the service

class MyService : public AbstractServiceType
{
public:

    // Macro to define few important parameters/functions used by the architecture
    fwCoreServiceClassDefinitionsMacro((MyService)(AbstractServiceType));

    // Service constructor
    MyService() throw() ;

    // Service destructor.
    virtual ~MyService() throw() ;

protected:

    // To configure the service
    void configuring() throw(fwTools::Failed);

    // To start the service
    void starting() throw(::fwTools::Failed);

    // To stop the service
    void stopping() throw(::fwTools::Failed);

    // To update the service
    void updating() throw(::fwTools::Failed);
};

fwServicesRegisterMacro( AbstractServiceType, MyService, MyData );

Object and service factories¶

To instantiate an object or a service, the architecture requires the use of a factory system. In class-based programming, the factory method pattern is a creational pattern which uses factory methods to deal with the problem of creating classes without specifying the exact class that will be created. This is done by creating classes via a factory method, which is either specified in an interface (abstract class) and implemented in child classes (concrete classes) or implemented in a base class (optionally as a template method), which can be overridden when inherited in derivative classes; rather than by a constructor.

// in .hpp file
fwCoreClassDefinitionsWithFactoryMacro( (MyData)(::fwData::Object),
    (()), ::fwData::factory::New< MyData >);

// in .cpp file
fwDataRegisterMacro( MyData );

// Direct creation
MyData::sptr obj = MyData::New();

// Factory creation (here obj is an object of type
// MyData, it is then possible to cast it dynamically)
::fwData::Object::sptr obj = ::fwData::factory::New("MyData");
MyData::sptr myData = MyData::dynamicCast(obj);

// in .hpp file
fwCoreServiceClassDefinitionsMacro ((MyService)(AbstractServiceType));

// in .cpp file
fwServicesRegisterMacro( AbstractServiceType, MyService, MyData );

::fwServices::registry::ServiceFactory::sptr srvFactory
        = ::fwServices::registry::ServiceFactory::getDefault();

// Factory creation (here srv is a service of type MyService,
// it is possible to cast it)
::fwServices::IService::sptr srv = srvFactory->create("MyService");

Object-Service registry¶

The FW4SPL architecture is standardized thanks to:

• Abstract classes fwData::Object and fwService::IService.
• The two factory systems.

In an application, one of the problems is managing the life cycle of a large number of object instances and their services. This problem is solved by the class fwServices::registry::ObjectService which maintains the relationship between objects and services. This class concept is very simple :

// OSR is a singleton
class ObjectService
{
public:
  // ...

  // Associates a service to an object
  void registerService ( ::fwData::Object::sptr obj,
                         const ::fwServices::IService::KeyType& objKey,
                         ::fwServices::IService::AccessType access,
                         ::fwServices::IService::sptr service);

  // Dissociates a service from an object
  void unregisterService ( const ::fwServices::IService::KeyType& objKey,
                           ::fwServices::IService::AccessType access,
                           IService::sptr service );

  // ...
}

This registry manages the object-service relationships and guarantees the non-destruction of an object while some services are still working on it.

Each object associated with the service must provide a key and an access type. The key is used to retrieve the object in the service code, while the access type tells how the object can be accessed: read, read/write or write.

class IService
{
public:
  // ...
  template<class DATATYPE> CSPTR(DATATYPE) getInput( const KeyType& key) const;
  template<class DATATYPE>  SPTR(DATATYPE) getInOut( const KeyType& key) const;
  // ...
};

::fwData::Image::sptr image = this->getInOut< ::fwData::Image>("image");
::fwData::Mesh::csptr mesh  = this->getInput< ::fwData::Mesh>("mesh");

Object access type¶

How to choose between the different access type for a given data ?

1. Read-only (IN)

   • If you don’t modify the data and so that means you can deal with a const pointer on the data, then this is the right choice.

2. Write-only (OUT)

   • This is a special case when the service will actually create the data. The data doesn’t exist before the service creation. At some point, during start(), or update() or elsewhere, the data is allocated, filled and registered in the OSR :

::IService::setOutput(const KeyType& key, const ::fwData::Object::sptr& object);
//..
::fwData::Image::sptr image = ::fwData::Image::New();
this->setOutput("outputImage", image);

3. Read-Write

   • The object already exists, and you need to modify it.

This topic is explained more widely in the AppConfig section.

Object-Service concept example¶

To conclude, the generic object-service concept is illustrated with this example:

// Create an object
::fwData::Object::sptr obj = ::fwData::factory::New("::fwData::Image");

// Create a reader and a view for this object
::fwServices::IService::sptr reader
    = ::fwServices::add(obj, "::io::IReader", "MyCustomImageReader");
::fwServices::IService::sptr view
    = ::fwServices::add(obj, "::fwRender::IRender", "MyCustomImageView");

// Configure and start services
reader->setConfiguration ( /* ... */ );
reader->configure();
reader->start();

view->setConfiguration ( /* ... */ );
view->configure();
view->start();

// Execute services
reader->update(); // Read image on filesystem
view->update(); // Refresh visualization with the new image buffer

// Stop services
reader->stop();
view->stop();

// Destroy services
::fwServices::registry::ObjectService::unregisterService(reader);
::fwServices::registry::ObjectService::unregisterService(view);

This example shows the code to create a small application to read an image and visualize it. You can easily transform this code to build an application which reads and displays a 3D mesh by changing object and services implementation strings only.

However, most applications made with FW4SPL are not built this way. Instead, we use AppConfig, which allows to simplify the code above by a declarative approach based on XML files.

Overview¶

“Signals and slots” is a language construct introduced in Qt [1] for communication between objects.

The concept is that objects and services(explained in 2.3) can send signals containing event information which can be received by other services using special functions known as slots.

FW4SPL implementation¶

In the FW4SPL architecture, the library fwCom provides a set of tools dedicated to communication. These communications are based on the signal and slot concept.

fwCom provides the following features :

• function and method wrapping
• direct slot calling
• asynchronous slot calling
• ability to work with multiple threads
• auto-disconnection of slot and signals
• arguments loss between slots and signals

Slots¶

Slots are wrappers for functions and class methods that can be attached to a fwThread::Worker. The purpose of this class is to provide synchronous and asynchronous mechanisms for method and function calling.

Slots have a common base class : SlotBase. This allows the storage of them in the same container. Slots are designed such that they can be called, even where only the argument type is known.

Examples :

A slot wrapping the function sum, which is a function with the signature int (int, int) :

::fwCom::Slot< int (int, int) >::sptr slotSum = ::fwCom::newSlot( &sum );

A slot wrapping the function start with signature void() of the object a which class type is A :

::fwCom::Slot< void() >::sptr slotStart = ::fwCom::newSlot(&A::start, &a);

Execution of the slots using the run method :

slotSum->run(40,2);
slotStart->run();

Execution of the slots using the method call, which returns the result of the execution :

int result = slotSum->call(40,2);
slotStart->call();

A slot declaration and execution, through a SlotBase :

::fwCom::Slot< size_t (std::string) > slotLen
        = ::fwCom::Slot< size_t (std::string) >::New( &len );
::fwCom::SlotBase::sptr slotBaseLen = slotLen;
::fwCom::SlotBase::sptr slotBaseSum = slotSum;
slotBaseSum->run(40,2);
slotBaseSum->run<int, int>(40,2);

// This one needs the  explicit argument type
slotBaseLen->run<std::string>("R2D2");
result = slotBaseSum->call<int>(40,2);
result = slotBaseSum->call<int, int, int>(40,2);
result = slotBaseLen->call<size_t, std::string>("R2D2");

Signals¶

Signals allow to perform grouped calls on slots. For this purpose, a signal class provides a mechanism to connect slots.

Examples:

The following instruction declares a signal with a void signature.

::fwCom::Signal< void() >::sptr sig = ::fwCom::Signal< void() >::New();

The connection between a signal and a slot of the same information type:

sig->connect(slotStart);

The following instruction will trigger the execution of all slots connected to this signal:

sig->emit();

It is possible to connect multiple slots with the same information type to the same signal and trigger their simultaneous execution.

Signals can take several arguments as a signature which will trigger their connected slots by passing the right arguments.

In the following example a signal is declared of type void(int, int). The signal is connected to two different types of slot, void (int) and int (int, int).

using namespace fwCom;
Signal< void(int, int) >::sptr sig2 = Signal< void(int, int) >::New();
Slot< int(int, int) >::sptr    slot1 = Slot< int(int, int) >::New(...);
Slot< void(int) >::sptr        slot2 = Slot< void(int) >::New(...);

sig2->connect(slot1);
sig2->connect(slot2);

sig2->emit(21, 42);

Here 2 points need to be highlighted :

• A signal cannot return a value. Consequently their return type is void. Thus, the return value of a slot, triggered by a signal, equally cannot be retrieved.
• To successfully trigger a slot using a signal, the minimum requirement as to the number of arguments or fitting argument types has to be given by the signal. In the last example the slot slot2 only requires one argument of type int, but the signal is emitting two arguments of type int. Because the signal signature fulfills the slot’s argument number and argument type, the signal can successfully trigger the slot slot2. The slot slot2 takes the first emitted argument which fits its parameter (here 21, the second argument is ignored).

sig2->disconnect(slot1);
sig2->emit(21, 42); // do not trigger slot1 anymore

::fwCom::Connection connection = signal->connect(slot);

::fwCom::Connection::Blocker lock(connection);
signal->emit();
// 'slot' will not be executed while 'lock' is alive or until lock is
// reset

connection.disconnect();
// slot is not connected anymore

Manage slots or signals in a class¶

The library fwCom provides two helper classes to manage signals or slots in a structure.

struct ThisClassHasSlots : public HasSlots
{
  typedef Slot< int()> GetValueSlotType;

  ThisClassHasSlots()
  {
      newSlot("sum", &SlotsTestHasSlots::getValue, this);
  }

  int sum(int a, int b)
  {
      return a+b;
  }

  int getValue()
  {
      return 4;
  }
};

ThisClassHasSlots obj;
obj.slot("sum")->call<int>(5,9);
obj.slot< ThisClassHasSlots::GetValueSlotType >("getValue")->call();

struct ThisClassHasSignals : public HasSignals
{
  typedef ::fwCom::Signal< void()> SignalType;

  ThisClassHasSignals()
  {
      newSignal< SignalType >("sig");
  }
};

ThisClassHasSignals obj;
Slot< void()>::sptr slot = ::fwCom::newSlot(&anyFunction)
obj.signal("sig")->connect( slot );
obj.signal< SignalsTestHasSignals::SignalType >("sig")->emit();
obj.signal("sig")->disconnect( slot );

Signals and slots used in objects and services¶

Signals are used in both objects and services, whereas slots are only used in services. The abstract class fwData::Object inherits from the HasSignals class as a basis to use signals :

class Object : public ::fwCom::HasSignals
{
  /// Key in m_signals map of signal m_sigObjectModified
  static const ::fwCom::Signals::SignalKeyType s_MODIFIED_SIG;
  //...

  /// Type of signal m_sigObjectModified
  typedef ::fwCom::Signal< void ( CSPTR( ::fwServices::ObjectMsg ) ) >
                ObjectModifiedSignalType;

  /// Signal that emits an ObjectMsg when an object is modified
  ObjectModifiedSignalType::sptr m_sigObjectModified;

  Object()
  {
      m_sigObjectModified = newSignal< ObjectModifiedSignalType >(s_MODIFIED_SIG);
      //...
  }
}

Moreover the abstract class fwService::IService inherits from the HasSlots class and the HasSignals class, as a basis to communicate through signals and slots. Actually, the methods start(), stop(), swap() and update() are all slots. Here is an extract with update():

class IService : public ::fwCom::HasSlots, public ::fwCom::HasSignals
{
  typedef ::boost::shared_future< void > SharedFutureType;

  /// Key in m_slots map of slot m_slotUpdate
  static const ::fwCom::Slots::SlotKeyType s_UPDATE_SLOT;

  /// Type of signal m_slotUpdate
  typedef ::fwCom::Slot<SharedFutureType()> UpdateSlotType;

  /// Slot to call update method
  UpdateSlotType::sptr m_slotUpdate;

  IService()
  {
      //...
      m_slotUpdate = newSlot( s_UPDATE_SLOT, &IService::update, this ) ;
      //...
  }

  //...
}

To automatically connect object signals and service slots, it is possible to override the method IService::getAutoConnections(). Please note that to be effective the attribute “autoConnect” of the service must be set to “yes” in the xml configuration (see App-config). The default implementation of this method connect the s_MODIFIED_SIG object signal to the s_UPDATE_SLOT slot.

IService::KeyConnectionsMap IService::getAutoConnections() const
{
    KeyConnectionsMap connections;
    connections.push( "data1", ::fwData::Object::s_MODIFIED_SIG, s_UPDATE_SLOT ) );
    connections.push( "data2", ::fwData::Object::s_MODIFIED_SIG, s_UPDATE_SLOT ) );
    return connections;
}

Object signals¶

Objects have signals that can be used to inform of modifications. The base class ::fwData::Object has the following signals available.

Thus all objects in FW4SPL can use the previous signals. Some object classes define extra signals.

Proxy¶

The class ::fwServices::registry::Proxy is a communication element and singleton in the architecture. It defines a proxy for signal/slot connections. The proxy concept is used to declare communication channels: all signals registered in a proxy’s channel are connected to all slots registered in the same channel. This concept is useful to create multiple connections or when the slots/signals have not yet been created (possible in dynamic programs).

The following shows an example where one signal is connected to several slots:

const std::string CHANNEL = "myChannel";

::fwServices::registry::Proxy::sptr proxy
    = ::fwServices::registry::Proxy::getDefault();

::fwCom::Signal< void() >::sptr sig = ::fwCom::Signal< void() >::New();

::fwCom::Slot< void() >::sptr slot1 = ::fwCom::newSlot( &myFunc1 );
::fwCom::Slot< void() >::sptr slot2 = ::fwCom::newSlot( &myFunc2 );
::fwCom::Slot< void() >::sptr slot3 = ::fwCom::newSlot( &myFunc3 );

proxy->connect(CHANNEL, sig);

proxy->connect(CHANNEL, slot1);
proxy->connect(CHANNEL, slot2);
proxy->connect(CHANNEL, slot3);

sig->emit(); // All slots are called

Dynamic program with factories¶

As shown in the Object-Service concept example, it is easy to change an application’s behaviour by simply changing the appropriate data and services. For example changing an image visualisation application to a 3D model visualisation application. Unfourtunely, this is limited to applications based on one service and one data, and thus would impossible to apply on applications containing multiple services and object.

To overcome this, the FW4SPL architecture provides a dynamic management of configurations to allow the use of multiple objects and services.

The xml configuration for an application is defined with the extension ::fwServices::registry::AppConfig.

Dynamic program with application configuration¶

In the fwServices library, an application configuration parser allows to parse XML files and creates and manages objects, services and communications.

// The parser
void main (int argc , char * argv [])
{
    string xmlAppConfigPath = argv [1];

    ::fwServices::AppConfigManager::sptr acm
            = ::fwServices::AppConfigManager::New();

    acm->setConfig(xmlAppConfigPath);
    acm->create(); // Creates objects and services from config.
    acm->start(); // Starts services specified in config.
    acm->update(); // Updates services specified in config.

    acm->stop(); // Stops services specified in config.
    acm->destroy(); // Destroy all services and then data.
}

The following part corresponds to the configuration XML file of the previous Object-Service concept example.

<object uid="image" type ="::fwData::MyData" />

<service uid="frame" impl="DefaultFrame" type="IFrame">
    <!-- service configuration -->
</service>

<service uid="view" impl="MyCustomImageView" type="::fwRender::IRender">
    <in key="object" uid="image" />
    <!-- service configuration -->
</service>

<service uid="reader" impl="MyCustomImageReader" type="::io::IReader" >
    <in key="object" uid="image" />
    <!-- service configuration -->
</service>

<!-- view listen now image modification -->
<connect>
    <signal>image/objectModified</signal>
    <slot>view/receive</slot>
</connect>

<start uid="frame" />
<start uid="view"/>
<start uid="reader"/>

<!-- Read the image on filesystem and notify
     the view to refresh is content -->
<update uid ="reader"/>

This simple example shows how it is possible to build an application with several objects and services using only a program and its configurations files.

Example¶

<extension implements="::fwServices::registry::AppConfig2">
    <id>myAppConfigId</id>
    <parameters>
        <param name="appName" default="my Application" />
        <param name="appIconPath" />
    </parameters>
    <desc>Image Viewer</desc>
    <config>

        <object uid="myImage" type="::fwData::Image" />

        <!--
            Description service of the GUI:
            The ::gui::frame::SDefaultFrame service automatically positions the various
            containers in the application main window.
            Here, it declares a container for the 3D rendering service.
        -->
        <service uid="myFrame" type="::gui::frame::SDefaultFrame">
            <gui>
                <frame>
                    <name>${appName}</name>
                    <icon>${appIconPath}</icon>
                    <minSize width="800" height="600" />
                </frame>
            </gui>
            <registry>
                <!-- Associate the container for the rendering service. -->
                <view sid="myRendering" />
            </registry>
        </service>

        <!--
            Reading service:
            The <file> tag defines the path of the image to load. Here, it is a relative
            path from the repository in which you launch the application.
        -->
        <service uid="myReaderPathFile" type="::ioVTK::SImageReader">
           <inout key="target" uid="myImage" />
           <file>./TutoData/patient1.vtk</file>
        </service>

        <!--
            Visualization service of a 3D medical image:
            This service will render the 3D image.
        -->
        <service uid="myRendering" type="::vtkSimpleNegato::SRenderer">
           <in key="image" uid="myImage" />
        </service>

        <!--
            Definition of the starting order of the different services:
            The frame defines the 3D scene container, so it must be started first.
            The services will be stopped the reverse order compared to the starting one.
        -->
        <start uid="myFrame" />
        <start uid="myReaderPathFile" />
        <start uid="myRendering" />

        <!--
            Definition of the service to update:
            The reading service load the data on the update.
            The render update must be called after the reading of the image.
        -->
        <update uid="myReaderPathFile" />
        <update uid="myRendering" />

    </config>
</extension>

<object uid="matrix" type="::fwData::TransformationMatrix3D">
    <matrix>
    <![CDATA[
        1  0  0  0
        0  1  0  0
        0  0  1  0
        0  0  0  1
    ]]>
    </matrix>
</object>

<object type="::fwData::Integer">
    <value>42</value>
</object>

<object type="::fwData::TransferFunction">
    <colors>
        <step color="#ff0000ff" value="1" />
        <step color="#ffff00ff" value="500" />
        <step color="#00ff00ff" value="1000" />
        <step color="#00ffffff" value="1500" />
        <step color="#0000ffff" value="2000" />
        <step color="#000000ff" value="4000" />
    </colors>
</object>

<item key="myImage">
    <object uid="myImageUid" type="::fwData::Image" />
</item>

<service uid="mesher" type="::opMesh::SMesher">
    <in key="image" uid="imageId" />
    <out key="mesh" uid="meshId" />
</service>

::fwData::Image::csptr image = this->getInput< ::fwData::Image >("image");
::fwData::Mesh::sptr mesh = ::fwData::Mesh::New();
// mesher .....
this->setOutput("mesh", mesh);

<connect channel="myChannel">
    <signal>object_uid/signal_name</signal>
    <slot>service_uid/slot_name</slot>
</connect>

<start uid="service_uid" />

<update uid="service_uid" />

Activity series¶

The ::fwMedData::ActivitySeries has a ::fwData::Composite that contains all the data required by the activity.

class FWMEDDATA_CLASS_API ActivitySeries : public ::fwMedData::Series
{
public:

    /// Constructor
    FWMEDDATA_API ActivitySeries();

    /// Destructor
    FWMEDDATA_API virtual ~ActivitySeries();

    /// Defines shallow copy
    FWMEDDATA_API void shallowCopy( const ::fwData::Object::csptr &_source );

    /// Defines deep copy
    FWMEDDATA_API void cachedDeepCopy( const ::fwData::Object::csptr &_source, DeepCopyCacheType &cache );

    /**
     * @brief Data container
     * @{ */
    ::fwData::Composite::sptr getData () const;
    void setData(const ::fwData::Composite::sptr & val);
    /**  @} */

    /**
     * @brief Activity configuration identifier
     * @{ */
    const std::string &getActivityConfigId () const;
    void setActivityConfigId (const std::string &val);
    /**  @} */

protected:

    /// Activity configuration identifier
    ConfigIdType m_activityConfigId;

    /// Data container
    ::fwData::Composite::sptr m_data;
};

Example¶

<extension implements="::fwActivities::registry::Activities">
   <id>myActivityId</id>
   <title>3D Visu</title>
   <desc>Activity description ...</desc>
   <icon>Bundles/media_0-1/icons/icon-3D.png</icon>
   <requirements>
        <requirement name="param1" type="::fwData::Image" /> <!-- defaults : minOccurs = 1, maxOccurs = 1-->
        <requirement name="param2" type="::fwData::Mesh" maxOccurs="3" >
            <key>Item1</key>
            <key>Item2</key>
            <key>Item3</key>
        </requirement>
        <requirement name="param3" type="::fwData::Mesh" maxOccurs="*" container="vector" />
        <requirement name="imageSeries" type="::fwMedData::ImageSeries" minOccurs="0" maxOccurs="2" />
        <requirement name="modelSeries" type="::fwMedData::ModelSeries" minOccurs="1" maxOccurs="1">
             <desc>Description of the required data....</desc>
             <validator>::fwActivities::validator::ImageProperties</validator>
        </requirement>
        <requirement name="transformationMatrix" type="::fwData::TransformationMatrix3D" minOccurs="0" maxOccurs="1" create="true" />
       <!-- ...-->
   </requirements>
   <builder>::fwActivities::builder::ActivitySeries</builder>
   <validator>::fwActivities::validator::ImageProperties</validator><!-- pour fw4spl_0.9.2 -->
   <appConfig id="myAppConfigId">
       <parameters>
           <parameter replace="registeredImageUid" by="@values.param1" />
           <parameter replace="orientation" by="frontal" />
           <!-- ...-->
       </parameters>
   </appConfig>
</extension>

The activity parameters are (in the following order):

Validators¶

There is three types of validator :

ValidationType validate(
       const ::fwActivities::registry::ActivityInfo& activityInfo,
       SPTR(::fwData::Vector) currentSelection ) const;

ValidationType validate(const CSPTR(::fwMedData::ActivitySeries) &activity ) const;

ValidationType validate(const CSPTR(::fwData::Object) &currentData ) const;

Wizard¶

Services are available to create/launch activities :

SActivityLauncher¶

This action allows to launch an activity according to the selected data.

<service uid="action_newActivity" type="::activities::action::SCreateActivity">
    <!-- Filter mode 'include' allows all given activity id-s.
         Filter mode 'exclude' allows all activity id-s excepted given ones. -->
    <filter>
        <mode>include</mode>
        <id>2DVisualizationActivity</id>
        <id>3DVisualizationActivity</id>
        <id>VolumeRenderingActivity</id>
    </filter>
</service>

SActivityWizard¶

This editor allows to select the data required by an activity in order to create the ActivitySeries. This editor displays a tab widget (one tab by data). It works on a ::fwMedData::SeriesDB and adds the created activity series into the seriesDB.

Overview¶

The multithreading paradigm has become more popular as efforts to further exploit instruction level parallelism have stalled since the late 1990s. This allowed the concept of throughput computing to re-emerge to prominence from the more specialized field of transaction processing:

• Even though it is very difficult to further speed up a single thread or single program, most computer systems are actually multi-tasking among multiple threads or programs.
• Techniques that would allow speedup of the overall system throughput of all tasks would be a meaningful performance gain.

Some advantages include:

• If a thread gets a lot of cache misses, the other thread(s) can continue, taking advantage of the unused computing resources, which thus can lead to faster overall execution, as these resources would have been idle if only a single thread was executed.
• If a thread cannot use all the computing resources of the CPU (because instructions depend on each other’s result), running another thread can avoid leaving these idle.
• If several threads work on the same set of data, they can actually share their cache, leading to better cache usage or synchronization of its values.

Some criticisms of multithreading include:

• Multiple threads can interfere with each other when sharing hardware resources such as caches or translation look aside buffers (TLBs).
• Execution times of a single thread are not improved but can be degraded, even when only one thread is executing. This is due to slower frequencies and/or additional pipeline stages that are necessary to accommodate thread-switching hardware.
• Hardware support for multithreading is more visible to software, thus requiring more changes to both application programs and operating systems than multiprocessing.
• Thread scheduling is also a major problem in multithreading.

Michael K. Gschwind, et al. [1]

Worker and Timer¶

In the FW4SPL architecture, the library fwThread provides few tools to execute asynchronous tasks on different threads.

In this library, the class Worker creates and manages a task loop. The default implementation creates a loop in a new thread. Some tasks can be posted on the worker and will be executed on the managed thread. When the worker is stopped, it waits for the last task to be processed and stops the loop.

::fwThread::Worker::sptr worker = ::fwThread::Worker::New();

::boost::packaged_task<void> task( ::boost::bind( &myFunction ) );
::boost::future< void > future = task.get_future();
::boost::function< void () > f = moveTaskIntoFunction(task);

worker->post(f);

future.wait();
worker->stop();

The Timer class provides single-shot or repetitive timers. A Timer triggers a function once after a delay, or periodically, inside the worker loop. The delay or the period is defined by the duration attribute.

::fwThread::Worker::sptr worker = ::fwThread::Worker::New();

::fwThread::Timer::sptr timer = worker->createTimer();

timer->setFunction(  ::boost::bind( &myFunction)  );

::boost::chrono::milliseconds duration
        = ::boost::chrono::milliseconds(100) ;
timer->setDuration(duration);

timer->start();
//...
timer->stop();

worker->stop();

Mutex¶

The namespace fwCore::mt provides common foundations for multithreading in FW4SPL, especially tools to manage mutual exclusions. In computer science, mutual exclusion refers to the requirement of ensuring that two concurrent threads are not in a critical section at the same time, it is a basic requirement in concurrency control, to prevent race conditions. Here, a critical section refers to a period when the process accesses a shared resource, such as shared memory. A lock system is designed to enforce a mutual exclusion concurrency control policy.

Currently, FW4SPL uses Boost Thread library which allows the use of multiple execution threads with shared data, keeping the C++ code portable. fwCore::mt defines a few typedef over Boost:

namespace fwCore
{
namespace mt
{

typedef ::boost::mutex Mutex;
typedef ::boost::unique_lock< Mutex > ScopedLock;

typedef ::boost::recursive_mutex RecursiveMutex;
typedef ::boost::unique_lock< RecursiveMutex > RecursiveScopedLock;

/// Defines a single writer, multiple readers mutex.
typedef ::boost::shared_mutex ReadWriteMutex;
/**
* @brief Defines a lock of read type for read/write mutex.
* @note Multiple read lock can be done.
*/
typedef ::boost::shared_lock< ReadWriteMutex > ReadLock;
/**
* @brief Defines a lock of write type for read/write mutex.
* @note Only one write lock can be done at once.
*/
typedef ::boost::unique_lock< ReadWriteMutex > WriteLock;
/**
* @brief Defines an upgradable lock type for read/write mutex.
* @note Only one upgradable lock can be done at once but there
        may be multiple read lock.
*/
typedef ::boost::upgrade_lock< ReadWriteMutex > ReadToWriteLock;
/**
* @brief Defines a write lock upgraded from ReadToWriteLock.
* @note Only one upgradable lock can be done at once but there
        may be multiple read lock.
*/
typedef ::boost::upgrade_to_unique_lock< ReadWriteMutex >
            UpgradeToWriteLock;

} //namespace mt
} //namespace fwCore

Multithreading and communication¶

::fwCom::Slot< int (int, int) >::sptr slotSum
        = ::fwCom::newSlot( &sum );
::fwCom::Slot< void () >::sptr slotStart
        = ::fwCom::newSlot( &A::start, &a );

::fwThread::Worker::sptr w = ::fwThread::Worker::New();
slotSum->setWorker(w);
slotStart->setWorker(w);

::boost::future< void > future = slotStart->asyncRun();
// do something else ...
future.wait(); //ensures slotStart is finished before continuing

::boost::future< int > future = slotSum->asyncCall();
// do something else ...
future.wait(); //ensures slotStart is finished before continuing
int result = future.get();

sig2->asyncEmit(21, 42);

Object-Service and Multithreading¶

::fwCore::mt::ReadWriteMutex & getMutex();

::fwData::String::sptr m_data = ::fwData::String::New();
{
    // lock data to write
    ::fwData::mt::ObjectReadLock readLock(m_data);
} // helper destruction, data is no longer locked


{
    // lock data to write
    ::fwData::mt::ObjectWriteLock writeLock(m_data);

    // unlock data
    writeLock.unlock();

    // lock data to read
    ::fwData::mt::ObjectReadToWriteLock updrageLock(m_data);

    // unlock data
    updrageLock.unlock();

    // lock again data to read
    updrageLock.lock();

    // lock data to write
    updrageLock.upgrade();

    // lock data to read
    updrageLock.downgrade();

} // helper destruction, data is no longer locked

// Initializes m_associatedWorker and associates
// this worker to all service slots
void setWorker( ::fwThread::Worker::sptr worker );

// Returns associate worker
::fwThread::Worker::sptr getWorker() const;

Overview¶

Serialization is the process to save plain C++ structures from memory to hard drive. In fw4spl, fwAtoms library provides tools to serialize all data (and especially Object that extend ::fwData::Object) to a JSON format [1]. Of course, this process is also available for loading data from JSON format to plain C++ structures.

To achieve this serialization, fwAtoms provides basic structures (which extend ::fwAtoms::Base) to manage better plain C++ structure evolution. Thus, there are two main steps in the serialization process:

• Converting a ::fwData::Object into a ::fwAtoms::Object
• Serializing a ::fwAtoms::Base in a JSON format

Atom objects¶

The basic structures provided by fwAtoms library are a set of restricted C++ type. All these structures extend ::fwAtoms::Base and cover all basic types and containers:

For instance, consider the following C++ class:

class SimpleClass
{
    bool m_myBoolean;
};

class ComplexClass
{
    std::string m_myString;
    float m_myFloat;
    SimpleClass* m_mySimpleClass;
};

It’s Atom equivalent is (simplified code):

fwAtoms::Object
{
    metaInfos
    {
        "CLASSNAME_METAINFO" : "SimpleClass"
        "ID_METAINFO" : "<ID of the object>"
    }

    attributes
    {
        "myBoolean" : ::fwAtoms::Boolean
    }
}


fwAtoms::Object
{
    metaInfos
    {
        "CLASSNAME_METAINFO" : "ComplexClass"
        "ID_METAINFO" ; "<ID of the object>"
    }

    attributes
    {
        "myString" : ::fwAtoms::String
        "myFloat" : ::fwAtoms::Numeric
        "mySimpleClass" : ::fwAtoms::Object("SimpleClass")
    }
}

The main advantage of this representation is the ability to change easily the form of a class. In fact, all plain C++ objects are represented as Atoms::Object with a map of attributes. Thus, adding, removing or changing the content of an attribute is easy. Moreover, because of these restricted types, atom parsing is also made easier. The main difficulty is how to convert plain C++ object using this set of restricted types.

Convert a fwData::Object¶

As explained earlier, all objects in fw4spl inherit from the ::fwData::Object class. To convert a C++ object in Atom, it must inherit from this class. To allow this conversion, some work must be done.

The first thing is to update the header file of the structure and add these lines :

// Before all namespace
fwCampAutoDeclareDataMacro((<namespace elem>)
        (<namespace elem>)(<class name>), <method export macro>);

// In the public class part
fwCampMakeFriendDataMacro((<namespace elem>)
        (<namespace elem>)(<class name>));

These two functions allow the declaration of the class to the conversion process.

Next, the conversion systems must know the class information including attributes, base class, library location and data version. This is achieved by creating a class which defines these properties.

// Reference class

fwCampAutoDeclareDataMacro((fwData)(ComplexClass), FWDATA_API);

namespace fwData
{
class ComplexClass : public ::fwData::Object
{
    fwCampMakeFriendDataMacro((fwData)(ComplexClass));

    std::string m_myString;
    float m_myFloat;
    ::fwData::SimpleClass* m_mySimpleClass;
};
}

// hpp binding file
#include <fwCamp/macros.hpp>
#include <fwData/ComplexClass.hpp>
#include "fwDataCamp/config.hpp"

fwCampDeclareAccessor((fwData)(ComplexClass), (fwData)(SimpleClass));

// cpp binding file
// include previous cpp file

#include <fwCamp/UserObject.hpp>

fwCampImplementDataMacro((fwData)(ComplexClass))
{
    builder
        .tag("object_version", "1")
        .tag("lib_name", "fwData")
        .base< ::fwData::Object>()
        .property("myString" , &::fwData::ComplexClass::m_myString)
        .property("myFloat" , &::fwData::ComplexClass::m_myFloat)
        .property("mySimpleClass" , &::fwData::ComplexClass::m_mySimpleClass)
        ;
}

localDeclarefwDataComplexClass();

//Convert a fwData::Object into fwAtoms::Object
SPTR(::fwAtoms::Object) convert( const SPTR(::fwData::Object) &data );

//Convert a fwAtoms::Object into fwData::Object
SPTR(::fwData::Object) convert( const SPTR(::fwAtoms::Object) &atom );

Serialize an Atoms object to JSON format¶

When a fw4spl data is converted into Atoms, it can be saved in JSON format. Both an Atom reader and Atom writer are available in the fwAtomsBoostIO fw4spl library: simply instantiate one of these classes with an Atom object and call the read or write method.

To serialize atoms into JSON, a visitor pattern is used. An example can be found in the fwAtomsBoostIO/Reader.cpp file.

Conclusion¶

Accordingly, you have now the requirements to serialize data in the framework and a basic knowledge about the mechanism behind it. To conclude, this is a diagram of the serialization mechanism:

Definitions and characteristics¶

An individual software component is a software package that encapsulates a set of related code: resources, objects, services, XML configuration, etc.

All the architecture is placed into separate components so that all of the data and functions inside each component are semantically related. Because of this principle, it is often said that components are modular and cohesive.

Components communicate with each other via interfaces. When a component offers services to the rest of the system, it adopts a provided interface which specifies services that other components can use. The generic architecture provided by classes Object/IService and the factory system make this interfacing easier.

Re-usability is an important characteristic of a high-quality software component. Programmers should design and implement software components in such a way that many different programs can reuse them.

Component-based implementation¶

Implementation requires a dynamic structure which represents the component and a software launcher which loads and manages these components. A component, called a bundle, is just a simple folder that contains :

• the component description file (plugin.xml) to describe the content of the dynamic library
• the dynamic library, the type of which (.so, .dll, .dylib) differs between operating systems
• other shared resources (icons, XSD file, media files, ...)

The software launcher uses the library fwRuntime to parse the software description file (profile.xml) and load required dynamic libraries:

./fwlauncher.exe mySoftware/profile.xml

The component description file (plugin.xml) is used to describe the content of the dynamic library. This file reveals which concepts and concept implementations are proposed by the component. These terms are identified in the file by keywords:

• Extension point: the concept
• Extension: a concept implementation (there can be many implementations one of a single concept)

In some cases, the Extension point is represented by an abstract class in a component, and the Extension by the class that it inherits from the abstract class of another component.

One example is the service concept. The component description file of servicesReg introduces the concept of service and incorporates the class IService into the dynamic library:

<plugin id="serviceReg">

  <library name="servicesReg" />

  <extension-point id="::fwServices::registry::ServiceFactory" />

</plugin>

And in another component, a new service is proposed in the dynamic library and the information is shared in the description file.

<plugin id="myBundle">

   <library name ="myBundle" />

   <! -- myBundle requires the bundle servicesReg to run -->
   <requirement id="servicesReg" />

   <! -- Need code related to ::io::IReader -->
   <requirement id="io" />

   <extension implements =" ::fwServices::registry::ServiceFactory ">
       <! -- service type -->
       <type>::io::IReader</type>
       <! -- the service name available in this component library -->
       <service>::myBundle::myReader</service>
       <! -- the object type associated to the service -->
       <object>::fwData::myData</object>
       <desc>Description of my reader</desc>
   </extension>

</plugin>

Even if it is often the case, concepts are not limited to class level. A lot a concepts can be defined : service configurations, operator parameters, etc.

Concepts¶

In the FW4SPL architecture, there is an object container which is often used: ::fwData::Composite. This container is also an Object and represents a map which associates a string with an Object. The architecture provides two main services to manage a Composite: a composite updater and a service manager.

Implementation¶

<object id="model" type="::fwMedData::ModelSeries">
    <service uid="listOrganEditor" type="::uiMedData::editor::SModelSeriesList" autoConnect="yes" />
</object>

<object type="::fwData::Composite">
    <service uid="myUpdater" type="::ctrlSelection::updater::SObjFromSlot" >
        <out key="object" uid="reconstruction" /> <!-- key of the updated object -->
    </service>
</object>

<!-- connect updater to listen the reconstruction selection -->
<connect>
    <signal>listOrganEditor/reconstructionSelected</signal>
    <slot>myUpdater/addOrSwap</slot>
</connect>

Overview¶

Graphical User Interface (GUI) is the process of displaying the graphical components of an application. In fw4spl, the fwGui library provides abstract tools to display components like windows, buttons, textfield, aso.

The software architecture provides a way of selecting different backends in order to manage the GUI components. As a result, the fwGuiQt library has been created to display components created using the Qt soup. Presently, this backend is the only one supported by the applications.

Backend¶

When creating an application, we need to specify which gui backend we want to use. To do so, the chosen gui bundle must be activated and started in the profile.xml of the application. The main gui bundle for any application is guiQt. The gui bundle must be activated regardless of the chosen backend.

<activate id="gui" version="0-1" />
<activate id="guiQt" version="0-1" />

<!-- ... -->

<start id="guiQt" />

Warning : The gui backend bundle must be started before any other bundle in the profile.xml.

Configuration¶

<service uid="mainFrame" type="::fwGui::IFrameSrv"
    impl="::gui::frame::DefaultFrame" autoConnect="no" >
    <gui>
        <frame>
            <name>Application name</name>
            <icon>path_to_application_icon</icon>
            <minSize width="800" height="600"/>
        </frame>
        <menuBar />
        <toolBar >
            <toolBitmapSize height= "32" width="32" />
        </toolBar>
    </gui>
    <registry>
        <menuBar sid="menuBar" start="yes" />
        <toolBar sid="toolBar" start="yes" />
        <view sid="view" start="yes" />
    </registry>
</service>

<service uid="menuBar" type="::fwGui::IMenuBarSrv"
    impl="::gui::aspect::DefaultMenuBarSrv" autoConnect="no" >
    <gui>
        <layout>
            <menu name="First Menu"/>
            <menu name="Second Menu"/>
        </layout>
    </gui>
    <registry>
        <menu sid="firstMenu" start="yes" />
        <menu sid="secondMenu" start="yes" />
    </registry>
</service>

<service uid="myMenu" type="::fwGui::IMenuSrv"
    impl="::gui::aspect::DefaultMenuSrv" autoConnect="no" >
    <gui>
        <layout>
            <menuItem name="First Item" icon="icon_path" />
            <menuItem name="Checked Item" style="check" />
            <separator />
            <menuItem name="Quit" shortcut="Ctrl+Q" specialAction="QUIT" />
        </layout>
    </gui>
    <registry>
        <menuItem sid="actionFirstItem" start="no" />
        <menuItem sid="actionCheckedItem" start="no" />
        <menuItem sid="actionQuit" start="no" />
    </registry>
</service>

<service uid="subView" type="::gui::view::IView"
    impl="::gui::view::DefaultView" autoConnect="no" >
    <gui>
        <layout type="::fwGui::LineLayoutManager" >
            <orientation value="horizontal" />
            <view caption="view1" />
            <view caption="view2" />
        </layout>
    </gui>
    <registry>
        <view sid="subView1" start="yes" />
        <view sid="subView2" start="yes" />
    </registry>
</service>

Multi-threading¶

The fwGui library has been designed to support multi-thread application. When a GUI component needs to be accessed, the function call must be encapsulated in a lambda declaration as shown in this example:

::fwGui::registry::Worker::get()->postTask<void>(
[&] {
        //TODO Write function calls
}
).wait();

This encapsulation is required because all access to GUI components must be performed in the thread containing the GUI. It moves the function calls from the current thread, to the GUI thread.

Overview¶

A generic scene in FW4SPL is visualization feature to visualize several elements like meshes or images in a scene. The scene is based on VTK. The main task of the generic scene is to manage all visualization services of the different elements contained in the scene. The generic scene is universal and therefore applicable for divers visualization tasks.

As used in FW4SPL, the scene generic configures a VTK scene with a simple xml configuration. Hence, FW4SPL is mainly used for medical assignments, the generic scene can be seen as fusion of a negatoscope and the 3D model visualization.

Components¶

class MyAdaptor : public ::fwRenderVTK::IVtkAdaptorService
{

public:

    fwCoreServiceClassDefinitionsMacro ( (MyAdaptor)(::fwRenderVTK::IVtkAdaptorService) );

protected:

    /// Parse the adaptor "config" tag
    void configuring() throw(fwTools::Failed);

    /// Initialize the vtk pipeline (actor, mapper, ...)
    void doStart();

    /// Clear the vtk pipeline
    void doStop();

    /// Update the pipeline from the current object
    void doUpdate();

    /// Update the pipeline with the new object (eventually call doStop();doStart();)
    void doSwap();
};

Configuration¶

<service uid="generiSceneUID" impl="::fwRenderVTK::SRender" type="::fwRender::IRender">
    <scene renderMode="auto|timer|none" offScreen="imageKey" width="1920" height="1080">
        <renderer id="myRenderer" layer="0" background="0.0" />
        <vtkObject id="transform" class="vtkTransform" />
        <picker id="negatodefault" vtkclass="fwVtkCellPicker" />

        <adaptor id="tmAdaptor" class="::visuVTKAdaptor::Transform" uid="adaptorUID" objectId="tm3dKey">
            <config transform="transform" />
        </adaptor>
        <adaptor id="snapshot" class="::visuVTKAdaptor::Snapshot" objectId="self">
            <config renderer="myRenderer" />
        </adaptor>

        <!-- ...... -->

        <connect>
            <signal>adaptorUID/modified</signal>
            <slot>serviceUid/updateTM</slot>
        </connect>

        <connect waitForKey="tm3dKey">
            <signal>modified</signal><!-- signal for object "tm3dKey" -->
            <slot>serviceUid/updateTM</slot>
        </connect>

        <proxy channel="myChannel">
            <signal>adaptor2UID/modified</signal>
            <slot>service2Uid/updateTM</slot>
        </proxy>
    </scene>
    <fps>30</fps><!-- used if renderMode=="timer" -->
</service>

renderMode (optional, “auto” by default)

This attribute is forwarded to all adaptors. For each adaptor, if renderMode=”auto”, the scene is automatically rendered after doStart, doUpdate, doSwap, doStop and m_vtkPipelineModified=true. If renderMode=”timer” the scene is rendered at N frame per seconds (N is defined by fps tag). If renderMode=”none” you should call ‘render’ slot to call reder the scene.

offScreen (optional):

Key of the image used for off screen render

width (optional, “1280” by default):

Width for off screen render

height (optional, “720” by default):

Height for off screen render

renderer

Defines a renderer. At least one renderer is mandatory, but there can be multiple renderer on different layers.

• id (mandatory): the identifier of the renderer
• layer (optional): defines the layer of the vtkRenderer. This is only used if there are layered renderers.
• background (optional): the background color of the rendering screen.

The color value can be defines as a grey level value (ex . 1.0 for white) or as a hexadecimal value (ex : #ffffff for white).

vtkObject

Represents a vtk object. It is usually used for vtkTransform or vtkImageBlend.

• id (mandatory): the identifier of the vtkObject
• class (mandatory): the classname of the vtkObject to create. For example vtkTransform, vtkImageBlend, ...

picker

Represents a picker.

• id (mandatory): the identifier of the picker
• vtkclass (optional, by default vtkCellPicker): the classname of the picker to create.

adaptor

Defines the adaptors to display in the scene.

• id (mandatory): the identifier of the adaptor
• class (mandatory): the classname of the adaptor service
• uid (optional): the fwID to specify for the adaptor service
• objectId (mandatory): the key of the adaptor’s object in the scene’s composite.
• autoConnect (optional, “yes” by default): if “yes” the service slot are automatically connected to the object signals.
• config: adaptor’s configuration. It is parsed in the adaptor’s configuring() method.

connect/proxy (optional)

Connects signal to slot

• waitForKey (optional): defines that the connection is made only if the key is present in the scene composite.
• signal (mandatory): must be signal holder UID, followed by ‘/’, followed by signal name.
• slot (mandatory): must be slot holder UID, followed by ‘/’, followed by slot name.

Overview¶

The data migration system consists on converting the data to another version. It allows us to adapt any version of data to any version of software, and thus ensuring compatibility between data and software independently of their version.

Migration process is applied on two independent steps :

• In ::ioAtoms::SReader while reading data files, previously serialized with fwAtoms, right before converting said data to ::fwData::Objects.
• In ::ioAtoms::SWriter after data is converted to fwAtoms::Base.

Definitions¶

Context

It represents a complex chunk of data. For example, the medical patient folder, the software preference file, etc. Hereafter we will consider a medical patient folder which is called MedicalData.

Structural patch

This sort of patch affects only one object of the serialized data regardless of the context (ex: add or remove attribute, type, ...), see Structural patch.

Semantic patch

This sort of patch is applied on a context to migrate to a given version without changing the data structure. (These patches are sometimes called contextual patches), see Semantic patch.

Patcher

A patcher defines the methods to parse the data and applies the structural and semantic patches, see Patcher.

Data Version¶

After the conversion from ::fwData::Object to ::fwAtoms::Object, each data is assigned a version number. Said number is defined in the camp serialization source files (see Serialization). Each data structure modification causes an incrementation of the data version.

Example of data declaration for introspection (used to convert to fwAtoms):

#include <fwCamp/UserObject.hpp>

fwCampImplementDataMacro((fwData)(ComplexClass))
{
    builder
        .tag("object_version", "1") // data version
        .tag("lib_name", "fwData")
        .base< ::fwData::Object>()
        .property("myString" , &::fwData::ComplexClass::m_myString)
        .property("myFloat" , &::fwData::ComplexClass::m_myFloat)
        .property("mySimpleClass" , &::fwData::ComplexClass::m_mySimpleClass)
        ;
}

Context version¶

The context version must be incremented after a data version modification.

The .versions file contains a detailed description of the context version, and the version of each data.

Example of V1.versions:

{
    "context": "MedicalData",
    "version_name": "V1",
    "versions":
    {
        "::fwData::Array": "1",
        "::fwData::Boolean": "1",
        "::fwData::Image": "1",
        "::fwData::Integer": "1",
        "::fwData::Material": "1",
        "::fwData::Mesh": "1",
        "::fwData::Patient": "1",
    }
}

Example of V2.versions:

{
    "context": "MedicalData",
    "version_name": "V2",
    "versions":
    {
        "::fwData::Array": "1",
        "::fwData::Boolean": "1",
        "::fwData::Image": "2",
        "::fwData::Integer": "1",
        "::fwData::Material": "1",
        "::fwData::Mesh": "1",
        "::fwMedData::Patient": "1",
    }
}

Migration¶

The migration is applied on a given context. It is described in the .graphlink file. It defines how to migrate from a context version to another.

Example of V1ToV2.graphlink:

{
    "context" : "MedicalData",
    "origin_version" : "V1",
    "target_version" : "V2",
    "patcher" : "DefaultPatcher",
    "links" : [
        {
            "::fwData::Patient" : "1",
            "::fwMedData::Patient" : "1"
        },
        {
            "::fwData::Image" : "1",
            "::fwData::Image" : "2"
        }
    ]
}

The links tag represents the data version modifications, by doing so, associated patches can be applied.

Graph¶

The .graphlink and .versions files are parsed and the information is stored in the ::fwAtoms::VersionsManager. Each context defines a graph.

Example of graph:

The graph is used to find the migration path from an initial version to a target version. In our example, it is possible to migrate from V1 to V5, the data is converted to V3, V4 then V5. If several paths are possible, the shortest path is used.

Structure¶

The fwAtomsPatch library contains the base classes to perform the migration.

PatchingManager

This class provides the transformTo() method used to migrate the data. It uses the graph to apply the patcher on each version.

patcher::IPatcher

Base class for patchers.

patcher::DefaultPatcher

Patcher used by default. It performs the data migration in two steps: first it applies the structural patches recursivly on each sub-object and then applies the semantic patches recursivly on each sub-object .

IPatch

Base class for structural and semantic patches. It provides an apply() method that must be implemented in sub-classes.

ISemanticPatch

Base class for semantic patches.

IStructuralPatch

Base class for structural patches.

IStructuralCreator

Base class for creators. It provides a create() method that must be implemented in sub-classes.

SemanticPatchDB

Singleton used to register all the semantic patches.

StructuralPatchDB

Singleton used to register all the structural patches.

CreatorPatchDB

Singleton used to register all the creator patches.

VersionsGraph

Registers the migration graphs.

VersionsManager

Singleton used to register all the version graph.

The fwStructuralPatch library contains the structural patches for fwData and fwMedData conversion.

The fwMDSemanticPatch library contains the semantic patches for fwData and fwMedData conversion in the MedicalData context.

The patchMedicalData bundle must be activated in your application to allow migration in MedicalData context.

#include "fwStructuralPatch/fwData/Image/V1ToV2.hpp"

#include <fwAtoms/Numeric.hpp>
#include <fwAtoms/Numeric.hxx>

namespace fwStructuralPatch
{

namespace fwData
{

namespace Image
{

V1ToV2::V1ToV2() : ::fwAtomsPatch::IStructuralPatch()
{
    m_originClassname = "::fwData::Image";
    m_targetClassname = "::fwData::Image";
    m_originVersion   = "1";
    m_targetVersion   = "2";

}

// ----------------------------------------------------------------------------

void V1ToV2::apply(
    const ::fwAtoms::Object::sptr& previous, // object in the origin version
    const ::fwAtoms::Object::sptr& current, // clone of the previous object to convert in the targer version
    ::fwAtomsPatch::IPatch::NewVersionsType& newVersions) // map < previous object, new object > association
{
    // Check if the previous and current object version and classname correspond
    IStructuralPatch::apply(previous, current, newVersions);

    // Update object version
    this->updateVersion(current);

    // Create helper
    ::fwAtomsPatch::helper::Object helper(current);

    helper.addAttribute("nb_components", ::fwAtoms::Numeric::New(1));
    helper.addAttribute("window_center", ::fwAtoms::Numeric::New(50));
    helper.addAttribute("window_width", ::fwAtoms::Numeric::New(500));
}

} // namespace Image

} // namespace fwData

} // namespace fwStructuralPatch

// fwStructuralPatch/autoload.cpp

::fwAtomsPatch::StructuralPatchDB::sptr structuralPatches = ::fwAtomsPatch::StructuralPatchDB::getDefault();
structuralPatches->registerPatch(::fwStructuralPatch::fwData::Image::V1ToV2::New());

#include "fwStructuralPatch/creator/fwMedData/Patient1.hpp"

#include <fwAtoms/String.hpp>

#include <fwAtomsPatch/helper/Object.hpp>

namespace fwStructuralPatch
{
namespace creator
{
namespace fwMedData
{

Patient1::Patient1()
{
    m_classname = "::fwMedData::Patient";
    m_version   = "1";
}

// ----------------------------------------------------------------------------

::fwAtoms::Object::sptr Patient1::create()
{
    // Create an empty ::fwAtoms::Object with the classname, version and ID informtation
    ::fwAtoms::Object::sptr patient = this->createObjBase();

    ::fwAtomsPatch::helper::Object helper(patient);

    helper.addAttribute("name", ::fwAtoms::String::New(""));
    helper.addAttribute("patient_id", ::fwAtoms::String::New(""));
    helper.addAttribute("birth_date", ::fwAtoms::String::New(""));
    helper.addAttribute("sex", ::fwAtoms::String::New(""));

    return patient;
}

} // namespace fwMedData
} // namespace creator
} // namespace fwStructuralPatch

// fwStructuralPatch/creator/autoload.cpp

::fwAtomsPatch::StructuralCreatorDB::sptr creators = ::fwAtomsPatch::StructuralCreatorDB::getDefault();
creators->registerCreator(::fwStructuralPatch::creator::fwMedData::Equipment1::New());

#include "fwMDSemanticPatch/V2/V3/fwData/Image.hpp"

#include <fwAtoms/Object.hpp>
#include <fwAtoms/Object.hxx>
#include <fwAtoms/Numeric.hpp>
#include <fwAtoms/Numeric.hxx>

#include <fwAtomsPatch/helper/functions.hpp>


namespace fwMDSemanticPatch
{
namespace V2
{
namespace V3
{
namespace fwData
{

Image::Image() : ::fwAtomsPatch::ISemanticPatch()
{
    m_originClassname = "::fwData::Image";
    m_originVersion   = "1";
    this->addContext("MedicalData", "V2", "V3"); // Context version
}

// ----------------------------------------------------------------------------

void Image::apply(
    const ::fwAtoms::Object::sptr& previous, // object in the origin version
    const ::fwAtoms::Object::sptr& current, // clone of the previous object to convert in the targer version
    ::fwAtomsPatch::IPatch::NewVersionsType& newVersions) // map < previous object, new object > association
{
    // Check if the previous and current object version and classname correspond
    ISemanticPatch::apply(previous, current, newVersions);

    // Cleans object fields (also creates them if they are missing)
    ::fwAtomsPatch::helper::cleanFields( current );

    ::fwAtomsPatch::helper::Object helper( current );

    ::fwAtoms::Object::sptr array        = ::fwAtoms::Object::dynamicCast(previous->getAttribute("array"));
    ::fwAtoms::Numeric::sptr nbComponent =
             ::fwAtoms::Numeric::dynamicCast(array->getAttribute("nb_of_components"));

    helper.replaceAttribute("nb_components", nbComponent->clone());
}

// ----------------------------------------------------------------------------

} // namespace fwData
} // namespace V3
} // namespace V2
} // namespace fwMDSemanticPatch

// fwMDSemanticPatch/V1/V2/fwData/autoload.cpp
::fwAtomsPatch::SemanticPatchDB::sptr contextPatchDB = ::fwAtomsPatch::SemanticPatchDB::getDefault();
contextPatchDB->registerPatch(::fwMDSemanticPatch::V1::V2::fwData::Composite::New());