Pan-Tilt Unit
=============


**A generic actuator to control pan-tilt supports**


This actuator reads the rotation values for pan and tilt, and applies
them to the pan-tilt unit that must be set as children of this actuator.
Angles are expected in radians.

Unlike most other actuators, the Pan-Tilt unit is composed not only of an
Empty object, but it also includes two meshes. These are the **PanBase** and
the **TiltBase** that must also be imported when using this actuator.
These meshes will rotate to produce the effect of a real Pan-Tilt unit.

.. note:: When mounting a camera or stereo unit on top of the Pan-Tilt unit,
  make sure to parent the camera to the **PTU** object.

This component can be configured to be operated manually as well as through data
from a middleware. When using manual mode, the pan and tilt segments can be rotated
using the following keys:

-  :kbd:`Page Up` tilt up
-  :kbd:`Page Down` tilt down
-  :kbd:`Home` pan left
-  :kbd:`Insert` pan right


Code samples
------------

- `Scenario with a PTU from the component unit-test
  <../../_modules/base/ptu_testing.html#PTUTest.setUpEnv>`_ :tag:`builder`
- `Datastream usage, from the component unit-test
  <../../_modules/base/ptu_testing.html#PTUTest.test_datastream>`_ :tag:`pymorse` :tag:`datastream`
- `Service usage, from the component unit-test
  <../../_modules/base/ptu_testing.html#PTUTest.test_set_service>`_ :tag:`pymorse` :tag:`service`


.. cssclass:: properties morse-section

Configuration parameters for pan-tilt unit
------------------------------------------


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

- ``Speed`` (float, default: ``1.0``)
	Rotation speed, in rad/s
- ``Tolerance`` (float, default: ``0.005235987755982988``)
	(no documentation available yet)
- ``Manual`` (boolean, default: ``False``)
	If true, the PTU can only move via the keyboard.


.. cssclass:: fields morse-section

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


This actuator reads these datafields at each simulation step:

- ``pan`` (float, initial value: ``0.0``)
	Pan value, in radians
- ``tilt`` (float, initial value: ``0.0``)
	Tilt value, in radians

*Interface support:*

- :tag:`ros`  as Vector3Reader (:py:mod:`morse.middleware.ros.platine.Vector3Reader`)
- :tag:`pocolibs`  as `POM_SE_POSTER <http://trac.laas.fr/git/pom-genom/tree/pomStruct.h#n167>`_ (:py:mod:`morse.middleware.pocolibs.actuators.platine.PlatinePoster`) or as `PLATINE_AXIS_STR <http://trac.laas.fr/git/platine-genom/tree/platineStruct.h#n16>`_ (:py:mod:`morse.middleware.pocolibs.actuators.platine.PlatineAxisPoster`)
- :tag:`socket`  as straight JSON deserialization (:py:mod:`morse.middleware.socket_datastream.SocketReader`)
- :tag:`yarp`  as yarp::Bottle (:py:mod:`morse.middleware.yarp_datastream.YarpReader`)


.. cssclass:: services morse-section

Services for Pan-Tilt Unit
--------------------------

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

    a dictionary of the current component's properties  

- ``set_pan_tilt(pan, tilt)`` (non blocking)
    Move the platine to a given target position, represented by an
    angle couple.
    
    
  - Parameters

    - ``pan``: Target pan angle, in radian
    - ``tilt``: Target tilt angle, in radian

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

    a dictionary of the current component's configurations  

- ``look_at_point(x, y, z)`` (non blocking)
    Move the platine to look towards a given point. The point is
    expected to be given in the world reference
    
    
  - Parameters

    - ``x``: x coordinate of the target point (in meter)
    - ``y``: y coordinate of the target point (in meter)
    - ``z``: z coordinate of the target point (in meter)

- ``look_at_object(obj_name)`` (non blocking)
    Move the platine to look in the direction of the given object.
    
    
  - Parameters

    - ``obj_name``: the (Blender) name of an object present in the scene

- ``get_pan_tilt()`` (blocking)
    Returns the current angles for the pan and tilt segments.
    
    
  - Return value

    a couple of float, representing respectively the pan          and the tilt of the platine, in radian. 



.. 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 *
    
    robot = ATRV()
    
    # creates a new instance of the actuator
    ptu = PTU()

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

    env = Environment('empty')
    

.. cssclass:: files morse-section

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

- `Source code <../../_modules/morse/actuators/ptu.html>`_
- `Unit-test <../../_modules/base/ptu_testing.html>`_




*(This page has been auto-generated from MORSE module morse.actuators.ptu.)*
