Depth camera
============

.. image:: ../../../media/sensors/depth_camera.png
  :align: center
  :width: 600


**A camera capturing RGBA image**


This sensor generates a Depth 'image' from the camera perspective.

"Depth images are published as sensor_msgs/Image encoded as 32-bit float.
Each pixel is a depth (along the camera Z axis) in meters."
[ROS Enhancement Proposal 118](http://ros.org/reps/rep-0118.html) on Depth
Images.

If you are looking for PointCloud data, you can use external tools like
[depth_image_proc](http://ros.org/wiki/depth_image_proc) which will use the
``intrinsic_matrix`` and the ``image`` to generate it, or eventually the
``XYZCameraClass`` in this module.


.. cssclass:: properties morse-section

Configuration parameters for Depth camera
-----------------------------------------


You can set these properties in your scripts with ``<component>.properties(<property1>=..., <property2>=...)``.

- ``cam_width`` (default: ``256``)
	(no documentation available yet)
- ``cam_height`` (default: ``256``)
	(no documentation available yet)
- ``cam_focal`` (default: ``25.0``)
	(no documentation available yet)
- ``cam_near`` (default: ``1.0``)
	(no documentation available yet)
- ``cam_far`` (default: ``20.0``)
	(no documentation available yet)
- ``Vertical_Flip`` (default: ``True``)
	(no documentation available yet)
- ``retrieve_depth`` (default: ``True``)
	(no documentation available yet)
- ``retrieve_zbuffer`` (default: ``False``)
	(no documentation available yet)


.. 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
- ``image`` (buffer, initial value: ``none``)
	Z-Buffer captured by the camera, converted in meters. memoryview of float of size ``(cam_width * cam_height * sizeof(float))`` bytes.
- ``intrinsic_matrix`` (mat3<float>, initial value: ``none``)
	The intrinsic calibration matrix, stored as a 3x3 row major Matrix.

*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`)
- :tag:`ros`  as `sensor_msgs/Image <http://ros.org/doc/api/sensor_msgs/html/msg/Image.html>`_ (:py:mod:`morse.middleware.ros.video_camera.DepthCameraPublisher`)
- :tag:`socket`  as a JSON-Encoded message for the DepthCamera (:py:mod:`morse.middleware.sockets.depth_camera.DepthCameraPublisher`)
- :tag:`yarp`  as yarp::ImageFloat (:py:mod:`morse.middleware.yarp.video_depth_camera.YarpImageFloatPublisher`)


.. cssclass:: services morse-section

Services for Depth camera
-------------------------

- ``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)
    Capture **n** images
    
    
  - Parameters

    - ``n``: the number of images to take. A negative number means           take image indefinitely

- ``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
    depthvideocamera = DepthVideoCamera()

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

    env = Environment('empty')
    

.. cssclass:: files morse-section

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

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




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