Skip to content
Haroldo Shigueaki Teruya edited this page Aug 5, 2021 · 4 revisions

This section describes the Perse SDK iOS API's, methods, your responses and possible errors.

Methods

The Perse is in alpha version and for now, only the Face module is available.

face.detect

  • Has the intent of detecting any number of human faces;
  • Can use this resource to evaluate the overall quality of the image;
  • The input can be the image file path or his Data;
  • The onSuccess return type is DetectResponse struct;
  • The onError return type can see in the Errors;
func detect(
    _ filePath: String,
    onSuccess: @escaping (DetectResponse) -> Void,
    onError: @escaping (String, String) -> Void
)
func detect(
    _ data: Data,
    onSuccess: @escaping (DetectResponse) -> Void,
    onError: @escaping (String, String) -> Void
)

face.compare

  • Accepts two sources for similarity comparison;
  • The inputs can be the image file paths or his Data's;
  • The onSuccess return type is CompareResponse struct;
  • The onError return type can see in the Errors;
func compare(
    _ firstFilePath: String,
    _ secondFilePath: String,
    onSuccess: @escaping (CompareResponse) -> Void,
    onError: @escaping (String, String) -> Void
)
func compare(
    _ firstFile: Data,
    _ secondFile: Data,
    onSuccess: @escaping (CompareResponse) -> Void,
    onError: @escaping (String, String) -> Void
)

Perse Camera

Variables
Variable Type Default Value Description
detectionTopSize Float '0.0f' Represents the percentage. Positive value enlarges and negative value reduce the top side of the detection. Use the setDetectionBox to have a visual result.
detectionRightSize Float '0.0f' Represents the percentage. Positive value enlarges and negative value reduce the right side of the detection. Use the setDetectionBox to have a visual result.
detectionBottomSize Float '0.0f' Represents the percentage. Positive value enlarges and negative value reduce the bottom side of the detection. Use the setDetectionBox to have a visual result.
detectionLeftSize Float '0.0f' Represents the percentage. Positive value enlarges and negative value reduce the left side of the detection. Use the setDetectionBox to have a visual result.
Methods
Function Parameters Valid values Return Type Description
startPreview - - void Start camera preview if has permission.
startCaptureType captureType: String
  • "none"
  • "face"
  • "qrcode"
  • "frame"
void Set capture type none, face, QR Code or frame.
stopCapture - - void Stop any type of capture.
destroy - - void Destroy camera preview.
toggleCameraLens - - void Toggle camera lens facing front/back.
setCameraLens cameraLens: String
  • "front"
  • "back"
void Set camera to use "front" or "back" lens. Default value is "front".
getCameraLens - - String Return "front" or "back".
setNumberOfImages numberOfImages: Int Any positive Int value void Default value is 0. For value 0 is saved infinity images. When saved images reached the "number os images", the onEndCapture is triggered.
setTimeBetweenImages timeBetweenImages: Int64 Any positive number that represent time in milli seconds void Set saving face/frame images time interval in milli seconds.
setOutputImageWidth width: Int Any positive number value that represents in pixels void Set face image width to be created in pixels.
setOutputImageHeight height: Int Any positive number value that represents in pixels void Set face image height to be created in pixels.
setSaveImageCaptured enable: Bool true or false void Set to enable/disable save image when capturing face and frame.
setDetectionBox enable: Bool true or false void Set to enable/disable detection box when face/qrcode detected. The detection box is the the face/qrcode bounding box normalized to UI.
setDetectionBoxColor alpha: Float, red: Float, green: Float, blue: Float Value between 0 and 1 void Set detection box ARGB color. Default value is (0.4, 1.0, 1.0, 1.0).
setDetectionMinSize minimumSize: Float Value between 0 and 1. Represents the percentage. void Set face/qrcode minimum size to detect in percentage related with the camera preview.
setDetectionMaxSize maximumSize: Float Value between 0 and 1. Represents the percentage. void Set face/qrcode maximum size to detect in percentage related with the camera preview.
setFaceContours enable: Bool true or false void Set to enable/disable face contours when face detected.
setFaceContoursColor alpha: Float, red: Float, green: Float, blue: Float Value between 0 and 1 void Set face contours ARGB color. Default value is (0.4, 1.0, 1.0, 1.0).
setROI enable: Bool true or false void Enable/disable the region of interest capture.
setROITopOffset topOffset: Float Value between 0 and 1. Represents the percentage. void Camera preview top distance in percentage.
setROIRightOffset rightOffset: Float Value between 0 and 1. Represents the percentage. void Camera preview right distance in percentage.
setROIBottomOffset bottomOffset: Float Value between 0 and 1. Represents the percentage. void Camera preview bottom distance in percentage.
setROILeftOffset leftOffset: Float Value between 0 and 1. Represents the percentage. void Camera preview left distance in percentage.
setROIAreaOffset enable: Bool true or false void Set to enable/disable region of interest offset visibility.
setROIAreaOffsetColor alpha: Float, red: Float, green: Float, blue: Float Value between 0 and 1 void Set face region of interest area offset color. Default value is (0.4, 1.0, 1.0, 1.0).
setTorch enable: Bool true or false void Set to enable/disable the device torch. Available only to camera lens "back".
PerseEventListener
Event Parameters Description
onImageCaptured type: String, count: Int, total: Int, imagePath: String, detectResponse: DetectResponse? Emitted when the image file is created:
  • count: current index
  • total: total to create
  • imagePath: the image path
  • detectResponse: Is the DetectResponse. Can be nil if not provided API Key.
    onFaceDetected x: Int, y: Int, width: Int, height: Int, leftEyeOpen: Bool, rightEyeOpen: Bool, smiling: Bool, headVerticalMovement: HeadMovement, headHorizontalMovement: HeadMovement, headTiltMovement: HeadMovement Emit the Head Movement.
    onFaceUndetected - Emitted after onFaceDetected, when there is no more face detecting.
    onEndCapture - Emitted when the number of image files created is equal of the number of images set (see the method setNumberOfImages).
    onQRCodeScanned content: String Must have started capture type of qrcode (see startCaptureType). Emitted when the camera scan a QR Code.
    onError error: String Emit message error.
    onMessage message: String Emit message.
    onPermissionDenied - Emit when try to startPreview but there is not camera permission.
    Head Movement

    The HeadMovement is the response send by the onFaceDetected. Represents the head movement:

    • Vertical;
    • Horizontal;
    • Tilt;

    Here we specify all the parameters:

    Attribute Description
    UNDEFINED Undefined head movement.
    VERTICAL_UP Head movement vertical is pointing up.
    VERTICAL_SUPER_UP Head movement vertical is pointing super up.
    VERTICAL_NORMAL Head movement vertical normal.
    VERTICAL_DOWN Head movement vertical is pointing down.
    VERTICAL_SUPER_DOWN Head movement vertical is pointing super up.
    HORIZONTAL_LEFT Head movement horizontal is pointing left.
    HORIZONTAL_SUPER_LEFT Head movement horizontal is pointing super left.
    HORIZONTAL_NORMAL Head movement horizontal normal.
    HORIZONTAL_RIGHT Head movement horizontal is pointing right.
    HORIZONTAL_SUPER_RIGHT Head movement horizontal is pointing super right.
    TILT_LEFT Head movement tilt is pointing left.
    TILT_SUPER_LEFT Head movement tilt is pointing super left.
    TILT_NORMAL Head movement tilt normal.
    TILT_RIGHT Head movement tilt is pointing right.
    TILT_SUPER_RIGHT Head movement tilt is pointing super right.

    Responses

    CompareResponse

    Attribute Type Description
    similarity Float Similarity between faces. Closer to 1 is better.
    timeTaken Float Time taken to analyze the image.
    defaultThresholds CompareThresholds Default threshold values for compare response.

    CompareThresholds

    Attribute Type Description
    similarity Float Default similarity threshold value.

    DetectResponse

    Attribute Type Description
    totalFaces Int Total of faces in the image.
    faces Array<FaceResponse> Array of FaceResponse.
    imageMetrics MetricsResponse Metrics of the detected image.
    timeTaken Float Time taken to analyze the image.
    defaultThresholds DetectThresholds Default threshold values for detect response.

    DetectThresholds

    Attribute Type Description
    underexposure Float Default loss of shadow threshold value.
    overexposure Float Default loss of highlight threshold value.
    sharpness Float Default intensity of motion blur threshold value.
    liveness Float Default confidence that a detected face is from a live person threshold value.

    FaceResponse

    Attribute Type Description
    landmarks LandmarksResponse Detected face landmarks.
    boundingBox Array<Int> Array with the four values of the face bounding box. The coordinates x, y and the dimension width and height respectively.
    faceMetrics MetricsResponse Metrics of the detecting face.
    livenessScore Long Confidence that a detected face is from a live person (1 means higher confidence).

    MetricsResponse

    Attribute Type Description
    underexposure Float Indicates loss of shadow detail. Closer to 0 is better.
    overexposure Float Indicates loss of highlight detail. Closer to 0 is better.
    sharpness Float Indicates intensity of motion blur. Closer to 1 is better.

    LandmarksResponse

    Attribute Type Description
    rightEye Array<Int> Right eye landmarks.
    leftEye Array<Int> Left eye landmarks.
    nose Array<Int> Nose landmarks.
    mouthRight Array<Int> Right side of mouth landmarks.
    mouthLeft Array<Int> Left side of mouth landmarks.

    Errors

    Error Code Description
    400 The request was unacceptable, often due to missing a required parameter.
    401 API key is missing or invalid.
    402 The parameters were valid but the request failed.
    415 The content type or encoding is not valid.