Basic usage
==============

Usage of DFACE modules
-------------------------------

The SDK provides face detection, face recognition, face pose, liveness detect and other independent functions to provide corresponding modules, users can flexibly call according to their own needs.

======================
1. DfaceDetect
======================

DfaceDetect is a face detection module, which can realize multi-person detection, maximum face detection.

   .. code:: java
         
        //set min size
        dfaceDetect.SetMinSize(60);
        dfaceDetect.SetNumThreads(1);
        //Detect face and return to face box list
        List<Bbox> faceBboxs = dfaceDetect.detection(frame, false);


===========================================
2. DfaceTrack
===========================================

DfaceTrack is a face tracking module that can implement real-time multi-face tracking.

 .. code:: java

        //start track
        dfaceTrack.start();
        while(frame){
           //detect face
           List<Bbox> faceBboxs = dfaceDetect.detection(frame, false);
           //Tracking faces requires the above frame input for detecting faces
           List<Bbox> trackBoxs = dfaceTrack.update(frame, faceBboxs);
        }
        //stop track
        dfaceTrack.stop();
        
.. warning::
    Tracking is an estimation judgment, so the returned position information may exceed the camera screen range. It is best to use it alone to make a judgment with the camera screen range to avoid cross-border access.


======================
3. DfaceRecognize
======================
DfaceRecognize is a face recognition module, mainly used for face feature extraction. Currently, there are three precision modes: high-precision mode, normal mode, and real-time mode. Because high-precision mode is very CPU-intensive, it is not suitable for embedded-side operation. Real-time mode is recommended for embedded-side operation.
.. code:: java
         
        //set min size
        List<Bbox> bbox = dfaceDetect.detectionMax(frame, true);
        //Extract face features
        byte[] feature1 = dfaceRecognize.extractFaceFeatureByImg(frame, bbox.get(0));




=======================================
４. DfaceCompare
=======================================

DfaceCompare is often used for face feature comparison, suitable for 1:1, 1:n comparison.

.. code:: java

        //Extract face features
        byte[] feature1 = dfaceRecognize.extractFaceFeatureByImg(frame, bbox1Lst.get(0));
        byte[] feature2 = dfaceRecognize.extractFaceFeatureByImg(frame, bbox2Lst.get(0));
        //n feature
        byte[][] feature_n;
        //n feature id
        long[] idx_n;
        //Feature comparison (1:1)
        float similarity = dfaceCompare.similarityByFeature(feature1, feature2);
        //Feature comparison (1:n), return the top feature IDs with similarity higher than threshold
        int[] idx = dfaceCompare.similarityByFeatureSort(feature_1,feature_n[][], dx_n, top, threshold)	
        

.. warning::

    DfaceCompare initialization needs to specify the precision mode.


=============================
５. DfacePose
=============================
DfacePose is a face pose module, which is mainly used to detect landmarks and poses of face 98.

    .. code:: java
         
        //set min size
        List<Bbox> bbox = dfaceDetect.detectionMax(frame, true);
        //detect landmarks
        List<FaceLandmark> poses = dfacePose.predictPose(frame, Arrays.asList(bbox));
        

    .. note::
        - Euler angles Introduction `Euler angles <https://en.wikipedia.org/wiki/Euler_angles>`__
        - yaw: Face view, turning the face to the right is a positive angle, turning the face to the left is a negative angle (unit degree)
        - pitch: Face view, downward is a positive angle, upward is a negative angle (unit degree)
        - roll: Face view, roll right is positive, and roll left is negative (unit degree)
        - t_x: Camera view, the deviation to the right of the camera is positive, and the left is negative (unit meters)
        - t_y： Camera view, the deviation from the camera is positive, and the negative is negative (unit meters)
        - t_z：  Camera view. The farther away from the camera, the larger the value. This value is closely related to the focal length of the camera. The actual generation environment needs to set the focal length parameters


============================
６. DfaceRGBLiveness
============================

DfaceRGBLiveness is an RGB liveness detection module, commonly used for liveness detect.

    .. code:: java
        
        //Liveness detect needs to switch back to the original image, minimize the information loss caused by resize
        float score = dfaceRGBLiveness.liveness_check(frame, boxs.get(0));


.. warning::

    According to the returned score, the score is close to 0: non-living 　 score close to 1: living



=======================================
７. DfaceNIRLiveness
=======================================

DfaceNIRLiveness is a near-infrared liveness detection module, commonly used for infrared liveness detect.

.. code:: java

        //Liveness detect
        int live = dfaceNIRLiveness.liveness_check(ir_box, color_box);

.. warning::

    The binocular liveness detect requires an infrared camera input screen, but the input face frame position is detected by the color camera.


=======================================
８. DfaceTool
=======================================
DfaceTool tool class contains some image processing, feature conversion and database processing methods.