.. _bodies:

Enable Body and Body Attribute Recognition
==============================================

FindFace Server allows you to recognize individual human bodies and body attributes.

The body attributes are as follows:

* gender:

  * male;
  * female;

* age (by group):

  * 0-16 years;
  * 17-35 years;
  * 36-50 years;
  * 50+ years;

* clothing type:

  * generalized category of upper body wear: long sleeves, short sleeves, no sleeve;
  * specific type of upper body wear: jacket, coat, sleeveless vest, sweatshirt, T-shirt, shirt, dress;
  * type of lower body wear: pants, skirt, shorts, nondescript;
  * type of headgear: hat/cap, hood/headscarf, none;

* clothing color (top/bottom);

* presence of personal protective equipment (PPE):

  * PPE item: vest, helmet;
  * PPE color;
  * PPE recognition score;

* whether a person has a bag:

  * on the back;
  * in hand(s).

This section describes how to enable body and body attribute recognition.

To enable recognition of human bodies and their attributes, do the following:

#. Specify neural network models for body object and body attribute recognition in the ``/opt/ffserver/configs/extraction-api.yaml`` configuration file.

   .. important::
      Be sure to choose the right acceleration type for each model, matching the acceleration type of ``extraction-api``: CPU or GPU. Be aware that ``extraction-api`` on CPU can work only with CPU-models, while ``extraction-api`` on GPU supports both CPU- and GPU-models.

   #. Open the ``extraction-api.yaml`` configuration file.

      .. code:: bash

         sudo vi /opt/ffserver/configs/extraction-api.yaml

   #. Specify the body detector model in the ``detectors -> models`` section by pasting the following code:

      .. rubric:: GPU

      .. code:: bash

         detectors:
           ...
           models:
             ...
             body_gustav:
               aliases:
               - body
               - edie
               - shiloette
               - glen
               model: detector/bodydet.kali.021.gpu.fnk
               options:
                 min_object_size: 32
                 resolutions:
                 - 2048x2048
           ...

      .. rubric:: CPU

      .. code:: bash

         detectors:
           ...
           models:
             ...
             body_gustav:
               aliases:
               - body
               - edie
               - shiloette
               - glen
               model: detector/bodydet.kali.021.cpu.fnk
               options:
                 min_object_size: 32
                 resolutions:
                 - 2048x2048
           ...


   #. Make sure that the ``objects -> body`` section contains the ``quality_attribute: body_quality`` and the  ``base_normalizer: facenorm/cropbbox.v2.gpu.fnk`` or the ``base_normalizer: facenorm/cropbbox.v2.cpu.fnk``, depending on your acceleration type:

      .. rubric:: GPU

      .. code:: bash

         objects:
           ...
           body:
             base_normalizer: facenorm/cropbbox.v2.gpu.fnk
             quality_attribute: body_quality
           ...

      .. rubric:: CPU

      .. code:: bash

         objects:
           ...
           body:
             base_normalizer: facenorm/cropbbox.v2.cpu.fnk
             quality_attribute: body_quality
           ...

   #. Make sure that the ``normalizers`` section contains a model for the ``cropbbox`` normalizer, as shown in the example below. This normalizer is required for the extractors.

      .. rubric:: GPU

      .. code:: bash

         normalizers:
           ...
           models:
             ...
             cropbbox:
               model: facenorm/cropbbox.v2.gpu.fnk
             ...

      .. rubric:: CPU

      .. code:: bash

         normalizers:
           ...
           models:
             ...
             cropbbox:
               model: facenorm/cropbbox.v2.cpu.fnk
             ...

   #. Specify the extraction models in the ``extractors -> models`` section, subject to the extractors you want to enable:

      .. rubric:: GPU

      .. code:: bash

         extractors:
            ...
            models:
              body_age_gender:
                default:
                  model: pedattr/pedattr.age_gender.v0.gpu.fnk
              body_bags:
                default:
                  model: pedattr/pedattr.bags.v0.gpu.fnk
              body_clothes:
                default:
                  model: pedattr/pedattr.clothes_type.v0.gpu.fnk
              body_color:
                default:
                  model: pedattr/pedattr.color.v1.gpu.fnk
              body_emben:
                default:
                  model: pedrec/pedrec.durga.gpu.fnk
              body_protective_equipment:
                default:
                  model: pedattr/pedattr.protective.v1.gpu.fnk
              body_quality:
                default:
                  model: pedattr/pedattr.quality.v0.gpu.fnk
            ...

      .. rubric:: CPU

      .. code:: bash

         extractors:
            ...
            models:
              body_age_gender:
                default:
                  model: pedattr/pedattr.age_gender.v0.cpu.fnk
              body_bags:
                default:
                  model: pedattr/pedattr.bags.v0.cpu.fnk
              body_clothes:
                default:
                  model: pedattr/pedattr.clothes_type.v0.cpu.fnk
              body_color:
                default:
                  model: pedattr/pedattr.color.v1.cpu.fnk
              body_emben:
                default:
                  model: pedrec/pedrec.durga.cpu.fnk
              body_protective_equipment:
                default:
                  model: pedattr/pedattr.protective.v1.cpu.fnk
              body_quality:
                default:
                  model: pedattr/pedattr.quality.v0.cpu.fnk
            ...


      The most used extraction models are the following:

      +------------------+---------------------------------------------------------------------------------+
      | Extractor        | Configure as follows                                                            |
      +==================+=================================================================================+
      | age and gender   | ``body_age_gender: pedattr/pedattr.age_gender.v0.gpu.fnk``                      |
      |                  +---------------------------------------------------------------------------------+
      |                  | ``body_age_gender: pedattr/pedattr.age_gender.v0.cpu.fnk``                      |
      +------------------+---------------------------------------------------------------------------------+
      | presence of bag  | ``body_bags: pedattr/pedattr.bags.v0.gpu.fnk``                                  |
      |                  +---------------------------------------------------------------------------------+
      |                  | ``body_bags: pedattr/pedattr.bags.v0.cpu.fnk``                                  |
      +------------------+---------------------------------------------------------------------------------+
      | clothing type    | ``body_clothes: pedattr/pedattr.clothes_type.v0.gpu.fnk``                       |
      |                  +---------------------------------------------------------------------------------+
      |                  | ``body_clothes: pedattr/pedattr.clothes_type.v0.cpu.fnk``                       |
      +------------------+---------------------------------------------------------------------------------+
      | clothing color   | ``body_color: pedattr/pedattr.color.v1.gpu.fnk``                                |
      |                  +---------------------------------------------------------------------------------+
      |                  | ``body_color: pedattr/pedattr.color.v1.cpu.fnk``                                |
      +------------------+---------------------------------------------------------------------------------+
      | individual body  | ``body_emben: pedrec/pedrec.durga.gpu.fnk``                                     |
      | feature vector   +---------------------------------------------------------------------------------+
      |                  | ``body_emben: pedrec/pedrec.durga.cpu.fnk``                                     |
      +------------------+---------------------------------------------------------------------------------+
      | presence of      | ``body_protective_equipment: pedattr/pedattr.protective.v1.gpu.fnk``            |
      | protective       +---------------------------------------------------------------------------------+
      | equipment        | ``body_protective_equipment: pedattr/pedattr.protective.v1.cpu.fnk``            |
      +------------------+---------------------------------------------------------------------------------+
      | body quality     | ``body_quality: pedattr/pedattr.quality.v0.gpu.fnk``                            |
      |                  +---------------------------------------------------------------------------------+
      |                  | ``body_quality: pedattr/pedattr.quality.v0.cpu.fnk``                            |
      +------------------+---------------------------------------------------------------------------------+


#. Modify the ``/opt/ffserver/configs/video-worker.yaml`` configuration file.

   #. In the ``models`` section, specify the body neural network models by analogy with the example below:

      .. rubric:: GPU

      .. code:: bash

         sudo vi /opt/ffserver/configs/video-worker.yaml

      .. code:: bash

         models:
           ...
           detectors:
             ...
             body:
               fnk_path: /usr/share/findface-data/models/detector/bodydet.kali.021.gpu.fnk
               min_size: 60
             ...
           normalizers:
             ...
             body_norm:
               fnk_path: /usr/share/findface-data/models/facenorm/cropbbox.v2.gpu.fnk
             body_norm_quality:
               fnk_path: /usr/share/findface-data/models/facenorm/cropbbox.v2.gpu.fnk
             ...
           extractors:
             ...
             body_quality:
               fnk_path: /usr/share/findface-data/models/pedattr/pedattr.quality.v0.gpu.fnk
               normalizer: body_norm_quality

      .. rubric:: CPU

      .. code:: bash

         sudo vi /opt/ffserver/configs/video-worker.yaml

      .. code:: bash

         models:
           ...
           detectors:
             ...
             body:
               fnk_path: /usr/share/findface-data/models/detector/bodydet.kali.021.cpu.fnk
               min_size: 60
             ...
           normalizers:
             ...
             body_norm:
               fnk_path: /usr/share/findface-data/models/facenorm/cropbbox.v2.cpu.fnk
             body_norm_quality:
               fnk_path: /usr/share/findface-data/models/facenorm/cropbbox.v2.cpu.fnk
             ...
           extractors:
             ...
             body_quality:
               fnk_path: /usr/share/findface-data/models/pedattr/pedattr.quality.v0.cpu.fnk
               normalizer: body_norm_quality


   #. Make sure that the ``objects -> body`` section is included:

      .. code:: bash

           objects:
             ...
             body:
               normalizer: body_norm
               quality: body_quality
               track_features: ''


#. Open the ``/opt/ffserver/configs/video-manager.yaml`` configuration file and make sure it contains the ``body`` section in ``detectors`` that looks similar to the example below.


   .. code:: bash

      sudo vi /opt/ffserver/configs/video-manager.yaml

   .. code:: bash

      detectors:
        ...
        body:
          filter_min_quality: 0.6
          filter_min_size: 70
          filter_max_size: 8192
          roi: ''
          fullframe_crop_rot: false
          fullframe_use_png: false
          jpeg_quality: 95
          overall_only: true
          realtime_post_first_immediately: false
          realtime_post_interval: 1
          realtime_post_every_interval: false
          track_interpolate_bboxes: true
          track_miss_interval: 1
          track_overlap_threshold: 0.25
          track_max_duration_frames: 0
          track_send_history: false
          post_best_track_frame: true
          post_best_track_normalize: true
          post_first_track_frame: false
          post_last_track_frame: false
          tracker_type: simple_iou
          track_deep_sort_matching_threshold: 0.65
          track_deep_sort_filter_unconfirmed_tracks: true
          track_object_is_principal: false
          track_history_active_track_miss_interval: 0