Overview

Service for personal protective equipment detection.

The service allows to perform people detection and classify if the detected person has any personal protective equipment.

Detection

People bounding box represented by 4 float numbers: x and y position of the left top corner, width, and height of the box. Numbers are normalized relative to the image size.

Endpoints

Get version

Returns an actual version of the service in format vX.Y.Z where X is the version of API.

Examples

Request:

$ curl -X 'GET' 'https://api4ai.cloud/ppe/v1/version'

Response:

v1.0.0

Analyze image and return results

Performs actual image analysis and responds with results.

Query parameter: detection

The detection query parameter allows the client to enable/disable people detection.

• If client passes True value then the service will perform detection. In this case the response may contain multiple boxes in output. Each detection will contain:
  • Bounding box: box.
  • Personal protective equipment classification entity ppe with glass, noglass, helmet, nohelmet, vest, novest classes and their probabilities.
  • Classification entity people-detector for detected bounding box which has only person class and the confidence.
• Otherwise if client passes False value then the image will be treated as a cropped person-only image and service will skip detection. In this case box is also appears in the response, but coordinates are always [0.0, 0.0, 1.0, 1.0].

Detection is enabled by default.

Response schema

For responses with 200 HTTP code, the type of response is JSON object with the following schema:

{
  "results": [
    {
      "status": {
        "code": "ok",
        "message": "Success"
      },
      "name": "curry.jpg",
      "md5": "11170166a6e894e74ff360ff3d01d6ef",
      "entities": [
        {
          "kind": "objects",
          "name": "ppe-detector",
          "objects": [
            {
              "box": ...,
              "entities": [
                {
                  "kind": "classes",
                  "name": "people-detector",
                  "classes": {
                    "person": ...
                  }
                },
                {
                  "kind": "classes",
                  "name": "ppe",
                  "classes": {
                    "glass": ...,
                    "noglass": ...,
                    "helmet": ...,
                    "nohelmet": ...,
                    "vest": ...,
                    "novest": ...
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Primary fields:

Other fields that are not described above always have the same values.

Passing image

Image can be passed by posting regular "multipart form data" in two alternative ways:

• as a binary file in image field
• as URL to some public resource in url field

Image must be a regular JPEG or PNG image (with or without transparency). Usually such images have extensions: .jpg, .jpeg, .png. The service checks the input file by MIME type and accepts the following types:

• image/jpeg
• image/png

The size of the image file must be less than 16Mb.

Examples

Request:

curl -X 'POST' 'https://api4ai.cloud/ppe/v1/results?api_key=...' -F 'image=@person.jpg'

Response:

{
  "results": [
    {
      "status": {
        "code": "ok",
        "message": "Success"
      },
      "name": "person.jpg",
      "md5": "11170166a6e894e74ff360ff3d01d6ef",
      "entities": [
        {
          "kind": "objects",
          "name": "ppe-detector",
          "objects": [
            {
              "box": [
                0.02378430962562561,
                0.025364607572555542,
                0.9789055287837982,
                0.974009782075882
              ],
              "entities": [
                {
                  "kind": "classes",
                  "name": "people-detector",
                  "classes": {
                    "person": 0.9750556349754333
                  }
                },
                {
                  "kind": "classes",
                  "name": "ppe",
                  "classes": {
                    "glass": 0.8393676280975342,
                    "noglass": 0.1606324166059494,
                    "helmet": 0.9929976463317871,
                    "nohelmet": 0.007002322468906641,
                    "vest": 0.3924143314361572,
                    "novest": 0.607585608959198
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Authentication

Some endpoints require authentication via API key. There are three alternative ways to pass API key:

• Pass API Key as query parameter api_key

  curl 'https://api4ai.cloud/some/end/point?api_key=1234567890'

• Pass API Key as query parameter key

  curl 'https://api4ai.cloud/some/end/point?key=1234567890'

• Pass API Key as HTTP Header x-api-key

  curl -H "x-api-key: 1234567890" 'https://api4ai.cloud/some/end/point'

Note: The API key 1234567890 and endpoint /some/end/point in the examples above are just for concept demonstration purposes and not actually working.

Possible errors

The service cannot process an image

When a client sends an image that can not be processed for some reason(s), the service responds with 200 code and returns JSON object in the same format as the format for successful analysis. In this case, the results[].status.code will have failure value and results[].status.message will contain relevant explanation.

Example of possible reasons for the issue:

• Unsupported file MIME type
• Corrupted image

Example response for image with unsupported MIME type:

{
  "results": [
    {
      "status": {
        "code": "failure",
        "message": "Unsupported media type. Expected one of ['image/jpeg', 'image/png']. Got 'text/plain'."
      },
      "name": "file.txt",
      "md5": "d41d8cd98f00b204e9800998ecf8427e",
      "entities": []
    }
  ]
}

Request size is too big

Request size is limited by approximately 32Mb. When a client sends a request that exceeds this limit, the service responds with a 413 code.

The typical reason for exceeding this limit is overly large image. Taking into account additional HTTP overhead, we strongly recommend not passing image files of size more than 16Mb.

Example response for overly large image:

Error: Request Entity Too Large

Your client issued a request that was too large.

Missing image

When a client sends a request without an image, the service responds with 422 code and returns a JSON object.

Example response for request with missing image:

{
  "detail": [
    {
      "loc": [
        "body",
        "image"
      ],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Client passes invalid API key

When a client sends an invalid API key, the service responds with 400 code and returns JSON object code and message root field.

Example response for request with an invalid API key:

{
  "message": "INVALID_ARGUMENT:API key not valid. Please pass a valid API key.",
  "code": 400
}

Client didn't pass API key

When a client sends a request without an API key, the service responds with 401 code and returns JSON object code and message root field.

Example response for request without an API key:

{
  "message": "UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.",
  "code": 401
}