============
 Converters
============

.. sectionauthor:: Johannes Wienke <jwienke@techfak.uni-bielfeld.de>

Besides the |project| types, a collection of :ref:`RSB <rsb>`
:term:`converter` s from :term:`data type` s found in several common
libraries like e.g. OpenCV to and from |project| types is maintained.
These :term:`converter` s can be used inside interested client
projects.

.. note::

   Currently, only C++ :term:`converter` s are available. Hence, the
   following description only focus on C++.

Installation
------------

#. Clone the ``rst-converters`` repository from |repository|.converters.
#. Install the project using the provided CMake file.
#. TODO provide more details here

The result will be a shared library containing the :term:`converter` s
which can be used by client projects.

Usage in CMake-based Projects
-----------------------------

In order to use the provided :term:`converter` s in projects based on
CMake, first find the ``rst-converters`` library using the following
code:

.. code-block:: cmake

   FIND_PACKAGE(rst-converters REQUIRED)
   INCLUDE_DIRECTORIES(BEFORE SYSTEM ${RST_CONVERTERS_INCLUDE_DIRS})

Afterwards you can create a usual target in CMake and finally link it against
the ``rst-converters`` library:

.. code-block:: cmake

   ADD_EXECUTABLE(tester tester.cpp)
   TARGET_LINK_LIBRARIES(tester ${RST_CONVERTERS_LIBRARIES})

In order to use the available :term:`converter` s in the client C++
code, the following example shall provide a first rough idea:

.. code-block:: cpp

   #include <rst/converters/opencv/IplImageConverter.h>

   int main() {
       rsb::converter::Converter<std::string>::Ptr imageConverter(
                new rst::converters::opencv::IplImageConverter());
       rsb::converter::stringConverterRepository()->registerConverter(imageConverter);
       // the converter can now be used in RSB
   }