.. highlight:: rst

.. _scgof:

#####
scgof
#####

**Geographic origin filter.**


Description
===========

*scgof* is released under the GNU Affero General Public License (Free
Software Foundation, version 3 or later). It filters origins based on 
their epicenter locations, and keeps only those within a region defined
in :ref:`BNA files <sec-gui_layers>`, and configured in a filter 
profile with a matching creation author. The origin filtering procedure is 
as follows:

#. Listen to origins received from groups defined in `connection.subscriptions`.
#. For each origin, check if the author and location match any of the filters configured with `author`, and a `region`.
#. If the origin checks the previous, transfer the origin to the messaging group defined in `connection.primaryGroup`. 

.. note::

 Inappropriate origins are still recorded in the database, they are only 
 discarded for event association.

It requires to setup modules creating the origins to be filtered, with 
a dedicated messaging group, e.g.:

.. code-block:: sh

 connection.primaryGroup = LOCATION_A 

Following the same example, you might add the group "LOCATION_A" to the 
default message groups defined by :ref:`scmaster` in :file:`scmaster.cfg`:

.. code-block:: sh

 msgGroups = LOCATION_A, ...

and let *scgof* listen to the messages to the "LOCATION_A" group. 
Adjust :file:`scgof.cfg`:

.. code-block:: sh

 connection.subscriptions = LOCATION_A



Configuration
=============

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/scgof.cfg`
| :file:`etc/global.cfg`
| :file:`etc/scgof.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/scgof.cfg`

scgof inherits `global options <https://docs.gempa.de/seiscomp/current/apps/global.html>`_.



.. confval:: bnaFile

   Type: *list:string*

   The BNA file defining regions \(closed polygons\) for each filter. BNA file
   might be defined and extended interactively in the map of `scolv` or `scmv`.
   Default is ``@DATADIR@/bna/custom.bna``.

.. confval:: profiles

   Type: *list:string*

   The list of origin filters.
   Default is ``none``.

.. note::
   **profile.\***
   *Parameters of each geographic origin filter.*



.. note::

   **profile.$name.\***
   $name is a placeholder for the name to be used and needs to be added to :confval:`profiles` to become active.

   .. code-block:: sh

      profiles = a,b
      profile.a.value1 = ...
      profile.b.value1 = ...
      # c is not active because it has not been added
      # to the list of profiles
      profile.c.value1 = ...


.. confval:: profile.$name.author

   Type: *string*

   Origin creation author to allow origins for. Only the author name is
   considered \(not the hostname\).
   Default is ``none``.

.. confval:: profile.$name.region

   Type: *string*

   Region \(closed polygon\) where to allow origins. All regions should be
   defined in \"bnaFile\".
   Default is ``none``.
