Gripper
=======


**Instruct the robot to move towards a given target**


Actuator capable of grabbing objects marked with the ``Graspable``
Game Property.  Currently it only works using services: **grab** and
**release**.  When instructed to grab an object, it will check if it
is within range, and if so, will parent the grabbed object to
itself.

.. note::

    For objects to be detected and grabbed by the gripper, they must
    have the following settings in the **Physics Properties** panel:

        - **Actor** must be checked
        - **Collision Bounds** must be checked
        - **Physics Type** must be ``Rigid Body``

    This will work even for Static objects

.. warning::

    This actuator does not simulate the physical interaction of the
    gripper fingers with the objects it grabs. Its purpose is to
    abstract the action of taking an object, for human-robot
    interaction experiments.


.. cssclass:: properties morse-section

Configuration parameters for Gripper
------------------------------------


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

- ``Angle`` (float, default: ``60.0``)
	Aperture angle of the radar capable to detecting the                   graspable objects (in degree)
- ``Distance`` (float, default: ``0.5``)
	Detection distance in meter. Graspable objects further                  way from the gripper than this distance cannot be                   held


.. cssclass:: fields morse-section

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


This actuator reads these datafields at each simulation step:

- ``grab`` (bool, initial value: ``False``)
	Currently not used

*Interface support:*

- :tag:`yarp`  as yarp::Bottle (:py:mod:`morse.middleware.yarp_datastream.YarpReader`)
- :tag:`socket`  as straight JSON deserialization (:py:mod:`morse.middleware.socket_datastream.SocketReader`)


.. cssclass:: services morse-section

Services for Gripper
--------------------

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

    a dictionary of the current component's properties  

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

- ``grab()`` (blocking)
    Tries to grab an object close to the gripper.
    
    
  - Return value

    if successful (or if an object is already in hand), the           name of the object, else None. 

- ``release()`` (blocking)
    Free the grabbed object.
    
    Let it fall down after resetting its rotation.
    Does nothing if no object is held.
    
    
  - Return value

    True if an object has been released, else False (if           no object was held). 

- ``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 actuator
    gripper = Gripper()

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

    env = Environment('empty')
    

.. cssclass:: files morse-section

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

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




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