Armature Pose Sensor
====================


**Returns the joint state of a MORSE armature**


The sensor streams the joint state (ie, the rotation or translation value
of each joint belonging to the armature) of its parent armature.

.. note::

    This sensor **must** be added as a child of the armature
    you want to sense. See the *Examples* section below for an example.

This component only allows to *read* armature configuration. To change the
armature pose, you need an :doc:`armature actuator <../actuators/armature>`.

.. important:: 

    To be valid, special care must be given when creating armatures. If you
    want to add new one, please carefully read the :doc:`armature creation
    <../../dev/armature_creation>` documentation.


.. note::

    The data structure on datastream exported by the armature sensor
    depends on the armature.  It is a dictionary of pair `(joint name,
    joint value)`.  Joint values are either radians (for revolute joints)
    or meters (for prismatic joints)



**See also:** :doc:`armature actuator <../actuators/armature>`



.. cssclass:: properties morse-section

Configuration parameters for Armature Pose Sensor
-------------------------------------------------

*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:`text`  as key = value format with timestamp and index value (:py:mod:`morse.middleware.text_datastream.Publisher`)
- :tag:`ros`  as `sensor_msgs/JointState <http://ros.org/doc/api/sensor_msgs/html/msg/JointState.html>`_ (:py:mod:`morse.middleware.ros.jointstate.JointStatePublisher`)
- :tag:`socket`  as straight JSON serialization (:py:mod:`morse.middleware.socket_datastream.SocketPublisher`)
- :tag:`yarp`  as yarp::Bottle (:py:mod:`morse.middleware.yarp_datastream.YarpPublisher`)
- :tag:`moos`  as StringPublisher (:py:mod:`morse.middleware.moos.abstract_moos.StringPublisher`)


.. cssclass:: services morse-section

Services for Armature Pose Sensor
---------------------------------

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

    a dictionary of the current component's configurations  

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

    a dictionary of the current component's properties  

- ``get_joints_length()`` (blocking)
    Returns a dict with the armature joints' names as key and
    and the corresponding bone length as value (in meters).
    
- ``get_joints()`` (blocking)
    Returns the list of joints of the armature.
    
    
  - Return value

    the (ordered) list of joints in the armature, from root to tip. 

- ``get_state()`` (blocking)
    Returns the joint state of the armature, ie a dictionnary with joint
    names as key and the corresponding rotation or translation as value
    (respectively in radian or meters).
    
    
- ``get_local_data()`` (blocking)
    Returns the current data stored in the sensor.
    
    
  - Return value

    a dictionary of the current sensor's data 

- ``get_joint(joint)`` (blocking)
    Returns the *value* of a given joint, either:
    - its absolute rotation in radian along its rotation axis, or
    - it absolute translation in meters along its translation axis.
    
    Throws an exception if the joint does not exist.
    
    
  - Parameters

    - ``joint``: the name of the joint in the armature.

- ``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 



.. cssclass:: examples morse-section

Examples
--------


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

.. code-block:: python

    robot = ATRV()

    arm = KukaLWR()
    robot.append(arm)
    arm.translate(z=0.9)

    arm_pose = ArmaturePose()
    # the sensor is appended to the armature, *not* to the robot
    arm.append(arm_pose)


.. cssclass:: files morse-section

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

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




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