/** @mainpage libKFace reference page.

# Introduction

Libkface is a Qt/C++ library to perform face detection and face recognition over pictures. Have a look at KFaceIface::FaceDetector to get started with face detection. Have a look at KFaceIface::RecognitionDatabase to get started with face recognition. This Library has been writen and is maintained by the digiKam team.

# Technical Background

Detection only processes image data. Recognition requires persistent storage of learned results, so there is a database and some code to manage identities. The faces database is an SQLite file. If nothing else is requested, it's hosted in the user's home directory and can be shared with other applications which use libkface. The default location depends on the OS used:

- Linux: ~/.kde4/share/apps/libkface/database/recognition.db
- OSX: ~/Library/Preferences/KDE/share/apps/libkface/database/recognition.db
- Windows: ~/AppData/Roaming/.kde/share/apps/libkface/database/recognition.db

An identity is defined in \ref KFaceIface::Identity and used to identify real persons based on various data. \ref KFaceIface::TrainingDataProvider defines interfaces to feed the recognition process. \ref KFaceIface::FaceDetector is quite shallow as the backend is separated. \ref KFaceIface::RecognitionDatabase has some more code. Locking, database creation, and persistence, as well as identity management is includede. But no backend either. The database subdirectory contains a stripped-down version of the digiKam database management code, just enough to comfortably keep a database with recognition data. To process database operations, the backend usees Qt's QSL driver. The detection subdirectory contains the face detection backend, implemented by comparison of face and facial feature detectors based on the Viola-Jones general object detection framework (paper from Modesto Castrillón, Oscar Déniz, Daniel Hernández and Javier Lorenzo, Machine Vision and Applications, january 2008). This algorithm uses OpenCV Haar cascades, and tries to fine tune things. To work fine, Haar cascade XML files are required and loaded by libkface. For obscur reasons, these files are not published with OpenCV's Windows version. Thus, XML files are published through libkface to reduce problems with face detection. The recognition-opencv-lbph subdirectory contains the face recognizer backend which we currently use. It's based on Phillip Wagner's Local Binary Patterns Histograms (LPBH) implementation from OpenCV. The alignment-congealing, alignment-flandmark, and preprocessing-tantriggs subdirectories are implemented algorithms which should improve the performance of face recognition but they are currently not used because using them lead to inferior results.

# Database Contents

The SQLite file contains the tables listed below:

- Identities: contains a list of identities with type.
- IdentityAttributes: contains identity attributes as text name and UUID.
- OpenCVLBPHRecognizer: this table currently will have only one entry, there is only one recognizer (LPBH algorithm). But the database in theory supports to have multiple recognizers, possibly with different settings, or with training data from different sources, or different subsets of training data.
- OpenCVLBPHistograms: contains face histogram data for each identity depending of the application that was used when the training was done.
- Settings: includes dabase version rules.

# Test Tools

The tests subdirectory is the best place to play around with the library and fine tune algorithms. Align tool: Alignment means to take a detected face, try to find out from which angle the photo was taken, and re-align the face so that the recognition algorithm does not need to care for misalignment. We currently do not have such an algorithm, but people believe that commercial solutions have it. Preprocess tool: Preprocessing is suggested to remove the influence of lighting conditions etc. We have implemented the Tan-Triggs algorithm, which is quite simple. In non-exhaustive tests, the use of the algorithm lead to worse recognition performance. Detect tool: Performs face detection on an image and displays the results in a GUI window. Recognize tool: Performs face recognition using a face database for storage of trained faces. This tool is able to use the ORL database which contains a freely available set of face images to test face recognition. It consists of 10 photos each of 20 different peoples from slightly different angles. TrainDB tool: This is a simple program to create a local training DB, record 100 dummy items, verify items registration, and call recognition. It's purpose is to quickly check the database management code. KFaceGui tool: A simple GUI application able to run detection and recognition without using CLI tools.

# Client Applications

Libkface is currently used by digiKam to do face management. Look at these implementations for details. */