4. API

This section describes the Perse SDK Android 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 ByteArray;
• The onSuccess return type is DetectResponse model;
• The onError return type can see in the Errors;

fun detect(
    imagePath: String,
    onSuccess: (DetectResponse) -> Unit,
    onError: (String, String) -> Unit
)

fun detect(
    imageFile: ByteArray,
    onSuccess: (DetectResponse) -> Unit,
    onError: (String, String) -> Unit
)

face.compare

• Accepts two sources for similarity comparison;
• The inputs can be the image file paths or his ByteArray;
• The onSuccess return type is CompareResponse model;
• The onError return type can see in the Errors;

fun compare(
    imageFile: String,
    imageFile: String,
    onSuccess: (CompareResponse) -> Unit,
    onError: (String, String) -> Unit
)

fun compare(
    imagePath: ByteArray,
    imagePath: ByteArray,
    onSuccess: (CompareResponse) -> Unit,
    onError: (String, String) -> Unit
)

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	Set camera lens facing front or back.
setCameraLens	cameraLens: String	"front" "back"	void	Set camera to use "front" or "back" lens. Default value is "front".
getCameraLens	-	-	Int	Return Int that represents lens face state: 0 for front 1 for back camera.
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: Long	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: Boolean	true or false.	void	Set to enable/disable save image when capturing face and frame.
setDetectionBox	enable: Boolean	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: Int, red: Int, green: Int, blue: Int	Value between 0 and 1.	void	Set detection box ARGB color. Default value is (100, 255, 255, 255).
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: Boolean	true or false.	void	Set to enable/disable face contours when face detected.
setFaceContoursColor	alpha: Int, red: Int, green: Int, blue: Int	Positive value between 0 and 255.	void	Set face contours ARGB color. Default value is (100, 255, 255, 255).
setROI	enable: Boolean	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: Boolean	true or false.	void	Set to enable/disable region of interest offset visibility.
setROIAreaOffsetColor	alpha: Int, red: Int, green: Int, blue: Int	Any positive integer between 0 and 255.	void	Set face region of interest area offset color. Default value is (100, 255, 255, 255).
setBlurFaceDetectionBox	enable: Boolean	true or false.	void	Enable/disable blur in face detection box.
setColorEncodingCapture	colorEncoding: String	"RGB" "YUV"	void	Set the color encoding for the saved images.
setComputerVision	enable: Boolean	true or false.	void	Enable/disable computer vision usage.
setComputerVisionLoadModels	modelPaths: ArrayList<String>	Must exist all model files paths.	void	Set the computer vision model files paths to load.
computerVisionClearModels	-	-	void	Clear loaded computer vision models.
setTorch	enable: Boolean	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	Long	Similarity between faces. Closer to 1 is better.
timeTaken	Long	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	List<FaceResponse>	List of FaceResponse.
imageMetrics	MetricsResponse	Metrics of the detected image.
timeTaken	Long	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	List<Int>	List 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	Long	Indicates loss of shadow detail. Closer to 0 is better.
overexposure	Long	Indicates loss of highlight detail. Closer to 0 is better.
sharpness	Long	Indicates intensity of motion blur. Closer to 1 is better.

LandmarksResponse

Attribute	Type	Description
rightEye	List<Int>	Right eye landmarks.
leftEye	List<Int>	Left eye landmarks.
nose	List<Int>	Nose landmarks.
mouthRight	List<Int>	Right side of mouth landmarks.
mouthLeft	List<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.