Stereo Camera Unit
==================


The purpose of this component is to link together one or more
cameras, and provide them with the possibility to move together as a
single unit. It will also provide the connection interface to use
the information of the cameras attached to it. In the case of two
cameras, it will provide the stereo information generated from the
two camera images.

Related components
------------------

A stereo unit needs to be the parent of one or more :doc:`cameras
<../sensors/video_camera>`. Otherwise, it does no useful function.

The movement of the stereo unit is implemented by making it the child of a
:doc:`Pan-Tilt unit <../actuators/ptu>` actuator.

Here is an example of how to construct the whole stereo system to mount on top
of a robot, using the Builder API. Note the order in which components are
appended to each other, as this is important to get the desired functionality:

.. code-block:: python

    from morse.builder import *

    # Add a robot
    atrv = ATRV()
    atrv.translate(z=0.1000)
    
    # A pan-tilt unit to be able to orient the cameras
    Platine = PTU()
    Platine.translate(x=0.2000, z=0.9000)
    atrv.append(Platine)
    
    # The STEREO UNIT, where the two cameras will be fixed
    Stereo = StereoUnit()
    Stereo.translate(z=0.0400)
    Platine.append(Stereo)
    
    # Left camera
    CameraL = VideoCamera()
    CameraL.translate(x=0.1000, y=0.2000, z=0.0700)
    Stereo.append(CameraL)
    CameraL.properties(capturing = True)
    CameraL.properties(cam_width = 320)
    CameraL.properties(cam_height = 240)
    CameraL.properties(cam_focal = 25.0000)
    
    # Right camera
    CameraR = VideoCamera()
    CameraR.translate(x=0.1000, y=-0.2000, z=0.0700)
    Stereo.append(CameraR)
    CameraR.properties(capturing = True)
    CameraR.properties(cam_width = 320)
    CameraR.properties(cam_height = 240)
    CameraR.properties(cam_focal = 25.0000)



.. cssclass:: properties morse-section

Configuration parameters for Stereo Camera Unit
-----------------------------------------------

*No configurable parameter.*

.. cssclass:: fields morse-section

Data fields
-----------


This sensor exports these datafields at each simulation step:

- ``timestamp`` (float, initial value: ``0.0``)
	number of seconds in simulated time

*Interface support:*

- :tag:`pocolibs`  as `ViamImageBank <http://trac.laas.fr/git/viam-genom/tree/viamStruct.h?h=viam-genom-1#n346>`_ (:py:mod:`morse.middleware.pocolibs.sensors.viam.ViamPoster`)


.. cssclass:: services morse-section

Services for Stereo Camera Unit
-------------------------------

- ``get_properties()`` (blocking)
    Returns the properties of a component.
    
    
  - Return value

    a dictionary of the current component's properties  

- ``get_local_data()`` (blocking)
    Returns the current data stored in the sensor.
    
    
  - Return value

    a dictionary of the current sensor's data 

- ``set_property(prop_name, prop_val)`` (blocking)
    Modify one property on a component
    
    
  - Parameters

    - ``prop_name``: the name of the property to modify (as shown the documentation)
    - ``prop_val``: the new value of the property. Note that there is no checking about the type of the value so be careful

  - Return value

    nothing 

- ``capture(n)`` (non blocking)
    The service takes an integer an argument and dispatch the call
    to all its individual cameras. The service ends when each camera
    has terminated its work.
    
    
  - Parameters

    - ``n``: the number of call to each individual camera

- ``get_configurations()`` (blocking)
    Returns the configurations of a component (parsed from the properties).
    
    
  - Return value

    a dictionary of the current component's configurations  



.. cssclass:: examples morse-section

Examples
--------


The following examples show how to use this component in a *Builder* script:

.. code-block:: python


    from morse.builder import *
    
    # adds a default robot (the MORSE mascott!)
    robot = Morsy()
    
    # creates a new instance of the sensor
    stereounit = StereoUnit()

    # place your component at the correct location
    stereounit.translate(<x>, <y>, <z>)
    stereounit.rotate(<rx>, <ry>, <rz>)
    
    robot.append(stereounit)
    
    # define one or several communication interface, like 'socket'
    stereounit.add_interface(<interface>)

    env = Environment('empty')
    

.. cssclass:: files morse-section

Other sources of examples
+++++++++++++++++++++++++

- `Source code <../../_modules/morse/sensors/stereo_unit.html>`_
- `Unit-test <../../_modules/base/stereo_unit_testing.html>`_




*(This page has been auto-generated from MORSE module morse.sensors.stereo_unit.)*