.. index:: 
  !PortraitProcessor Class

.. _id3_face_portrait_processor_class:

===============================================================================
PortraitProcessor Class
===============================================================================

Namespace: :ref:`id3.Face<reference_face>`

.. toctree::
  :hidden:

  backgroundColorUniformityThreshold<background_color_uniformity_threshold>
  backgroundStructureUniformityThreshold<background_structure_uniformity_threshold>
  createPortrait<create_portrait>
  cropAspectRatio<crop_aspect_ratio>
  cropEyePositionRatio<crop_eye_position_ratio>
  cropIcaoPortrait<crop_icao_portrait>
  cropIodRatio<crop_iod_ratio>
  cropMargin<crop_margin>
  cropPortrait<crop_portrait>
  detectOcclusions<detect_occlusions>
  detectPresentationAttack<detect_presentation_attack>
  dynamicRangeThreshold<dynamic_range_threshold>
  equalBrightnessThreshold<equal_brightness_threshold>
  estimateAge<estimate_age>
  estimateBackgroundUniformity<estimate_background_uniformity>
  estimateExpression<estimate_expression>
  estimateFaceAttributes<estimate_face_attributes>
  estimateGeometryQuality<estimate_geometry_quality>
  estimatePhotographicQuality<estimate_photographic_quality>
  expressionSensibility<expression_sensibility>
  eyeOcclusionThreshold<eye_occlusion_threshold>
  eyeOpeningThreshold<eye_opening_threshold>
  faceDetectionImageSize<face_detection_image_size>
  faceDetectionModel<face_detection_model>
  faceDetectionThreshold<face_detection_threshold>
  faceEncodingModel<face_encoding_model>
  faceMaskThreshold<face_mask_threshold>
  glassesThreshold<glasses_threshold>
  hatThreshold<hat_threshold>
  makeupThreshold<makeup_threshold>
  maleThreshold<male_threshold>
  maximumEyeGazeX<maximum_eye_gaze_x>
  maximumEyeGazeY<maximum_eye_gaze_y>
  maximumHeadHeightRatio<maximum_head_height_ratio>
  maximumHeadWidthRatio<maximum_head_width_ratio>
  maximumHorizontalPosition<maximum_horizontal_position>
  maximumIod<maximum_iod>
  maximumPitchAngle<maximum_pitch_angle>
  maximumRollAngle<maximum_roll_angle>
  maximumVerticalPosition<maximum_vertical_position>
  maximumYawAngle<maximum_yaw_angle>
  minimumHeadHeightRatio<minimum_head_height_ratio>
  minimumHeadWidthRatio<minimum_head_width_ratio>
  minimumHorizontalPosition<minimum_horizontal_position>
  minimumIod<minimum_iod>
  minimumVerticalPosition<minimum_vertical_position>
  mouthOcclusionThreshold<mouth_occlusion_threshold>
  mouthOpenThreshold<mouth_open_threshold>
  naturalSkinColorThreshold<natural_skin_color_threshold>
  noFlashReflectionThreshold<no_flash_reflection_threshold>
  noiseThreshold<noise_threshold>
  noseOcclusionThreshold<nose_occlusion_threshold>
  overExposureThreshold<over_exposure_threshold>
  padThreshold<pad_threshold>
  pixelationThreshold<pixelation_threshold>
  redEyeThreshold<red_eye_threshold>
  removeBackground<remove_background>
  reset<reset>
  resolutionThreshold<resolution_threshold>
  sharpnessThreshold<sharpness_threshold>
  smileThreshold<smile_threshold>
  threadCount<thread_count>
  tintedGlassThreshold<tinted_glass_threshold>
  trackerMatchingThreshold<tracker_matching_threshold>
  trackerMaximumFaceAge<tracker_maximum_face_age>
  trackerMinimumFaceAge<tracker_minimum_face_age>
  trackerNmsIouThreshold<tracker_nms_iou_threshold>
  underExposureThreshold<under_exposure_threshold>
  updatePortrait<update_portrait>


Definition
----------
.. line-block::
    Facilitates the creation of portraits in various scenarios such as enrolment or face verification.

.. tab-set::

    .. tab-item:: Python
      :sync: Python

      .. code:: Python

        class PortraitProcessor

    .. tab-item:: Dart
      :sync: Dart

      .. code:: Dart

        class PortraitProcessor implements Finalizable

    .. tab-item:: C#
      :sync: C#

      .. code:: C#

        public partial class PortraitProcessor

    .. tab-item:: Java
      :sync: Java

      .. code:: Java

        public class PortraitProcessor implements AutoCloseable, Serializable

    .. tab-item:: Swift
      :sync: Swift

      .. code:: Swift

        public class PortraitProcessor

    .. tab-item:: C
      :sync: C

      .. code:: C

        typedef struct id3FacePortraitProcessor *ID3_FACE_PORTRAIT_PROCESSOR;



Usage
-----

.. tab-set::

    .. tab-item:: Python
      :sync: Python

      .. code:: Python

        portraitProcessorInstance = id3face.PortraitProcessor()

      **Explicit destruction**

      .. code:: Python

        # ...
        del portraitProcessorInstance

    .. tab-item:: Dart
      :sync: Dart

      .. code:: Dart

        final portraitProcessorInstance = sdk.PortraitProcessor();
        // ...

      **Explicit destruction**

      .. code:: Dart

        // ...
        portraitProcessorInstance.dispose()

    .. tab-item:: C#
      :sync: C#

      .. code:: C#

        using (var portraitProcessorInstance = new PortraitProcessor())
        {
           // ...
        }

      **Explicit destruction**

      .. code:: C#

        var portraitProcessorInstance = new PortraitProcessor()
        // ...
        portraitProcessorInstance.Dispose()

    .. tab-item:: Java
      :sync: Java

      .. code:: Java

        try (PortraitProcessor portraitProcessorInstance = new PortraitProcessor()) {
        // ...
        }

      **Explicit destruction**

      .. code:: Java

        PortraitProcessor portraitProcessorInstance = new PortraitProcessor();
        // ...
        portraitProcessorInstance.close();

    .. tab-item:: Swift
      :sync: Swift

      .. code:: Swift

        private var portraitProcessorInstance: PortraitProcessor? = nil
        portraitProcessorInstance = try PortraitProcessor()

    .. tab-item:: C
      :sync: C

      .. code:: C

        ID3_FACE_PORTRAIT_PROCESSOR hPortraitProcessor{};
        int err = id3FacePortraitProcessor_Initialize(&hPortraitProcessor);
        if (err == ID3_SUCCESS) {
            // ...
            id3FacePortraitProcessor_Dispose(&hPortraitProcessor);
        }


Properties
----------

.. list-table:: 
  :width: 100%
  :widths: 30 5 65
  :header-rows: 1

  * - Name
    - Type
    - Description
  * - :ref:`backgroundColorUniformityThreshold<id3_face_portrait_processor_background_color_uniformity_threshold_class_member>`
    - int
    - Background color uniformity threshold.
  * - :ref:`backgroundStructureUniformityThreshold<id3_face_portrait_processor_background_structure_uniformity_threshold_class_member>`
    - int
    - Background structure uniformity threshold.
  * - :ref:`cropAspectRatio<id3_face_portrait_processor_crop_aspect_ratio_class_member>`
    - float
    - Aspect ratio (height to width) of the cropped portrait image.
  * - :ref:`cropEyePositionRatio<id3_face_portrait_processor_crop_eye_position_ratio_class_member>`
    - float
    - Ratio between the vertical eye position and the image height for ICAO portrait cropping. Must be in the range ]0;1[.
  * - :ref:`cropIodRatio<id3_face_portrait_processor_crop_iod_ratio_class_member>`
    - float
    - Ratio between the interocular distance (IOD) and the image width for ICAO portrait cropping. Must be in the range ]0;1[.
  * - :ref:`cropMargin<id3_face_portrait_processor_crop_margin_class_member>`
    - float
    - Relative margin around the face for basic portrait cropping.
  * - :ref:`dynamicRangeThreshold<id3_face_portrait_processor_dynamic_range_threshold_class_member>`
    - int
    - Face dynamic range threshold.
  * - :ref:`equalBrightnessThreshold<id3_face_portrait_processor_equal_brightness_threshold_class_member>`
    - int
    - Equal brightness threshold.
  * - :ref:`expressionSensibility<id3_face_portrait_processor_expression_sensibility_class_member>`
    - int
    - Sensibility of the expression classifier.
  * - :ref:`eyeOcclusionThreshold<id3_face_portrait_processor_eye_occlusion_threshold_class_member>`
    - int
    - Visible eye threshold.
  * - :ref:`eyeOpeningThreshold<id3_face_portrait_processor_eye_opening_threshold_class_member>`
    - int
    - Eye opening threshold.
  * - :ref:`faceDetectionImageSize<id3_face_portrait_processor_face_detection_image_size_class_member>`
    - int
    - The size, in pixels, of the downscaled image used for face detection.
  * - :ref:`faceDetectionModel<id3_face_portrait_processor_face_detection_model_class_member>`
    - :ref:`FaceModel<id3_face_face_model_enum>`
    - Specifies the model used to detect and track faces.
  * - :ref:`faceDetectionThreshold<id3_face_portrait_processor_face_detection_threshold_class_member>`
    - int
    - Specifies the face detection confidence threshold, in the range is [0;100].
  * - :ref:`faceEncodingModel<id3_face_portrait_processor_face_encoding_model_class_member>`
    - :ref:`FaceModel<id3_face_face_model_enum>`
    - Model used to create features and assess consistancy among views of a given face.
  * - :ref:`faceMaskThreshold<id3_face_portrait_processor_face_mask_threshold_class_member>`
    - int
    - Face mask detection threshold.
  * - :ref:`glassesThreshold<id3_face_portrait_processor_glasses_threshold_class_member>`
    - int
    - Glasses detection threshold.
  * - :ref:`hatThreshold<id3_face_portrait_processor_hat_threshold_class_member>`
    - int
    - Threshold for confirming that the person is wearing a hat.
  * - :ref:`makeupThreshold<id3_face_portrait_processor_makeup_threshold_class_member>`
    - int
    - Make-up detection threshold.
  * - :ref:`maleThreshold<id3_face_portrait_processor_male_threshold_class_member>`
    - int
    - Male gender detection threshold.
  * - :ref:`maximumEyeGazeX<id3_face_portrait_processor_maximum_eye_gaze_x_class_member>`
    - int
    - Maximum value of the eye gaze alongside the X axis.
  * - :ref:`maximumEyeGazeY<id3_face_portrait_processor_maximum_eye_gaze_y_class_member>`
    - int
    - Maximum value of the eye gaze alongside the Y axis.
  * - :ref:`maximumHeadHeightRatio<id3_face_portrait_processor_maximum_head_height_ratio_class_member>`
    - int
    - Maximum distance between the base of the chin and the crown is less than 80% of the total height of the image.
  * - :ref:`maximumHeadWidthRatio<id3_face_portrait_processor_maximum_head_width_ratio_class_member>`
    - int
    - Value indicating if the image width is conform to the (image width / head width) ratio of 7:5.
  * - :ref:`maximumHorizontalPosition<id3_face_portrait_processor_maximum_horizontal_position_class_member>`
    - int
    - Value indicating if the head is correctly centered horizontally.
  * - :ref:`maximumIod<id3_face_portrait_processor_maximum_iod_class_member>`
    - int
    - Maximum interocular distance (IOD), in pixels.
  * - :ref:`maximumPitchAngle<id3_face_portrait_processor_maximum_pitch_angle_class_member>`
    - float
    - Maximum head pitch angle, in degrees, for frontal positioning.
  * - :ref:`maximumRollAngle<id3_face_portrait_processor_maximum_roll_angle_class_member>`
    - float
    - Maximum head roll angle, in degrees, for frontal positioning.
  * - :ref:`maximumVerticalPosition<id3_face_portrait_processor_maximum_vertical_position_class_member>`
    - int
    - Maximum distance from the bottom edge of the image to the imaginary line passing through the center of the eyes is between 50% - 70% of the total vertical length of the image.
  * - :ref:`maximumYawAngle<id3_face_portrait_processor_maximum_yaw_angle_class_member>`
    - float
    - Maximum head yaw angle, in degrees, for frontal positioning.
  * - :ref:`minimumHeadHeightRatio<id3_face_portrait_processor_minimum_head_height_ratio_class_member>`
    - int
    - Minimum distance between the base of the chin and the crown is less than 80% of the total height of the image.
  * - :ref:`minimumHeadWidthRatio<id3_face_portrait_processor_minimum_head_width_ratio_class_member>`
    - int
    - Value indicating if the image width is conform to the (image width / head width) ratio of 7:5.
  * - :ref:`minimumHorizontalPosition<id3_face_portrait_processor_minimum_horizontal_position_class_member>`
    - int
    - Value indicating if the head is correctly centered horizontally.
  * - :ref:`minimumIod<id3_face_portrait_processor_minimum_iod_class_member>`
    - int
    - Minimum intra-occular distance, in pixels.
  * - :ref:`minimumVerticalPosition<id3_face_portrait_processor_minimum_vertical_position_class_member>`
    - int
    - Minimum distance from the bottom edge of the image to the imaginary line passing through the center of the eyes is between 50% - 70% of the total vertical length of the image.
  * - :ref:`mouthOcclusionThreshold<id3_face_portrait_processor_mouth_occlusion_threshold_class_member>`
    - int
    - Mouth occlusion threshold. 
  * - :ref:`mouthOpenThreshold<id3_face_portrait_processor_mouth_open_threshold_class_member>`
    - int
    - Mouth opening threshold.
  * - :ref:`naturalSkinColorThreshold<id3_face_portrait_processor_natural_skin_color_threshold_class_member>`
    - int
    - Natural skin color threshold.
  * - :ref:`noFlashReflectionThreshold<id3_face_portrait_processor_no_flash_reflection_threshold_class_member>`
    - int
    - Flash reflexion detection threshold.
  * - :ref:`noiseThreshold<id3_face_portrait_processor_noise_threshold_class_member>`
    - int
    - Threshold for confirming the presence of noise in the image.
  * - :ref:`noseOcclusionThreshold<id3_face_portrait_processor_nose_occlusion_threshold_class_member>`
    - int
    - Nose occlusion threshold. 
  * - :ref:`overExposureThreshold<id3_face_portrait_processor_over_exposure_threshold_class_member>`
    - int
    - Over exposure threshold.
  * - :ref:`padThreshold<id3_face_portrait_processor_pad_threshold_class_member>`
    - int
    - Presentation attack detection threshold, from 0 to 100.
  * - :ref:`pixelationThreshold<id3_face_portrait_processor_pixelation_threshold_class_member>`
    - int
    - Pixelation detection threshold.
  * - :ref:`redEyeThreshold<id3_face_portrait_processor_red_eye_threshold_class_member>`
    - int
    - Threshold for confirming the presence of red eyes.
  * - :ref:`resolutionThreshold<id3_face_portrait_processor_resolution_threshold_class_member>`
    - int
    - Threshold indicating whether the image resolution is sufficient.
  * - :ref:`sharpnessThreshold<id3_face_portrait_processor_sharpness_threshold_class_member>`
    - int
    - Sharpness threshold. 
  * - :ref:`smileThreshold<id3_face_portrait_processor_smile_threshold_class_member>`
    - int
    - Smile threshold.
  * - :ref:`threadCount<id3_face_portrait_processor_thread_count_class_member>`
    - int
    - Number of threads to be used for portrait processing.
  * - :ref:`tintedGlassThreshold<id3_face_portrait_processor_tinted_glass_threshold_class_member>`
    - int
    - Tinted glass detection threshold.
  * - :ref:`trackerMatchingThreshold<id3_face_portrait_processor_tracker_matching_threshold_class_member>`
    - int
    - Minimum match score to reach to preserve the ID of a tracked face between frame 't-1' and frame 't'.
  * - :ref:`trackerMaximumFaceAge<id3_face_portrait_processor_tracker_maximum_face_age_class_member>`
    - int
    - Maximum number of consecutive non-detections to be reached before deleting a tracked face.
  * - :ref:`trackerMinimumFaceAge<id3_face_portrait_processor_tracker_minimum_face_age_class_member>`
    - int
    - Minimum number of consecutive detections to reach before creating a tracked face.
  * - :ref:`trackerNmsIouThreshold<id3_face_portrait_processor_tracker_nms_iou_threshold_class_member>`
    - int
    - Non-maximum suppression (NMS) intersection-over-union (IOU) threshold, in the range [0;100].
  * - :ref:`underExposureThreshold<id3_face_portrait_processor_under_exposure_threshold_class_member>`
    - int
    - Under exposure threshold.

Methods
-------

.. list-table:: 
  :width: 100%
  :widths: 30 70
  :header-rows: 1

  * - Name
    - Description
  * - :ref:`createPortrait<id3_face_portrait_processor_create_portrait_class_method>`
    - Analyses an image and creates a portrait with the first detected face or the currently tracked face if the update parameter is activated.
  * - :ref:`cropIcaoPortrait<id3_face_portrait_processor_crop_icao_portrait_class_method>`
    - Creates an ICAO-compliant portrait image by cropping the source image around the detected face.
  * - :ref:`cropPortrait<id3_face_portrait_processor_crop_portrait_class_method>`
    - Creates a portrait image by cropping the source image around the detected face.
  * - :ref:`detectOcclusions<id3_face_portrait_processor_detect_occlusions_class_method>`
    - Detects occlusions on the subject's face.
  * - :ref:`detectPresentationAttack<id3_face_portrait_processor_detect_presentation_attack_class_method>`
    - Detects a possible presentation attack.
  * - :ref:`estimateAge<id3_face_portrait_processor_estimate_age_class_method>`
    - Estimates the age of the person.
  * - :ref:`estimateBackgroundUniformity<id3_face_portrait_processor_estimate_background_uniformity_class_method>`
    - Checks the background uniformity of the specified portrait.
  * - :ref:`estimateExpression<id3_face_portrait_processor_estimate_expression_class_method>`
    - Estimates the subject's expression on the specified portrait.
  * - :ref:`estimateFaceAttributes<id3_face_portrait_processor_estimate_face_attributes_class_method>`
    - Estimates the face attributes of the specified portrait.
  * - :ref:`estimateGeometryQuality<id3_face_portrait_processor_estimate_geometry_quality_class_method>`
    - Estimates the geometric quality of the specified portrait according to the ICAO portrait parameters.
  * - :ref:`estimatePhotographicQuality<id3_face_portrait_processor_estimate_photographic_quality_class_method>`
    - Etimates the photographic quality of the specified portrait.
  * - :ref:`removeBackground<id3_face_portrait_processor_remove_background_class_method>`
    - Removes the background on the specified portrait image.
  * - :ref:`reset<id3_face_portrait_processor_reset_class_method>`
    - Resets the face tracker.
  * - :ref:`updatePortrait<id3_face_portrait_processor_update_portrait_class_method>`
    - Analyses an image and updates the specified portrait with the first detected face or the currently tracked face.
