Proximity Sensor
================


**Distance sensor to detect nearby objects.**


This sensor can be used to determine which other objects are within a
certain radius of the sensor. It performs its test based only on distance.
The type of tracked objects can be specified using the **Track** property.


.. cssclass:: properties morse-section

Configuration parameters for proximity sensor
---------------------------------------------


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

- ``Range`` (float, default: ``100``)
	The distance, in meters beyond which this sensor is unable to locate other robots.
- ``Track`` (string, default: ``"Robot_Tag"``)
	The type of tracked objects. This type is looked for as game property of scene objects. You must then add a new game property to the objects you want to be detected by the proximity sensor.


.. cssclass:: fields morse-section

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


This sensor exports these datafields at each simulation step:

- ``timestamp`` (float, initial value: ``0.0``)
	number of milliseconds in simulated time
- ``near_objects`` (dict, initial value: ``{}``)
	A list of the tracked objects located within the given radius. The keys of the dictionary are the object names, and the values are the distances (in meters) from the sensor.
- ``near_robots`` (dict, initial value: ``{}``)
	deprecated. Points to near_objects for compatibility reasons.

*Interface support:*

- :tag:`text`  as key = value format with timestamp and index value (:py:mod:`morse.middleware.text_datastream.Publisher`)
- :tag:`ros`  as StringPublisher (:py:mod:`morse.middleware.ros.StringPublisher`)
- :tag:`yarp_json`  as json encoded data in yarp::bottle (:py:mod:`morse.middleware.yarp.yarp_json.YarpJsonPublisher`)
- :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`)


.. cssclass:: services morse-section

Services for Proximity Sensor
-----------------------------

- ``set_range(range)`` (blocking)
    The service expects a float range (in meter), and modify the range
    used to detect objects around the proximity sensor.
    
    
  - Parameters

    - ``range``: detection range, in meters

- ``set_tracked_tag(tag)`` (blocking)
    The service allows to modify the kind of objects detected by the
    proximity sensor.
    
    
  - Parameters

    - ``tag``: value of the *Track* property used to select detected             objects.

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

    a dictionary of the current component's properties  

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

    a dictionary of the current component's configurations  

- ``get_local_data()`` (blocking)
    Returns the current data stored in the sensor.
    
    
  - Return value

    a dictionary of the current sensor's data 



.. 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 sensor
    proximity = Proximity()

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

    env = Environment('empty')
    

.. cssclass:: files morse-section

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

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




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