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 getEmbeddings component ?​

getEmbeddings component is used to get unique 128 float embeddings for one face..

  • Description : getEmbeddings() takes an input(through STDIN) as image in base64 format and returns 128 float embeddings. Check Input and output parameters for details.

  • Parameters :

    • Input(Via STDIN) : getEmbeddings.stdin() << inputJson << std::endl;
      • A JSON String with following parameters:
        • Parameter1 : Image (.jpg/.png) in base64 format
    • Output(Via STDOUT) : getEmbeddings.stdout() >> outputJson;
      • A JSON string with following contents
        • flaot vector of 128 face embeddings
        • int responseID

  • Using getEmbeddings component

    • With our alignFace component: To understand how to use getEmbeddings with alignFace component, check this section
    • You can also use getEmbeddings with any other alignGace component but inputJson for getEmbeddings should be in the format of outputJson of alignFace component.

List of getEmbeddings features in shunya stack​

  1. Get 128 face embeddings

Using getEmbeddings​

Requirements to use getEmbeddings​

  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 getEmbeddings​

  1. Read inputJson.
  2. Call API binary
  3. Print 128 embeddings
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. Get 128 unique face embeddings for a face

Steps are

Step 1: Read inputJson.​

  1. Start with an ready to use template for aligning faces from image.

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

  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/getEmbeddings
    • Open the file get_embeddings.cpp
    • Modify the line to set input image json string
    • 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 getEmbeddings Component ###############*/
    subprocess::popen getEmbeddings("/usr/bin/getEmbeddings", {});
    /* Passing inputJson to the API */
    getEmbeddings.stdin() << inputJson << std::endl;
    getEmbeddings.close();
    std::string outputJson;
    /* Getting output in outputJson */
    getEmbeddings.stdout() >> outputJson;
  2. You will get output in outputJson string.

Step 3: Print 128 embeddings.​

  1. Code to print the json output, got from drawFaces API.
    /* ---- print outputJson  ---- */
    std::cout<<"\nEmbeddings: "<<outputJson<<"\n";

Run ready to use example.​

  1. Run example by yourself.

    mkdir build && cd build
    cmake ../
    make 
    # before running getEmbeddingsCpp make sure you have inputJsonRaw.json in build directory
    ./getEmbeddingsCpp

  2. 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

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

    • Then the JSON output is 

      {
          "apiVersion": "1.2.0",
          "requestId": 1606318527,
          "data": {
              "embeddings": [{
                  "value": 0.123456
              },
              {
                  "value": 0.123456
              },
              "similarly for 128 embedding"
              ],
          }
      }

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?​