Skip to main content



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 drawFaces component ?

drawFaces component is used to draw face data(detected faces information) on face image.

  • Description : drawFaces() takes an input(through STDIN) as image in base64 format, and detected faces information(bounding boxes, probability and 5 landmarks)(inputJson) and returns base64 string with drawn values on image(outputJson). Check Input and output parameters for details.
  • Parameters :
    • Input(Via STDIN) : drawFaces.stdin() << inputJson << std::endl;
      • An inputJson String with following parameters:
        • Parameter1: For each detected face
          • Bounding box co-ordinates
          • Probability being face
          • 5 Landmarks co-ordinates values
        • Parameter2: Original image in base64 string format
    • Output(Via STDOUT) : drawFaces.stdout() >> outputJson;
      • A outputJson string with following contents
        • Base64 image string with drawn landmarks, bounding boxes and probability
        • int requestID
  • Using drawFaces component
    • With our detectFaces component: To understand how to use drawFaces with detectFaces component, check this section
    • You can also use drawFaces with any other detectFaces component but inputJson for drawFaces should be in the format of outputJson of detectFaces component.

List of drawFaces features in shunya stack

  1. Get Image with drawn face detections

Using drawFaces

Requirements to use drawFaces

  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 drawFaces

  1. Read inputJson.
  2. Call API binary
  3. Store the image with drawn faceInfo

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. Give detected faces information as as input in JSON file
  2. Get JSON output of all the detected faces drawn on image.

Steps are

Step 1. Read inputJson.

  1. Start with an ready to use template for drawing faces on image.

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

    • For CPP you will find the examples in the folder shunya-ai-examples/indiv-components/cpp-examples/face-detection/drawFaces
    • Open the file draw_faces.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 drawFaces Component ###############*/
    subprocess::popen drawFaces("/usr/bin/drawFaces", {});
    /* Passing inputJson to the API */
    drawFaces.stdin() << inputJson << std::endl;
    std::string drawFacesOut;
    /* Getting output in outputJson */
    drawFaces.stdout() >> outputJson;
  2. You will get output in outputJson string.

Step 3. Store the image with drawn faceInfo

  1. Code to print the json output, got from drawFaces API.
    /* ---- Parse outputJson  ---- */
    rapidjson::Document drawFaceOutJSON = readJsonString(outputJson);
    std::string b64Img(drawFaceOutJSON["data"]["image"].GetString(),
    cv::Mat image = base642Mat(b64Img);
    /* Storing image with draw drawnFace.jpg in system */

Run ready to use example.

  1. Run example by yourself.

    mkdir build && cd build
    cmake ../
    # before running drawFacesCpp make sure you have inputJsonRaw.json in build directory
  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 containing face data is

      "image": "/e98239u9r93ynm9rfumu02398r8umc9ejmrc8ew0r374y8uhmcwe,=="
    • Then the JSON output is

      "apiVersion": "1.2.0",
      "requestId": 1606318527,
      "data": {
      "image": "lkdn=sdfsdfin/slnsfd"

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

  • This is an example for face-detection and here we will be using 2 components: detectFaces and drawFaces

  • Check this ready to use example in c++

  • Download the code

    git clone
    cd example/shunya-ai-examples/cpp-examples/face-detection
  • In this folder there is a file, face_detect.cpp

  • Using video component for capturing images from video

    /* --- Capturing image from video using Video component --- */
    captureObj src = newCaptureDevice("video-source"); /* Create capture Instance */
    cv::Mat inputImage;
    int32_t outIndex = 0;

    /*################## Call Video Component functions ################*/
    inputImage = captureFrameToMem(&src); /* Capture one frame at a time in a loop*/

    if (inputImage.empty()) {
    fprintf(stderr, "End of video file!.");
    return 0;
  • Using detectFace component

    /* ---- Create Input JSON ---- */
    std::string b64InpImg = mat2Base64(inputImage);
    rapidjson::Document inputJson;
    rapidjson::Value inpImage;

    /* Set face detection probability */
    float probability = 0.8;

    inpImage.SetString(b64InpImg.c_str(), strlen(b64InpImg.c_str()), inputJson.GetAllocator());
    inputJson.AddMember("inputImage", inpImage, inputJson.GetAllocator());
    inputJson.AddMember("probability", probability, inputJson.GetAllocator());
    /*################## Call detectFaces Component ################*/
    subprocess::popen detectFaces("/usr/bin/detectFaces", {});
    detectFaces.stdin() << jsonDoc2Text(inputJson) << std::endl;
    std::string detectFacesOut;
    detectFaces.stdout() >> detectFacesOut;

  • Using drawFaces component

    rapidjson::Document detectFacesJson = readJsonString(detectFacesOut);
    if (detectFacesJson.HasMember("data")) {
    rapidjson::Value &results = detectFacesJson["data"]["faces"];
    /* Reading from json file and add it in the structure */
    for (rapidjson::SizeType i = 0; i < results.Size(); i++) {
    // calling drawFaces
    rapidjson::Value &drawFacesjson = detectFacesJson["data"];
    rapidjson::Document inDrawface;
    subprocess::popen drawFace("/usr/bin/drawFaces", {});
    //std::cout<<"\nprinting drawFace input: "<<jsonDoc2Text(inDrawface);
    drawFace.stdin() << jsonDoc2Text(inDrawface) << std::endl;
    std::string drawFaceOut;
    drawFace.stdout() >> drawFaceOut;
    rapidjson::Document drawFaceOutJSON = readJsonString(drawFaceOut);
    std::string b64Img(drawFaceOutJSON["data"]["image"].GetString(),
    cv::Mat image = base642Mat(b64Img);
    std::cout<<"\nImage Stored !";
    std::cout<<"\nThere is no data member in json";
  • Run code by yourself

    mkdir build && cd build
    cmake .. && make
    • You will get a new image stored in system.
    Oops!, No Image to display.

Facing errors with the component?