.. _tutorial-client-api:

=====================
 Client API Tutorial
=====================

In addition to :ref:`bag-cat` and :ref:`bag-play`, |project| provides
a simple client API for working with :term:`log files <log
file>`. Analyzing, visualizing and transforming recorded data are the
primary use-cases for this API.

Preparation
===========

.. seealso::

   :ref:`preparation`
     Installing |project|

This section assumes a working installation of |project| including at
least one of the client APIs.

.. container:: listing-multi

   .. container:: listing-python

      The |project| client API for Python is provided by the
      :py:mod:`rsbag` module. To use the module

      .. code-block:: python

         import rsbag

      All subsequent listings assume this.

   .. container:: listing-cpp

      *Not implemented yet*

   .. container:: listing-java

      *Not implemented yet*

   .. container:: listing-common-lisp

      .. code-block:: common-lisp

         (ql:quickload '(:cl-rsbag :rsbag-tidelog))

.. note::

   The client API presented here only takes care of making available
   the contents of :term:`log files <log file>`, not the
   interpretation of this data. Depending on the kind of data, it may
   be necessary to load and/or register :ref:`RSB <rsb>`
   :term:`converters <converter>` to access the data in a convenient
   form. See :ref:`tutorial-converters` for details.

Opening A Log file
==================

Processing data in :term:`log files <log file>` starts with opening
the respective :term:`log file`.

.. container:: listing-multi

   .. container:: listing-python

      :term:`Log files <log file>` are opened using the
      :py:func:`rsbag.openBag` function. This function returns a
      :py:class:`Bag` object implementing the
      :ref:`context manager protocol <python:with>`:

      .. code-block:: python
         :linenos:

         with rsbag.openBag('/media/local_data/foo.tide',
                            rsbag = '/vol/mydistribution/bin/rsbagcl0.16',
                            channels = [ 'vision' ]) as bag:
             pass

      .. note::

         The name and path of the :program:`rsbag` program may have to
         be adapted.

   .. container:: listing-cpp

      *Not implemented yet*

   .. container:: listing-java

      *Not implemented yet*

   .. container:: listing-common-lisp

      .. code-block:: common-lisp

         (rsbag:with-bag (bag "/media/local_data/foo.tide" :direction :input)
            (rsbag:bag-channel bag "vision"))

Accessing Events
================

.. container:: listing-multi

   .. container:: listing-python

      :term:`Events <event>` are accessed using the
      :py:attr:`rsbag.Bag.events` and :py:attr:`rsbag.Bag.items`
      properties. Both behave like ordinary :ref:`Python sequences
      <python:sequence>`:

      .. code-block:: python
         :linenos:

         with rsbag.openBag('/media/local_data/foo.tide',
                            channels = [ 'vision' ]) as bag:
             print len(bag.events)
             for e in bag.events:
                 print (e.scope, e.metaData.createTime, e.data.width, e.data.height)

   .. container:: listing-cpp

      *Not implemented yet*

   .. container:: listing-java

      *Not implemented yet*

   .. container:: listing-common-lisp

      .. code-block:: common-lisp

         (rsbag:with-bag (bag "/media/local_data/foo.tide" :direction :input)
            (values
              (length (rsbag:bag-channel bag "vision"))
              (subseq (rsbag:bag-channel bag "vision") 5 10)))