How to generate ToF DeviceModules

The ToF-DeviceModule-Tutorial will help you implementing a new ToF-Device easily. Using MicroServices for this purpose will be one of our main goals, too.

If you do not know much about MicroServices, please take a look at:

The C++ Micro Services

Generating a ToF-Device-Module in MITK

In order to implement your own device, you need to code the following objects:

• device (the device itself)
• device factory (a singleton which produces instances of your device)
• controller (connection to the Hardware-SDK)
• Module Activator (Important for the MicroServices. This class ensures the automatic loading of the device.)

The following example shows how to implement a device, here we take the Kinect.

1. Creating a Sub-Folder
   Following the Kinect-DeviceModule as a prototype, create a MODULENAME-Sub-Folder in your source directory. This MODULENAME-Folder is going to hold all the necessary files we will create in the next steps.

2. Create the CMake Files for our new camera-model in the MODULENAME-Folder <

   • CMakeList.txt

     In this file, the module is generated via CMake commands. The module name is set, the necessary libraries will be searched here in order to link them with your module. For the Kinect, we chose OpenNI and need the XnCppWrapper.h. Your device must inherit from the mitkToFCameraDevice and consequently your module must depend on mitkToFHardware -> what is the reason for the DEPENDS mitkToFHardware -line. For autoloading your Module with mitkToFHardware, insert the following CMake Macro: AUTOLOAD_WITH mitkToFHardware . We usually add an option for the user to activate the device module, but this is not essential (refer to OPTION(MITK_USE_TOF_KINECT "Enable support for Kinect camera" OFF)).
     -> refer to CMakeList.text in the Kinect-Folder

     Warning: The dll/so files are not automatically deleted.

     
     

   • files.cmake The files.cmake contains all the previously mentioned files (device, deviceFactory, controller, and ModuleActivator)
     -> refer to mitkKinectActivator.cpp

3. Creating the Code Files in the MODULENAME-Folder

   • MODULENAMEController
     -> While referring to mitkKinectcontroller.cpp and the mitkKinectcontroller.h, take a good look at the definition of the MITK_KINECTMODULE_EXPORT-class in the .h file

     
     

   • MODULENAMEDevice Your device must inherit from ToFCameraDevice (e.g. class MITK_KINECTMODULE_EXPORT KinectDevice : public ToFCameraDevice) and consequently implement the methods of the ToFCameraDevice MicroService-Interface. (See ToFCameraDevice.h). Make sure to give your device a specific name in the method GetDeviceName(). All instances of your device will automatically be available in the view "ToFUtil", if you generate it via the factory.
     -> refer to mitkKinectDevice.cpp and the mitkKinectDevice.h.

     
     

   • MODULENAMEDeviceFactory Like the mitkToFCameraDevice, the mitkIToFDeviceFactory is a MicroService-Interface. The factory is meant for generation of devices of the same type. This concept allows for having multiple instances of the same camera connected. (Currently our GUI does not really support an actual connection of multiple devices, but the software framework, in principle, does.) Your factory must inherit from the mitkAbstractDeviceFactory, which provides some useful methods for device generation. Your factory instance should be registered as MicroService in order to be available in the view "ToF Device Generation".
     -> refer to mitkKinectDeviceFactory.cpp and the mitkKinectDeviceFactory.h

     
     

   • MODULENAMEActivator The load() method of this class will be called when the module is activated. If you would like to have an instance of your device registered as MicroService, you should call deviceFactory->ConnectToFDevice(); here. In addition, you can generate devices anywhere in your code via this method. The factory will automatically be available in the view "ToF Device Generation" if you register it like we do with the Kinect. TODO: Code example:
     ->refer to mitkKinectActivator.cpp and the mitkKinectActivator.h or the mitkPMDModuleActivator.cpp and the mitkPMDModuleActivator.h.

If you did everything correct, your Module should be implemented an executable MODULENAME-Project will be generated and a working device should show up in the ServiceListWidget in the Connection-Part of ToFUtil. Warning The dll/so files are not automatically deleted. After deactivating a device, please delete the concerning files in SUPERBUILDDIR/MITK-build/bin/mitkToFHardware/BUILDTYPE

[OPTIONAL] Adding a Testing Sub-Directory

If you have any Tests you want to include, a Testing-Subdirectory in the newly created MODULENAME-Folder should be created. In this Folder we are going to put a CMakeLists.txt and a files.cmake the first one will just consist

\code
MITK_CREATE_MODULE_TESTS()
\endcode

while the later one, the files.cmake holds Information about TestFiles you created and put in the Folder. E.g. for the Kinect:

set(MODULE_TESTS
mitkKinectControllerTest.cpp
mitkKinectDeviceTest.cpp
)

As before, feel free to take a look at one of the existing Modules and their Testing-Subfolder as the Kinect´s.

If you managed to implement your Module properly, an executable MODULENAMETestDriver will be generated.