FW4SPL documentation¶

Features¶

• Reader/Writer

  • VTK (images and meshes)
  • DICOM
  • ITK
  • atoms (in-houte data format)

• Visualisation

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

Application¶

VRRender is an application 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.

Features¶

• additional DICOM reader/writer

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

• navigation along a spline

• timeline

• network communication via openigtlink

Application¶

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

Proofs of concept¶

Examples¶

Features¶

• video calibration
• optical tag tracking

Applications¶

ARCalibration¶

ARCalibration is an application dedicated to the camera calibration.

Mono camera intrinsic calibration.

Stereo camera extrinsic calibration.

Prerequisites for Windows users¶

If not already installed:

1. Install Mercurial
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 environment for a x64 version. For 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 launcher.exe from FW4SPL. Therefore the profile.xml of the application in the build folder has to be passed as argument.

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.0
5. Install Ninja

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

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

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

FW4SPL installation¶

FW4SPL works with data separation for source, build and install data. To prepare the development environment:

• Create your “Dev” directory

$ 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

To prepare the third party environment:

• 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

$ cd Dev/Build/Debug
$ ccmake ../../Src/fw4spl

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

Dependencies¶

• Clone the repository into your source directory of Deps

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

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

$ cd fw4spl-deps
$ git checkout fw4spl_0.10.2.3

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

$ cd Deps/Build/Debug

• Call ccmake and point to the sources

$ ccmake ../../Src/fw4spl-deps

To build the dependencies, you must configure the project with cmake into the Build folder

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

Or open cmake gui editor, see Build tools instructions.

$ ccmake ../Src/fw4spl-deps

Some CMake variables have to be change:

• CMAKE_INSTALL_PREFIX: set the install location.
• CMAKE_BUILD_TYPE: set the build type ‘Debug’ or ‘Release’

Press configure ([c]) and generate ([g]) makefiles.

• Compile the FW4SPL dependencies with make in the console, it will automaticaly download, build and install each dependencies.

$ make all

Warning

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

Source¶

• Clone fw4spl repository into your source directory

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

• Get into fw4spl folder and update to the latest stable version

$ cd fw4spl
$ git checkout fw4spl_0.10.2.3

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

$ cd Dev/Build/Debug

• Call ccmake and point to the sources

To use make :

$ 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 part libraries.(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 ”;”.

Note

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

Press configure ([c]) and generate ([g]) makefiles.

Then, build dependencies with ninja.

$ ninja all

Launch an application¶

To build a specific or several applications the CMake argument PROJECTS_TO_BUILD can be set. Use ; so separate each application name.

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

$ bin/launcher Bundles/MyApplication_Version/profile.xml

Example:

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

Extensions¶

fw4spl has two extension repositories:

• fw4spl-ext: contains additional functionalities and proofs of concept
• fw4spl-ar: contains functionalities for augmented reality (video tracking, calibration)

$ cd ~/Dev/Deps/Src
$ git clone https://github.com/fw4spl-org/fw4spl-ext-deps.git fw4spl-ext-deps
$ cd fw4spl-ext-deps
$ git checkout fw4spl_0.10.2.3

$ cd ~/Dev/Deps/Src
$ git clone https://github.com/fw4spl-org/fw4spl-ar-deps.git fw4spl-ar-deps
$ cd fw4spl-ar-deps
$ git checkout fw4spl_0.10.2.3

$ cd ~/Dev/Deps/Build
$ ccmake .

~/Dev/Deps/Src/fw4spl-ext-deps/;~/Dev/Deps/Src/fw4spl-ar-deps/

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

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

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

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
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 works with data separation for source, build and install data. To prepare the development environment:

• Create a development folder (Dev)

$ mkdir Dev

• Create the build, source and install folder

  • Dev/Build
  • Dev/Src
  • Dev/Install

$ mkdir Dev/Build Dev/Src Dev/Install

To prepare the third party environment:

• Create a third party folder (Deps)

$ mkdir Dev/Deps

• Create the build, source and install folder

  • Dev/Deps/Build
  • Dev/Deps/Src
  • Dev/Deps/Install

$ mkdir Dev/Deps/Build Dev/Deps/Src Dev/Deps/Install

$ ccmake /PATH/TO/fw4spl

$ ccmake -G Ninja /PATH/TO/fw4spl

Dependencies¶

For the third party libraries the following repository have to be cloned in the (Deps) source folder:

• fw4spl-deps: contains the scripts to compile the external libraries used by fw4spl (Boost, VTK, ITK, Qt, …​)

$ cd ~/Dev/Deps/Src
$ git clone https://github.com/fw4spl-org/fw4spl-deps.git fw4spl-deps
$ cd fw4spl-deps
$ git checkout fw4spl_0.10.2.3

To build the dependencies, you must configure the project with cmake into the Build folder

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

Or open cmake gui editor, see Build tools instructions.

$ ccmake ../Src/fw4spl-deps

Some CMake variables have to be change:

• CMAKE_INSTALL_PREFIX: set the install location.
• CMAKE_BUILD_TYPE: set the build type ‘Debug’ or ‘Release’

Press configure ([c]) and generate ([g]) makefiles.

Then, compile the FW4SPL dependencies with make

$ make all
$ make install_tool

Warning

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

Source¶

For the FW4SPL source code the following repository have to be cloned in the (Dev) source folder:

• fw4spl: main repository, contains the core libraries and bundles.

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

Note

For the source compilation we use ninja instead of make. But if you prefer to use make, replace all the ninja command with make and remove -G Ninja in the cmake command.

To build fw4spl, you must configure the project with cmake into the Build folder

$ cd ~/Dev/Build
$ cmake ../Src/fw4spl -DCMAKE_INSTALL_PREFIX=../Install -DCMAKE_BUILD_TYPE=Debug -DEXTERNAL_LIBRARIES=../Deps/Install -G Ninja

Or open cmake gui editor, see Build tools instructions.

$ ccmake ../Src/fw4spl -G Ninja

Some CMake variables have to be change:

• CMAKE_INSTALL_PREFIX: set the install location.
• EXTERNAL_LIBRARIES: set the install path of the third part libraries.
• CMAKE_BUILD_TYPE: set to Debug or Release

You can re-edit cmake configuration :

$ ccmake .

• PROJECT_TO_BUILD set the name of the application to build (See DevSrcApps)
• 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 aplication will be installed

Press configure ([c]) and generate ([g]) makefiles.

Then, build dependencies with ninja.

$ ninja all

Launch an application¶

To build a specific or several applications the CMake argument PROJECTS_TO_BUILD can be set. Use ; so separate each application name.

After an successful compilation the application can be launched with the launcher program from a terminal. Therefore the profile.xml of the application in the build folder has to be passed as argument to the launcher:

$ bin/launcher Bundles/MyApplication_Version/profile.xml

Example:

$ cd ~/Dev/Build
$ bin/launcher Bundles/VRRender_0-9/profile.xml

Extension¶

fw4spl has two extension repositories:

• fw4spl-ext: contains additional functionalities and proofs of concept
• fw4spl-ar: contains functionalities for augmented reality (video tracking, calibration)

$ cd ~/Dev/Deps/Src
$ git clone https://github.com/fw4spl-org/fw4spl-ext-deps.git fw4spl-ext-deps
$ cd fw4spl-ext-deps
$ git checkout fw4spl_0.10.2.3

$ cd ~/Dev/Deps/Src
$ git clone https://github.com/fw4spl-org/fw4spl-ar-deps.git fw4spl-ar-deps
$ cd fw4spl-ar-deps
$ git checkout fw4spl_0.10.2.3

$ cd ~/Dev/Deps/Build
$ ccmake .

~/Dev/Deps/Src/fw4spl-ext-deps/;~/Dev/Deps/Src/fw4spl-ar-deps/

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

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

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

Recommended softwares¶

The following programs may be helpful for your developments:

• IDE:

  • Qt creator
  • Eclipse CDT.

• Versioning tools:

  • SourceTree

Introduction¶

The framework FW4SPL (FrameWork for Software Production) is an open-source framework, developed by IRCAD (research institute against cancer and disease). The principle of FW4SPL is the fast and easy creation of applications, mainly in the medical field. Therefore it provides features like digital image processing in 2D and 3D, visualization or simulation of medical interactions. To build an application with FW4SPL there are no programming skills required. By writing a simple XML the users can design their own application.

FW4SPL is built on component-based 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 and MacOS. The programming language of the framework is C++. This document will introduce the general architecture of FW4SPL.

Annexes¶

• Srclib list: this document lists all libraries with a brief description.
• Object list: this document lists all data with a brief description.
• Service list: this document lists all services and bundles with a brief description.
• Third party: this document contains a description of libraries used to support this architecture and its functions.
• OSR diagram: this document introduces how to represent an application configuration as a diagram.

Introduction¶

Inside the Object Oriented Programming (OOP) paradigm, an object is an instance of a class which contains all its data and methods (such as reading, writing, visualizations, image analysis, etc.). This philosophy works well, provided that the classes do not change with time. However, in this situation, the maintenance of source code is difficult.

In order to make this maintenance easier, FW4SPL architecture relies on an Object-Service paradigm where data and their methods 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.) without depending on the input data format. For example, an input image could have one of several formats such as Jpeg or Dicom but the FW4SPl object will be the same.

Moreover, 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 FW4SPL’s main data library. 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. A service is always associated with a data. For example, image data can have a reader service, a writer service, a visualization service or a processing operator.

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 possible to cast it)
::fwData::Object::sptr obj = ::fwData::factory::New("MyData");

// 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
{
  // relation map beetwen an object and his associated services
  map < Object *, vec < IService > > osr;

  // Associates a service to an object
  // manages in the function the association: srv->setObject(obj);
  void registerService ( Object * obj , IService * srv );

  // Dissociates a service to his object
  void unregisterService ( IService * srv );

  // ...
}

// Some helpers exist : below, add method is used to combine
// factory system with service registration
::fwServices::IService::sptr add(::fwData::Object::sptr obj,
        std::string serviceType, std::string _implementationId)

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

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.

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¶

Slots are used in both objects and services, whereas signals 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::getObjSrvConnections(). 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::KeyConnectionsType IService::getObjSrvConnections() const
{
    KeyConnectionsType connections;
    connections.push_back( std::make_pair( ::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" >
        <!-- service configuration -->
    </service>

    <service uid="reader" impl="MyCustomImageReader"
             type="::io::IReader" >
        <!-- 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"/>

</ object >

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::AppConfig">
    <id>myAppConfigId</id>
    <parameters>
        <param name="appName" default="my Application" />
        <param name="appIconPath" />
    </parameters>
    <desc>Image Viewer</desc>
    <config>

        <object type="::fwData::Composite">

            <!--
                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" impl="::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>

            <item key="myImage">
                <object uid="myImageUid" type="::fwData::Image">
                    <!--
                        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" impl="::ioVTK::SImageReader">
                        <file>./TutoData/patient1.vtk</file>
                    </service>

                    <!--
                        Visualization service of a 3D medical image:
                        This service will render the 3D image.
                    -->
                    <service uid="myRendering" impl="::vtkSimpleNegato::SRenderer" />
                </object>
            </item>

            <!--
                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" />

        </object>

    </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>

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

<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>

<connect>
    <signal>object_uid/signal_name</signal>
    <slot>service_uid/slot_name</slot>
</connect>

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

<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" container="composite">
           <key>Item1</key>
           <key>Item2</key>
           <key>Item3</key>
       </requirement>
       <requirement name="imageSeries" type="::fwMedData::ImageSeries" minOccurs="0" maxOccurs="2" />
       <requirement name="modelSeries" type="::fwMedData::ModelSeries" minOccurs="1" maxOccurs="1" />
       <!-- ...-->
   </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):

icon¶

The path to the activity icon. It is displayed by the SActivityLauncher when several activity can be launched with the selected data.

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:

./launcher.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_uid" type="::fwMedData::ModelSeries">
    <service uid="${GENERIC_UID}_listOrganEditor" impl="::uiMedData::editor::SModelSeriesList"
        type="::gui::editor::IEditor" autoConnect="yes" />
</object>

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

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

<object type="::fwData::Composite">
  <service uid="manager_uid" impl="::ctrlSelection::manager::SwapperSrv"
        type="::ctrlSelection::IManagerSrv" autoConnect="yes" >
        <mode type="dummy" />
        <config>
            <object id="rec" type="::fwData::Reconstruction">
                <service uid="organMaterialEditor" impl="::uiReconstruction::OrganMaterialEditor"
                    type="::gui::editor::IEditor" />
                <service uid="representationEditor" impl="::uiReconstruction::RepresentationEditor"
                    type="::gui::editor::IEditor" />
            </object>
    </config>
  </service>
</object>

<object type="::fwData::Composite">
    <service uid="manager_uid" impl="::ctrlSelection::manager::SwapperSrv"
        type="::ctrlSelection::IManagerSrv" autoConnect="yes" >
        <mode type="dummy" />
        <config>
            <object id="rec" type="::fwData::Reconstruction">

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

                <connect>
                    <signal>object_uid/signal_name</signal>
                    <slot>service_uid/slot_name</slot>
                </connect>

                <connect>
                    <signal>signal_name</signal><!-- signal from recontruction "rec" -->
                    <slot>service_uid/slot_name</slot>
                </connect>
            </object>
        </config>
    </service>
<object>

<object type="::fwData::Composite">
    <service uid="manager_uid" impl="::ctrlSelection::manager::SwapperSrv"
        type="::ctrlSelection::IManagerSrv" autoConnect="yes" >
        <mode type="dummy" />
        <config>
            <object id="rec" type="::fwData::Reconstruction">

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

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

                <proxy channel="myOtherChannel">
                    <signal>signal_name</signal><!-- signal from recontruction "rec" -->
                    <slot>service_uid/slot_name</slot>
                </proxy>
            </object>
        </config>
    </service>
<object>

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());

Usage¶

If you have to modify data, you don’t have to re-implement all the migration system, but there are steps to perform :

step 1

Increment the data version in camp declaration (and update the declaration of the attribute if needed). See Data Version.

step 2

Increment the context version: create new .versions files (with the associated data version). See Context version.

step 3

Create the .graphlink file. See graphlink.

step 4 (optional)

Create the creator if you need to add a new non-null objet. See Creator.

step 5

Create the structural patch. See Structural patch.

step 6 (optional)

Create the semantic patch if you need other objects to update the current one. See Semantic patch.

Source and files¶

Rule 4 : Files tree

Source files must be placed in a folder src/. Public header files must be placed in a folder include/. Private headers may be placed in a different location.

Rule 5 : Files hierarchy

The file hierarchy should follow the namespace hierarchy. For instance, the implementation of a class ::ns1::ns2::SService should be put in src/ns1/ns2/SService.cpp.

Rule 6 : Files extensions

Header files use the extension .hpp.

Implementation files use the extension .cpp.

Files containing implementation of “template” classes use the extension .hxx.

Recommendation 2 : Only one class per file

It is recommended to declare (or to implement) only one class per file. However tiny classes may be declared inside the same file.

Rule 7 : Includes

Use the right include directive depending on the context. #include "..." must be used to import headers from the same module, whereas #include <...> must be used to import headers from other modules.

Rule 8 : Include path

The include path is not an absolute path depending on a local file system. A correct include path does respect the letter case of the filenames and folders (since some platforms require it) and uses the character ‘/’ as a separator.

Rule 9 : Protection against multiple inclusions

You must protect your files against multiple inclusions. To this end, use the standard directives of the precompiler #ifndef and #define (since #pragma once is only supported by Microsoft compilers).

Use the name of the file and the namespace hierarchy inside the define name in order to prevent any conflict with a file which has the same name but located in a different namespace. Namespaces and file name must be separated by a single underscore _. The define name must be prefixed and suffixed by two underscores __. Last, a comment must be placed after #endif to quote the define.

#ifndef __NAMESPACEA_NAMESPACEB_SAMPLE_HPP__ // Preamble protecting against
#define __NAMESPACEA_NAMESPACEB_SAMPLE_HPP__ // multiple inclusions.

#endif // __NAMESPACEA_NAMESPACEB_SAMPLE_HPP__

Recommendation 3 : Independent headers

A header should compile alone. All necessary includes should be contained inside the header itself. In the following sample :

// Header.hpp

class Foo
{
public:
    std::string m_string;
}

you will be forced to include the file in this way to get a successful build :

// Source.hpp

#include <string>
#include "Header.hpp"

This is a bad practice, the header should rather be written :

// Header.hpp

#include <string>

// Header.hpp
class Foo
{
public:
    std::string m_string;
}

So that people can simply include the header :

// Source.hpp

#include "Header.hpp"

Recommendation 4 : Minimize inclusions

Try to minimize as much as possible inclusions inside a header file. Include only what you use. Use forward declarations when you can (i.e. a type or class structure is not referenced inside the header). This will limit dependency between files and reduce compile time. Hiding the implementation can also help to minimize inclusions (see Hide implementation)

Rule 10 : Sort headers inclusions

You must sort headers in the following order : same module, framework libraries, bundles, external libraries, standard library. This way, this helps to make each header independent. The rule can be broken if a different include order is necessary to get a successful build.

#include "currentModule.hpp"

#include <libSampleB/second.hpp>
#include <libSampleA/first.hpp>
#include <libSampleB/subModule/first.hpp>

#include <Qt/QtGui>
#include <vector>
#include <map>

Recommendation 5 : Sort inclusions alphanumerically

In addition to the previous sort, you may sort includes in alphanumerical order, according to the whole path. Thus they will be grouped by module. For a better readability, an empty line can be added between each module.

#include "currentModule.hpp"

#include <libSampleA/first.hpp>
#include <libSampleB/second.hpp>

#include <libSampleB/subModule/first.hpp>
#include <libSampleB/subModule/second.hpp>

#include <Qt/QtGui>

#include <map>
#include <vector>

Naming conventions¶

Rule 11 : Class

Class names must be written in upper camel case. It should not repeat a namespace name. For instance ::editor::SCustomEditor should be rather called ::editor::SCustom.

Rule 12 : File

The name of the file should be based on the class name defined in it. It must follow the same letter case.

Rule 13 : Namespace

Namespaces must be written in camel case. A comment quoting the namespace must be placed next to the ending ‘}’.

namespace namespaceA
{
namespace namespaceB
{
    class Sample
    {
    ...
    };
} // namespace namespaceB
} // namespace namespaceA

When referring a namespace, you must put :: if this is a root namespace, with an exception for std namespace. Ex: ::boost::filesystem.

Rule 14 : Function and method names

Functions and methods names must be written in camel case.

Recommendation 6 : Correct naming of functions

Try as much as possible to help the users of your code by using comprehensive names. You may for instance help them to indicate the cost of a function. A function that executes a search to retrieve an object must not be called like a getter. In this case, it is better to call it findObjet() instead of getObject().

Rule 15 : Variable

Variable names must be written in camel case. Members of a class are prefixed with a m_.

class SampleClass
{
private:
   int m_identifier;
   float m_value;
};

Static variables are prefixed with a s_.

static int s_staticVar;

Rule 16 : Constant

Constant variables must be written in snake_case but in capitals, and follow the previous rule.

class SampleClass
{
    static const int s_AAA_BBB_CCC_VALUE = 1;
};

void fooFunction()
{
    const int AAA_BBB_VAR = 1;
    ...
}

Rule 17 : Type

Type names, like classes, must be written in upper camel case.

typedef int CustomType;
typedef vector<int> CustomContainer;

Rule 18 : Template parameter

Template parameters must be written in capitals. In addition, they must be short and explicit.

template< class KEY, class VALUE > class SampleClass
{
    ...
};

Rule 19 : Macro

Macros without parameters must be written in capitals. On the contrary, there is no specific rule on macros with parameters.

#define CUSTOM_FLAG_A 1
#define CUSTOM_FLAG_B 1

#define CUSTOM_MACRO_A( x ) x
#define Custom_Macro_B( x ) x
#define custom_Macro_C( x ) x
#define custom_macro_d( x ) x

Rule 20 : Enumerated type

An enumerated type name must be written in upper camel case. Labels must be written in capitals. If a typedef is defined, it follows the upper camel case standard.

typedef enum SampleEnum
{
    LABEL_1,
    LABEL_2
    ...
} SampleEnumType;

Rule 21 : Service

A service implementation is identified by a S at the beginning of the class name. Example : SCustomEditor. A service interface is identified by a I at the beginning of the class name. Example : IEditor.

Rule 22 : Signal

A signal name must be prefixed with sig. It should be suffixed by a past action (ex: Updated, Triggered, Cancelled, CakeCookedAndBaked). It follows other common variable naming rules (member of a class, etc...).

class Sample
{
    SigType::sptr m_sigImageDisplayed;
};

Rule 23 : Slot

A slot name must be prefixed with slot. It should be suffixed by an imperative order (Ex: Update, Run, Detach, Deliver, OpenWebBrowser, GoToFail). It follows other common variable naming rules (member of a class, etc...).

class Sample
{
    SlotType::sptr m_slotDisplayImage;
}

Coding rules¶