.. _api_detect:


Detect objects in a photo
=============================

To detect objects in a photo, use this method:

.. code::

    POST /detect

The REQUEST BODY is required and contains multipart/form-data with the following parameters. 

.. _request_parameters:

+-------------------------+---------------------+------------------------------------------------+
| Name                    | Type                | Description                                    |                        
+=========================+=====================+================================================+
| ``photo``               | binary              | Source image file.                             |
+-------------------------+---------------------+------------------------------------------------+
| ``attributes``          | object              | Contains attributes that can be detected for   |
|                         |                     | the following object types: face, vehicle,     |                                                                 
|                         |                     | and body.                                      |
+-------------------------+---------------------+------------------------------------------------+

The ``attributes`` field may be empty or include the ``face``, ``car``, and ``body`` objects, each with the following set of parameters:

+--------------------------------------+----------------+--------------------------------------------------------------------+
| Name                                 | Type           | Description                                                        |
+=========+============================+================+====================================================================+
| ``face``                             | object         | Contains face attributes.                                          |
+---------+----------------------------+----------------+--------------------------------------------------------------------+
|         | ``age``                    | boolean        | If ``true``, the estimated age is included in the response.        |                                              
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``beard``                  | boolean        | If ``true``, the presence of a beard is detected.                  |                                                    
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``emotions``               | boolean        | If ``true``, the facial expression is detected  (surprise, sadness,|
|         |                            |                | happiness, neutral expression, fear, disgust, anger).              |                                         
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``glasses``                | boolean        | If ``true``, the presence and type of glasses is detected.         |                                              
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``gender``                 | boolean        | If ``true``, the gender is determined.                             |                                                    
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``medmask``                | boolean        | If ``true``, the presence of a medical mask and its improper       |
|         |                            |                | positioning on the face is detected.                               |
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``headpose``               | boolean        | If ``true``, the head turn and head tilt angles are estimated.     |                                                                                
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``eyes_attrs``             | boolean        | If ``true``, the eye state is determined (eyes opened, eyes closed,|
|         |                            |                | eyes occluded).                                                    |                            
+---------+----------------------------+----------------+--------------------------------------------------------------------+
| ``car``                              | object         | Contains vehicle attributes.                                       |
+---------+----------------------------+----------------+--------------------------------------------------------------------+
|         | ``description``            | boolean        | If ``true``, the response will include details about the vehicle,  |
|         |                            |                | such as its body type, make, model, and body color.                |                                              
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``license_plate``          | boolean        | If ``true``, the response will include information about the       |
|         |                            |                | vehicle's license plate, such as its number, country, region,      |
|         |                            |                | and number color.                                                  |                                                    
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``special_vehicle_type``   | boolean        | If ``true``, the response will indicate whether the vehicle belongs|
|         |                            |                | to a special category (e.g., ``taxi``, ``route_transport``).       |                                         
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``category``               | boolean        | If ``true``, the response will include the vehicle’s category      |
|         |                            |                | (e.g., ``B``, ``C``).                                              |                                              
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``weight_type``            | boolean        | If ``true``, the response will include the vehicle's weight        |
|         |                            |                | classification (e.g., ``B_heavy``, ``D_light``).                   |                                                    
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``orientation``            | boolean        | If ``true``, the response will include the vehicle's angle in      |
|         |                            |                | the photo (e.g., ``front``, ``side``, ``back``).                   |
+---------+----------------------------+----------------+--------------------------------------------------------------------+
| ``body``                             | object         | Contains body attributes.                                          |
+---------+----------------------------+----------------+--------------------------------------------------------------------+
|         | ``color``                  | boolean        | If ``true``, the colors of the upper and lower clothing are        |
|         |                            |                | detected.                                                          |                                              
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``clothes``                | boolean        | If ``true``, the response will include details about clothing,     |
|         |                            |                | such as the type of upper-body clothing, the presence and length   |
|         |                            |                | of its sleeves, lower-body clothing, and headwear.                 |                                                    
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``bags``                   | boolean        | If ``true``, the response will indicate whether a bag is present   |
|         |                            |                | in the hand or on the back.                                        |                                         
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``protective_equipment``   | boolean        | If ``true``, the presence and color of a vest and helmet           |
|         |                            |                | is detected.                                                       |                                              
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``age_gender``             | boolean        | If ``true``, the age group and gender is determined.               |                            
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``fall``                   | boolean        | If ``true``, the response will indicate whether the person has     |
|         |                            |                | fallen.                                                            |
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``handface``               | boolean        | If ``true``, the following actions are detected: smoking,          |
|         |                            |                | using a phone, and making a phone call.                            |                                                           
+         +----------------------------+----------------+--------------------------------------------------------------------+
|         | ``phoneuse``               | boolean        | If ``true``, the action of taking pictures with a phone            |
|         |                            |                | is detected.                                                       |                            
+---------+----------------------------+----------------+--------------------------------------------------------------------+

Attach a source image file and send the ``POST`` request.

.. rubric:: CURL example

.. code::

 curl -X POST "http://<findface-ip:port>/detect" \
 -H "Authorization: Token <token>" \
 -H "Content-Type: multipart/form-data" \
 -F "photo=@sample_face.jpg" \
 -F 'attributes={
  "face": {
    "age": true,
    "beard": true,
    "emotions": true,
    "glasses": true,
    "gender": true,
    "medmask": true,
    "headpose": true,
    "eyes_attrs": true
  },
  "car": {
    "description": false,
    "license_plate": false,
    "special_vehicle_type": false,
    "category": false,
    "weight_type": false,
    "orientation": false
  },
  "body": {
    "color": false,
    "clothes": false,
    "bags": false,
    "protective_equipment": false,
    "age_gender": false,
    "fall": false,
    "handface": false,
    "phoneuse": false
  }
 }'

.. tip::

  Replace ``sample_face.jpg`` with the full path if the file is not in your current working directory.
  Example: ``"photo=@/home/ubuntu/sample_face.jpg"``

If the response is successful (OK: 200), it returns a JSON object that contains the following :ref:`parameters <detect_response_parameters>`. :ref:`Example <detect_response_example>`.

.. _detect_response_parameters:

.. list-table::
     :widths: 14 8 45
     :header-rows: 1

     * - Name 
       - Type 
       - Description
     * - ``orientation*``
       - integer
       - EXIF orientation of the photo.
     * - ``objects``
       - object
       - Contains arrays of data. Each array includes information about detected objects of a specific type (face, body, or vehicle), along with their attributes specified in the request.

.. _detect_response_example:

.. rubric:: Response example

.. code::

 {
  "orientation": 1,
  "objects": {
    "face": [
      {
        "id": "d1uvcdskd5qs72mq52h0",
        "bbox": {
          "left": 722,
          "top": 31,
          "right": 801,
          "bottom": 132
        },
        "detection_score": 0.5006658,
        "low_quality": false,
        "features": {
          "age": 25,
          "beard": {
            "name": "none",
            "confidence": 0.052511778
          },
          "emotions": {
            "name": "neutral",
            "confidence": 0.9908866
          },
          "glasses": {
            "confidence": 0.89929795,
            "name": "none"
          },
          "gender": {
            "confidence": 0.99800926,
            "name": "female"
          },
          "medmask": {
            "confidence": 0.9999994,
            "name": "none"
          },
          "headpose_pitch": {
            "name": 6.227072,
            "confidence": 1
          },
          "headpose_yaw": {
            "name": 20.798172,
            "confidence": 1
          },
          "eyes_attrs": {
            "confidence": 0.8949018,
            "name": "opened"
          }
        }
      }
    ],
    "body": [
      {
        "id": "d1uvceskd5qs72mq52hg",
        "bbox": {
          "left": 522,
          "top": 5,
          "right": 933,
          "bottom": 792
        },
        "detection_score": 0.82396024,
        "low_quality": false,
        "features": {}
      }
    ]
  }
 }

In the response, you will receive the ``id`` and bounding box (bbox) coordinates of the object (``face``, ``car``, ``body``). Copy the ``id`` of the required object to :ref:`add the object <api_object>` to a record or to :ref:`search for the object <api_search_objects>`.