Skip to main content

alignFace

warning

The document is a continuation of the previous document, if you have landed directly on this page then, Please read from page Get started.

What is alignFace component ?​

alignFace component is used to crop and align the detected faces.

  • Description : alignFace() takes an input(through STDIN) as image in base64 format and probability in float both wrapped in JSON format and returns the face information with each face probability greater than input given. Check Input and output parameters for details.
  • Parameters :
    • Input(Via STDIN) : alignFace.stdin() << inputJson << std::endl;
      • An inputJson String with following parameters:
        • Parameter1 : Image (.jpg/.png) in base64 format
        • Parameter2 : For each detected face
          • Bounding box co-ordinates
          • Probability being face
          • 5 Landmarks co-ordinates values
      • Output(Via STDOUT) : alignFace.stdout() >> outputJson;
        • An outputJson string with following contents
          • Image in base64 format
          • int requestID
  • Using alignFace component
    • With our detectFaces component: To understand how to use alignFace with detectFaces component, check this section
    • You can also use alignFace with any other detectFaces component but inputJson for alignFace should be in the format of outputJson of detectFaces component.

List of alignFace features in shunya stack​

  1. Get aligned face data.

Using alignFace​

Requirements to use alignFace​

  1. Shunya OS installed (supported Arm devices) or Shunya OS docker container (X86 based windows/linux devices)
  2. Shunya AI installed in Shunya OS.

Steps to use alignFace​

  1. Read inputJson.
  2. Call API binary
  3. Get aligned face image adn store
note

Run the steps given below inside Shunya OS installed (supported Arm devices) or Shunya OS docker container (X86 based windows/linux devices) terminals.

Lets take an example use case: Say we need to

  1. Align the detected face

Steps are

Step 1: Read inputJson​

  1. Start with a ready to use template for detecting faces from video/image.

    git clone https://gitlab.iotiot.in/shunya/products/shunya-ai-examples.git

  2. Open the examples in a text editor and modify as per your usecase.

    • For CPP you will find the examples in the folder cpp-examples/face-recognition/alignFace
    • Open the file align_face.cpp
    • Modify the line to set the input json filename.
    • IMP Note: inputJsonRaw.json file contains the parameter1 and parameter2 of input. If you want to see how it looks you can check below.
    /* Reading the json file and convert it into the Json string format */
    std::ifstream ifs { R"(inputJsonRaw.json)" };
    if ( !ifs.is_open() )
    {
        std::cerr << "Could not open file for reading!\n";
        return EXIT_FAILURE;
    }
    IStreamWrapper isw { ifs };

    Document doc {};
    doc.ParseStream( isw );

    StringBuffer buffer {};
    Writer<StringBuffer> writer { buffer };
    doc.Accept( writer );

    if ( doc.HasParseError() )
    {
        std::cout << "Error  : " << doc.GetParseError()  << '\n'
                  << "Offset : " << doc.GetErrorOffset() << '\n';
        return EXIT_FAILURE;
    }
    /* Finally we get inputJson string */
    const std::string inputJson { buffer.GetString() };

Step 2: Call API binary​

  1. We will now call API binary by giving input image(parameter1) and face info(parameter2) as an input through STDIN.

    /*################# Call alignFace Component ###################*/
    subprocess::popen alignFace("/usr/bin/alignFace", {});
    /* Passing inputJson to the API */
    alignFace.stdin() << inputJson << std::endl;
    alignFace.close();
    std::string outputJson;
    /* Getting output in outputJson */
    alignFace.stdout() >> outputJson;

Step 3: Get aligned face image and store​

  1. Following code read the output of alignFace API and stores image in system.
    /* ---- Parse outputJson  ---- */
    rapidjson::Document alignFaceOutJSON = readJsonString(outputJson);
    std::string b64Img(alignFaceOutJSON["data"]["image"].GetString(),
                       alignFaceOutJSON["data"]["image"].GetStringLength());
    cv::Mat image = base642Mat(b64Img);
    /* Storing image with draw alignedFace.jpg in system */
    cv::imwrite("alignedFace.jpg",image);

Run ready to use example.​

```shell
git clone https://gitlab.iotiot.in/shunya/products/shunya-ai-examples.git
cd  cpp-examples/face-recognition/alignFace
mkdir build && cd build
cmake ../
make 
# before running alignFaceCpp make sure you have inputJsonRaw.json in build directory
./alignFaceCpp
```

  1. Running the codes will print the JSON output on the terminal (to STDOUT).

    For Example:

    • Lets say the input image is

      Oops!, No Image to display.

    • Input JSON is

      {
          "data": {
              "faces": [{
                  "faceId": "face0",
                  "boundingBox": {
                      "top": 125.00978088378906,
                      "left": 124.74224853515625,
                      "width": 59.70306396484375,
                      "height": 71.89865112304688
                  },
                  "confidence": 0.9994653463363648,
                  "landmarks": [{
                      "type": "pupilLeft",
                      "x": 140.8665008544922,
                      "y": 149.56112670898438
                  }, {
                      "type": "pupilRight",
                      "x": 167.63665771484376,
                      "y": 150.40902709960938
                  }, {
                      "type": "noseTip",
                      "x": 153.38809204101563,
                      "y": 161.689208984375
                  }, {
                      "type": "mouthLeft",
                      "x": 141.44529724121095,
                      "y": 174.52609252929688
                  }, {
                      "type": "mouthRight",
                      "x": 164.7596893310547,
                      "y": 175.16357421875
                  }]
              },
              ],
              "image": "/e98239u9r93ynm9rfumu02398r8umc9ejmrc8ew0r374y8uhmcwe,=="
          }
      }

    • Then the JSON output is 

      {
          "apiVersion": "1.2.0",
          "requestId": 19287918271287,
          "data": {
              "image": "base64str"
          }
      }

This part is not updated yet (please do not use below example)​

Understand this component with an example (ready to use code)​

  • This is an example for face-recognition and here we will be using 5 components: detectFaces, alignFace, getEmbeddings, storeFace, findFace

  • Check this ready to use example in c++ and python

  • Download the code

    git clone https://gitlab.iotiot.in/shunya/products/shunya-ai-examples.git
    cd shunya-ai-examples/cpp-examples/face-recognition
    ```shell git clone https://gitlab.iotiot.in/shunya/products/shunya-ai-examples.git cd shunya-ai-examples/python-examples/face-recognition ```

  • In this folder there is a file, find_face.cpp or find_face.py

  • detectFaces Components used 

    subprocess::popen detectFaces("/usr/bin/detectFaces", {});
    ```shell detectFaces = Popen(['/usr/bin/detectFaces'], stdout=PIPE, stdin=PIPE) ```

  • alignFace component used

    subprocess::popen alignFace("/usr/bin/alignFace", {});
    ```shell alignFace = Popen(['/usr/bin/alignFace'], stdout=PIPE, stdin=PIPE) ```

  • getEmbeddings component used

    subprocess::popen getEmbeddings("/usr/bin/getEmbeddings", {});
    ```shell getEmbeddings = Popen(['/usr/bin/getEmbeddings'], stdout=PIPE, stdin=PIPE) ```

  • storeFace component used

    subprocess::popen storeFace("/usr/bin/storeFace", {});
    ```shell storeFace = Popen(['/usr/bin/storeFace'], stdout=PIPE, stdin=PIPE) ```

  • findFace component used

    subprocess::popen findFace("/usr/bin/findFace", {});
    ```shell findFace = Popen(['/usr/bin/findFace'], stdout=PIPE, stdin=PIPE) ```

  • Run code by yourself

    mkdir build && cd build
    cmake .. && make
    ./findFaceCpp
    ```shell python3 find_face.py ```
    - You will get a name of person.

Facing errors with the component?​