Spoof Detection
================

Active Spoof
------------
Active spoof works by observing the geometry and perspective of a face as it moves closer to a camera.
Active spoof requires two input images, one far and one close, and is an involved process.
Therefore, please be sure to consult the `sample code <https://github.com/getchui/sample-apps/blob/master/cpp_sdk/cpp_dist_bundle/c%2B%2B/active_spoof.cpp>`_ for a demonstration of proper usage.

.. doxygenfunction:: Trueface::SDK::checkSpoofImageFaceSize

.. doxygenfunction:: Trueface::SDK::detectActiveSpoof

.. doxygenenum:: Trueface::ActiveSpoofStage

.. doxygenenum:: Trueface::SpoofLabel

Passive Spoof
-------------
Passive spoof is meant to be used for selfie-style images from smartphones or from laptop webcams, and should not be used with CCTV cameras / cameras at a distance.
Unlike active spoof which requires two input images (one close and one far), passive spoof requires only a single input image.
This being said, there are still strict requirements for said input image:

- Face must be at least 100 pixels in height. Face height must also be between 0.323 and 0.55 of the total image height.
- The face must be centered vertically and horizontally within the frame for portrait images. Landscape images are more permissive for horizontal centering as a portrait region is cropped around the face.
- The face must have neutral yaw, pitch, and roll, and must be facing the camera directly.
- The eyes must be open.
- User must not be wearing a mask.
- The image must not be overly bright or dark.

If any of the above criteria are not met, the method will return an error code. It is therefore imperative to check the return value of the function.
Please consult the `sample code <https://github.com/getchui/sample-apps/blob/master/cpp_sdk/cpp_dist_bundle/c%2B%2B/spoof_detection.cpp>`_ for proper usage of this method. We advise running this method on the front end so that immediate feedback can be provided to the user until they submit a conforming image.
We also advise running multiple images through the spoof detector (4-6) and then taking the average result.

.. doxygenfunction:: Trueface::SDK::detectSpoof

Below are two examples of **conforming** images, one landscape, and one portrait:

.. image:: ../../shared/images/real_1.jpg
   :width: 300pt

.. image:: ../../shared/images/real_2.jpg
   :width: 200pt

Below are four examples of **non-conforming** images:

Face too far:

.. image:: ../../shared/images/real_too_far.jpg
   :width: 200pt

Face too close:

.. image:: ../../shared/images/real_too_close.jpg
   :width: 200pt

Face yaw angle too extreme:

.. image:: ../../shared/images/real_angle_too_extreme_1.jpg
   :width: 200pt

Face roll angle too extreme:

.. image:: ../../shared/images/real_angle_too_extreme_4.jpg
   :width: 200pt

Image too bright:

.. image:: ../../shared/images/real_image_too_bright.png
   :width: 200pt