.. _situation_recognition:

Situation Recognition
=====================

The situation recognition uses information from various sensors to provide
an abstracted *mental model* of the current state of the apartment and its
content.

Related resources
-----------------


Component repository:
 - Browse component repository: `sitinf <https://bitbucket.org/vrichter/sitinf>`_.
 - ``git clone https://bitbucket.org/vrichter/sitinf``

System startup:
 - The situation recognition can be found in ``lsp-csra-base.sh`` on the ``situation`` tab.
 - The component script is called ``situation``.

Related projects:
 - Browse repository `system-startup <https://projects.cit-ec.uni-bielefeld.de/projects/lsp-csra/repository/system-startup>`_.

Interfaces
-----------------

.. _Screen: http://docs.cor-lab.de//rst-manual/trunk/html/generated/sandbox/package-rst-homeautomation.html#rst.homeautomation.unit.Screen
.. _ClassificationResultMap:  http://docs.cor-lab.de//rst-manual/trunk/html/generated/sandbox/package-rst-classification.html#rst.classification.ClassificationResultMap
.. _BayesNetwork:  http://docs.cor-lab.de//rst-manual/trunk/html/generated/sandbox/package-rst-bayesnetwork.html#rst.bayesnetwork.BayesNetwork
.. _BayesNetworkEvidence:  http://docs.cor-lab.de//rst-manual/trunk/html/generated/sandbox/package-rst-bayesnetwork.html#rst.bayesnetwork.BayesNetworkEvidence

The informers are used to publish the updates in evidence, situation recognition result as and the used bayes network.

The api is available for two separate networks.

- *situation* is a general purpose network for situation recognition in the csra. ``prefix=/citec/csra/home/situation``
- *addressee* recognizes whether flobi was addressed in the kitchen or entrance. ``prefix=/citec/csra/home/addressee``


=============================================== ============================
Scope (Informer)                                Type
=============================================== ============================
 ``$prefix/result``                             `ClassificationResultMap`_
 ``$prefix/evidence``                           `BayesNetworkEvidence`_
 ``$prefix/network``                            `BayesNetwork`_
=============================================== ============================

With the listeners the evidence can be set for testing or learning purposes and the network used for recognition can be set.

========================================================== ============================
Scope (Listener)                                           Type
========================================================== ============================
 ``$prefix/override/evidence/override``                    `ClassificationResultMap`_
 ``$prefix/override/evidence/learn``                       `ClassificationResultMap`_
 ``$prefix/override/network/``                             `BayesNetwork`_
========================================================== ============================

The local servers can be used to *pull* the current bayesian network and situation.

============================================= ============================
Scope (Local Server) + Method                 Return Type
============================================= ============================
 ``$prefix/result/get()``                     `ClassificationResultMap`_
 ``$prefix/network/get()``                    `BayesNetwork`_
============================================= ============================

Situation Network
------------------

The following graph is used in the situation recognition:

.. image:: images/situation-graph.svg

The following graph is used in the addressee recognition:

.. image:: images/addressee-graph.svg


Examples
--------------

Find out if Flobi has the attention of someone in the kitchen and print the information:

.. code-block:: java
   :emphasize-lines: 3,4

    ClassificationResultMapType.ClassificationResultMap situation = (ClassificationResultMapType.ClassificationResultMap) event.getData();
        if(situation.getAspectsList().stream()
              .filter(aspect -> aspect.getName().equals("Attention_Flobi_Kitchen"))
              .filter(aspect -> aspect.getResult().getDecidedClass().equals("Some"))
              .findAny().isPresent())
        {
            System.out.println("Flobi has attention.");
        } else {
            System.out.println("Flobi does not have attention.");
        }