Search And Rescue sensor
========================


**High level sensor for search and rescue scenario**


This is a multi functional component specific for Search and Rescue
scenario, where the robot must be able to aid human victims. The
sensor is capable of detecting any victim located within a cone in
front of the robot, with a range delimited in the properties of the
Blender object. The output of the sensor is a list of the robots and
their positions in the simulated world. This sensor works only with
the human victim object.

Additionally, the sensor provides a number of services related to
the capabilities of the robot to help the nearest victim:

    - Report on the condition of a victim
    - Report the capabilities of the robot
    - Heal a victim (if the robot has compatible capabilities with
      the requirements of the victim)

In the test scenarios, human victims are shown in red.  When a robot
approaches, if it has the adequate capabilities, it will be able to
help the victims. When issued the command, the sensor will gradually
change the colour of the victim to green, and its status to healthy.
It will detect if a victim is in front of the robot. When instructed
to heal the victim, it will change the Game Properties of the object
to reduce its injured value.


.. cssclass:: properties morse-section

Configuration parameters for search and rescue sensor
-----------------------------------------------------


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

- ``Heal_range`` (float, default: ``5.0``)
	maximum distance from which it is possible to heal a victim. Even if the victim can be detected by the sensor, it can’t be healed unless its distance from the robot is less than this value.
- ``Abilities`` (string, default: ``""``)
	represents a list of numbers, separated by comas, that represent the equipment capabilities of the robot. This information should be used by the operator of the robot to determine if it is capable of helping a victim or not.
- ``Angle`` (float, default: ``60.0``)
	Aperture angle of the radar capable of detecting the  victims (in degree)
- ``Distance`` (float, default: ``10.0``)
	Detection distance in meter. Victims further way from the gripper than this distance will not be detected
- ``Freq`` (float, default: ``3.0``)
	change the delay required to heal a victim. This number is expressed as the number of tics that are ignored before taking action. A lower number will produce a lower delay


.. 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
- ``victim_dict`` (dict, initial value: ``{}``)
	A list of entries for each victim detected inside the cone of the sensor. Keys are victim name. The value is a dictionnary containing the coordinate of the victim, its requirements, and the severity of its injuries

*Interface support:*

- :tag:`text`  as key = value format with timestamp and index value (:py:mod:`morse.middleware.text_datastream.Publisher`)
- :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:`pocolibs`  as `GENPOS_TRAJ_POINTS <http://trac.laas.fr/git/genPos-genom/tree/genPosStruct.h#n144>`_ (:py:mod:`morse.middleware.pocolibs.sensors.target.TargetPoster`)
- :tag:`yarp`  as yarp::Bottle (:py:mod:`morse.middleware.yarp_datastream.YarpPublisher`)


.. cssclass:: services morse-section

Services for Search And Rescue sensor
-------------------------------------

- ``get_victim_requirements()`` (blocking)
    Returns the list describing the type of injuries sustained by the victim
    
- ``get_properties()`` (blocking)
    Returns the properties of a component.
    
    
  - Return value

    a dictionary of the current component's properties  

- ``get_robot_abilities()`` (blocking)
    Returns the list describing  the abilities with which the robot
    is equipped.
    It must match the requirements of the victim for the robot to be
    able to heal it.
    
- ``get_local_data()`` (blocking)
    Returns the current data stored in the sensor.
    
    
  - Return value

    a dictionary of the current sensor's data 

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

    a dictionary of the current component's configurations  

- ``get_victim_severity()`` (blocking)
    Returns the integer indicating the victim healing priority
    
- ``heal()`` (non blocking)
    Reduce the Severity value of the nearest victim.
    When the value reaches ‘0’, change the Injured status of the victim to False.
    The service terminates when the victim is fully healed.
    


.. 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
    searchandrescue = SearchAndRescue()

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

    env = Environment('empty')
    

.. cssclass:: files morse-section

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

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




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