.. vim: set fileencoding=utf-8 :

============
 User Guide
============

Score-level fusion is done (as the name suggests) using the scores generated by
a biometric recognition or presentation attack detection (PAD) system. The idea
of fusion is to integrate several systems into one macro system that produces
one decision for a given biometric sample. For example, a face biometric system
and a voice biometric system can be integrated together using score-level
fusion to improve the performance of biometric recognition. Another example is
to integrate one or several biometric recognition systems with one or several
pad systems to improve both the recognition rate and the attack resilience.
Fusion can be done between different biometric systems and/or pad systems. You
can mix any number of biometric systems and pad systems in this package to do
score-level fusion. The scores must comply the format of
:ref:`bob.bio.base <bob.bio.base>` and :ref:`bob.pad.base <bob.pad.base>`
packages.


The actual fusion can be done in different ways. For example, the simplest
approach to score-level fusion is to sum the scores of all systems. The way to
do the fusion in this package is by implementing an algorithm class that
inherits from :any:`bob.fusion.base.algorithm.Algorithm`:

* An algorithm also takes a list of preprocessors
  (:any:`bob.fusion.base.algorithm.Algorithm.preprocessors`) that are applied
  to data before fusion.
* A simple preprocessor can normalize data to be 0 mean and 1 std.
* Preprocessors can also be trainable and they will be trained in
  :any:`bob.fusion.base.algorithm.Algorithm.train_preprocessors`.
* After training the preprocessors and applying them on the data, the
  normalized data (data is score values) is used to train the fusion algorithm
  in :any:`bob.fusion.base.algorithm.Algorithm.train`.
* After that, :any:`bob.fusion.base.algorithm.Algorithm.fuse` is called on
  normalized scores to get the final decision score.

You can look into the source code of the
:any:`bob.fusion.base.script.routine_fusion` to see the actual steps that will
be run to do score-level fusion in this package.

All the computations are done using the following script:

.. code-block:: sh

    $ bob fusion fuse --help

What you need is some training data (or a model_file that contains an already
trained algorithm) if your algorithm requires training and some scores to test
your algorithm on. See the :ref:`bob.fusion.base.api` or run ``bob fusion
resource`` for a list of already available algorithms.

Here is a minimal example to do MEAN fusion
(:any:`bob.fusion.base.algorithm.Weighted_Sum`) on a face recognition system
and a face PAD system.

.. code-block:: sh

    $ bob fusion fuse -a mean face_bio/scores-{world,dev,eval} face_pad/scores-{train,dev,eval}


Finally, you can visualize the decision boundary of your fusion algorithm using
``bob fusion boundary``.


.. include:: links.rst