Armature Actuator
=================


**An actuator to manipulate Blender armatures in MORSE.**


**Armatures** are the MORSE generic way to simulate kinematic chains
made of a combination of revolute joints (hinge) and prismatic
joints (slider).

This component only allows to *set* an armature configuration. To read the
armature pose, you need an :doc:`armature pose sensor <../sensors/armature_pose>`.

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


This actuator offers two main ways to control a kinematic chain: either by
setting the values of each joint individually (via a continuous datastream
or via dedicated services: :py:meth:`translate`,
:py:meth:`set_translation`, :py:meth:`rotate`, :py:meth:`set_rotation`) or
by placing the end-effector and relying on a inverse kinematic solver (via
the services :py:meth:`set_IK_target` and :py:meth:`move_IK_target`).

.. note::

    When setting the joints with a datastream, the data structure that the
    armature actuator expects depends on the armature itself.  It is a
    dictionary of pair `(joint name, joint value)`.  Joint values are
    either radians (for revolute joints) or meters (for prismatic joints)

To use inverse kinematics, you must first define *IK targets* to control
your kinematic chain. You can create them :doc:`manually from Blender
<../../dev/armature_creation>` or directly in your `Builder script` (refer
to the `Examples` section below for an example).

.. note::

    :tag:`ros` Armatures can be controlled in ROS through the
    `JointTrajectoryAction
    <http://wiki.ros.org/joint_trajectory_action>`_
    interface.


**See also:** :doc:`armature pose sensor <../sensors/armature_pose>`




.. cssclass:: properties morse-section

Configuration parameters for armature actuator
----------------------------------------------


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

- ``DistanceTolerance`` (float, default: ``0.005``)
	Tolerance in meters when translating a joint
- ``AngleTolerance`` (float, default: ``0.01``)
	Tolerance in radians when rotating a joint
- ``RotationSpeed`` (float, default: ``0.8``)
	Global rotation speed for the armature rotational joints (in rad/s)
- ``LinearSpeed`` (float, default: ``0.05``)
	Global linear speed for the armature prismatic joints (in m/s)
- ``IKRotationSpeed`` (float, default: ``0.5``)
	Default speed of IK target rotation (in rad/s)
- ``IKLinearSpeed`` (float, default: ``0.5``)
	Default speed of IK target motion (in m/s)


.. cssclass:: fields morse-section

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

No data field documented (see above for possible notes).

.. cssclass:: services morse-section

Services for Armature Actuator
------------------------------

- ``translate(joint, translation, speed)`` (non blocking)
    Translates a joint at a given speed (in m/s).
    
    
  - Parameters

    - ``joint``: name of the armature's joint to translate
    - ``translation``: the absolute translation, relative to the joint origin, in meters
    - ``speed``: (default: value of 'linear_speed' property) translation speed, in m/s

- ``set_translations(translations)`` (blocking)
    Sets in one call the translations of the prismatic joints in this
    armature.
    
    Has the same effect as applying `set_translation` on each of the joints
    independantly.
    
    Translations must be ordered from the root to the tip of the armature.
    
    If more translations are provided than the number of joints, the
    remaining ones are discarded. If less translations are provided, the
    maximum are applied.
    
    .. important::
    
        If a revolute joint is encountered while applying the translations,
        an exception is thrown, and **no** translation is applied.
    
    
    **See also:** `set_translation`
    
  - Parameters

    - ``translations``: a set of absolute translations, in meters

- ``move_IK_target(name, translation, rotation, relative, linear_speed, radial_speed)`` (non blocking)
    Moves an IK (inverse kinematic) target at a given speed (in m/s for
    translation, rad/s for rotation).
    
    Note that moving an IK target conflicts somewhat with the original
    purpose of the inverse kinematic solver, and overall continuity is not
    guaranteed (the IK solver may find a solution for a given target
    position that 'jumps' relative to the solution for the previous target
    position).
    
    
    **See also:** `place_IK_target` to set instantaneously the IK target pose.
    
    
  - Parameters

    - ``name``: name of the IK target (as returned by :py:meth:`list_IK_targets`)
    - ``translation``: a [x,y,z] translation vector, in the scene frame,  in meters.
    - ``rotation``: a [rx,ry,rz] rotation, in the scene frame (ie, X,Y,Z  rotation axis are the scene axis). Angles in radians.
    - ``relative``: if True (default), translation and rotation are  relative to the current target pose.
    - ``linear_speed``: (default: value of the `ik_target_linear_speed`  property) translation speed (in m/s).
    - ``radial_speed``: (default: value of the `ik_target_radial_speed`  property) rotation speed (in rad/s).

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

    a dictionary of the current component's configurations  

- ``set_rotation(joint, rotation)`` (blocking)
    Rotates instantaneously the given (revolute) joint by the given
    rotation. Joint speed limit is not taken into account.
    
    If the joint does not exist or is not a revolute joint (hinge),
    throws a MorseServiceFailed exception.
    
    The rotation is always clamped to the joint limit.
    
    
  - Parameters

    - ``joint``: name of the joint to rotate
    - ``rotation``: absolute rotation from the joint origin along the joint rotation axis, in radians

- ``place_IK_target(name, translation, rotation, relative)`` (blocking)
    Places instantaneously a IK (inverse kinematic) target to a given
    position and orientation.
    
    
    **See also:** `move_IK_target` to move the IK target over time.
    
    
  - Parameters

    - ``name``: name of the IK target (as returned by :py:meth:`list_IK_targets`)
    - ``translation``: a [x,y,z] translation vector, in the scene frame, in meters.
    - ``rotation``: a [rx,ry,rz] rotation, in the scene frame (ie, X,Y,Z  rotation axis are the scene axis). Angles in radians.
    - ``relative``: if True (default), translation and rotation are  relative to the current target pose.

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

    a dictionary of the current component's properties  

- ``get_IK_limits()`` (blocking)
    Returns the IK limits for the given joint.
    
    - For revolute joints, returns a pair `(ik_min,ik_max)`, in radians.
    - For prismatic joint, returns a pair `(0.0, max translation)`, in meters.
    
- ``rotate(joint, rotation, speed)`` (non blocking)
    Rotates a joint at a given speed (in rad/s).
    
    
    **See also:** `Blender documentation on joint rotation <http://www.blender.org/documentation/blender_python_api_2_64_release/bge.types.html#bge.types.BL_ArmatureChannel.joint_rotation>`_
    
    
  - Parameters

    - ``joint``: name of the armature's joint to rotate
    - ``rotation``: rotation around the joint axis in radians
    - ``speed``: (default: value of 'radial_speed' property) rotation speed, in rad/s

- ``set_translation(joint, translation)`` (blocking)
    Translates instantaneously the given (prismatic) joint by the given
    translation. Joint speed limit is not taken into account.
    
    
    **See also:** `Blender documentation on joint location <http://www.blender.org/documentation/blender_python_api_2_64_release/bge.types.html#bge.types.BL_ArmatureChannel.location>`_
    
    If the joint does not exist or is not a prismatic joint (slider),
    throws a MorseServiceFailed exception.
    
    The translation is always clamped to the joint limit.
    
    
  - Parameters

    - ``joint``: name of the joint to move
    - ``translation``: absolute translation from the joint origin in the joint sliding axis, in meters

- ``trajectory(trajectory)`` (non blocking)
    Executes a joint trajectory to the armature.
    
    The `trajectory` parameter should have the following structure:
    
    .. code-block:: python
    
        trajectory = {
            'starttime': <timestamp in second>,
            'points': [
                {'positions': [...],
                 'velocities': [...],
                 'accelerations' [...],
                 'time_from_start': <seconds>}
                {...},
                ...
                ]
            }
    
    .. warning::
        
        Currently, both `velocities` and `accelerations` are ignored.
    
    The trajectory execution starts after `starttime` timestamp passed
    (if omitted, the trajectory execution starts right away).
    
    `points` is the list of trajectory waypoints. It is assumed that the
    values in the waypoints are ordered the same way as in the set of
    joint of the armature (ie, from the root to the tip of the armature).
    `velocities` and `accelerations` are optional.
    
    The component attempts to achieve each waypoint at the time obtained
    by adding that waypoint's `time_from_start` value to `starttime`.
    
    
  - Parameters

    - ``trajectory``: the trajectory to execute, as describe above.

- ``list_IK_targets()`` (blocking)
    (no documentation yet)
- ``set_rotations(rotations)`` (blocking)
    Sets in one call the rotations of the revolute joints in this armature.
    
    Has the same effect as applying `set_rotation` on each of the joints
    independantly.
    
    Rotations must be ordered from the root to the tip of the armature.
    
    If more rotations are provided than the number of joints, the remaining
    ones are discarded. If less rotations are provided, the maximum are
    applied.
    
    .. important::
    
        If a prismatic joint is encountered while applying the rotation,
        an exception is thrown, and **no** rotation is applied.
    
    
    **See also:** `set_rotation`
    
  - Parameters

    - ``rotations``: a set of absolute rotations, in radians

- ``get_dofs()`` (blocking)
    Returns a dictionary with keys the channels
    of the armature and as values the rotation axis of the joint.
    


.. 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()

    # imports an armature,
    # either from a Blender file...
    armature = Armature(model_name = "<blend file>")
    # ...or by providing the name of an existing armature:
    # armature = Armature(armature_name = "<name of armature>")
    # (note that you can combine both options to select an armature in a 
    # Blender file)

    # if you want to use inverse kinematics, you can create 'IK targets'
    # here as well:
    armature.create_ik_targets(["<name of the bone you want to control>", ...])

    # place your armature at the correct location
    armature.translate(<x>, <y>, <z>)
    armature.rotate(<rx>, <ry>, <rz>)

    # define one or several communication interfaces, like 'socket' or 'ros'
    # With ROS, this actuator exposes a JointTrajectoryAction interface.
    armature.add_interface(<interface>)

    robot.append(armature)

    env = Environment('empty')
    

.. cssclass:: files morse-section

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

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




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