iOS Yoonit Camera

◻ Camera preview (Front & Back) ◻ Yoonit Facefy integration ◻ Face detection, capture and image crop ◻ Understanding of the human face ◻ Frame capture ◻ Capture timed images ◻ QR Code scanning

Sponsors

Platinum

Become a sponsor!

Table of Contents

• Installation
• Usage
  • Camera Preview
  • Start capturing face images
  • Start scanning QR Codes
• API
  • Variables
  • Methods
  • Events
    • Face Analysis
    • Head Movements
    • Image Quality
  • KeyError
  • Message
• To contribute and make it better

Installation

Add the following line to your Podfile file:

pod 'YoonitCamera'

And run in the root of your project:

pod install

Usage

All the functionalities that the ios-yoonit-camera provides is accessed through the CameraView, that includes the camera preview. See an example how we use in our Demo.

Below we have the basic usage code, for more details, see the API section.

Camera Preview

@IBOutlet var cameraView: CameraView!

Do not forget request camera permission. Start camera preview:

self.cameraView.startPreview()

Start capturing face images

With camera preview, we can start capture detected face and generate images:

self.cameraView.startCaptureType("face")

Set camera event listener to get the result:

class YourViewController: UIViewController, CameraEventListenerDelegate {
    ...
    self.cameraView.cameraEventListener = self
    ...
    func onImageCaptured(
        _ type: String, 
        _ count: Int, 
        _ total: Int, 
        _ imagePath: String,
        _ darkness: NSNumber?,
        _ lightness: NSNumber?,
        _ sharpness: NSNumber?
    ) {
        // YOUR CODE
    }
    
    func onFaceDetected(
        _ x: Int, 
        _ y: Int, 
        _ width: Int, 
        _ height: Int, 
        _ leftEyeOpenProbability: NSNumber?, 
        _ rightEyeOpenProbability: NSNumber?, 
        _ smilingProbability: NSNumber?, 
        _ headEulerAngleX: NSNumber?, 
        _ headEulerAngleY: NSNumber?, 
        _ headEulerAngleZ: NSNumber?
    ) {
        // YOUR CODE
    }
    ...
}

Start scanning QR Codes

With camera preview, we can start scanning QR codes:

self.cameraView.startCaptureType("qrcode")

Set camera event listener to get the result:

class YourViewController: UIViewController, CameraEventListenerDelegate {
    ...
    self.cameraView.cameraEventListener = self
    ...
    func onQRCodeScanned(content: String) {
        // YOUR CODE
    }
}

API

Variables

Variable	Type	Default Value	Description
detectionTopSize	Float	'0.0'	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.0'	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.0'	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.0'	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".

Events

Event	Parameters	Description
onImageCaptured	type: String, count: Int, total: Int, imagePath: String, darkness: NSNumber?, lightness: NSNumber?, sharpness: NSNumber?	Must have started capture type of face/frame (see startCaptureType). Emitted when the image file is created: type: '"face"' or '"frame"' count: current index total: total to create imagePath: the image path inferences: each array element is the image inference result. darkness: image darkness classification. lightness: image lightness classification. sharpness: image sharpness classification.
onFaceDetected	x: Int, y: Int, width: Int, height: Int, leftEyeOpenProbability: NSNumber?, rightEyeOpenProbability: NSNumber?, smilingProbability: NSNumber?, headEulerAngleX: NSNumber?, headEulerAngleY: NSNumber?, headEulerAngleZ: NSNumber?	Must have started capture type of face. Emit the face analysis
onFaceUndetected	-	Must have started capture type of face. Emitted after onFaceDetected, when there is no more face detecting.
onEndCapture	-	Must have started capture type of face/frame. 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.

Face Analysis

The face analysis is the response send by the onFaceDetected. Here we specify all the parameters.

Attribute	Type	Description
x	Int	The x position of the face in the screen.
y	Int	The y position of the face in the screen.
width	Int	The width position of the face in the screen.
height	Int	The height position of the face in the screen.
leftEyeOpenProbability	NSNumber?	The left eye open probability.
rightEyeOpenProbability	NSNumber?	The right eye open probability.
smilingProbability	NSNumber?	The smiling probability.
headEulerAngleX	NSNumber?	The angle in degrees that indicate the vertical head direction. See Head Movements
headEulerAngleY	NSNumber?	The angle in degrees that indicate the horizontal head direction. See Head Movements
headEulerAngleZ	NSNumber?	The angle in degrees that indicate the tilt head direction. See Head Movements

Head Movements

Here we explaining the above gif and how reached the "results". Each "movement" (vertical, horizontal and tilt) is a state, based in the angle in degrees that indicate head direction;

Head Direction	Attribute	v < -36°	-36° < v < -12°	-12° < v < 12°	12° < v < 36°	36° < v
Vertical	headEulerAngleX	Super Down	Down	Frontal	Up	Super Up
Horizontal	headEulerAngleY	Super Left	Left	Frontal	Right	Super Right
Tilt	headEulerAngleZ	Super Right	Right	Frontal	Left	Super Left

Image Quality

The image quality is the classification of the three attributes: darkness, lightness and sharpness. Result available in the onImageCaptured event. Let's see each parameter specifications:

Threshold	Classification
Darkness
darkness > 0.7	Too dark
darkness <= 0.7	Acceptable
Lightness
lightness > 0.65	Too light
lightness <= 0.65	Acceptable
Sharpness
sharpness >= 0.1591	Blurred
sharpness < 0.1591	Acceptable

KeyError

Pre-define key error used by the onError event.

KeyError	Description
INVALID_CAPTURE_TYPE	Tried to start a non-existent capture type.
INVALID_CAMERA_LENS	Tried to input invalid camera lens.
INVALID_NUMBER_OF_IMAGES	Tried to input invalid face/frame number of images to capture.
INVALID_TIME_BETWEEN_IMAGES	Tried to input invalid face time interval to capture face.
INVALID_OUTPUT_IMAGE_WIDTH	Tried to input invalid image width.
INVALID_OUTPUT_IMAGE_HEIGHT	Tried to input invalid image height.
INVALID_DETECTION_BOX_COLOR	Tried to input invalid detection box ARGB value color.
INVALID_MINIMUM_SIZE	Tried to input invalid minimum size.
INVALID_MAXIMUM_SIZE	Tried to input invalid maximum size.
INVALID_ROI_TOP_OFFSET	Tried to input invalid region of interest top offset.
INVALID_ROI_RIGHT_OFFSET	Tried to input invalid region of interest right offset.
INVALID_ROI_BOTTOM_OFFSET	Tried to input invalid region of interest bottom offset.
INVALID_ROI_LEFT_OFFSET	Tried to input invalid region of interest left offset.
INVALID_ROI_COLOR	Tried to input invalid region of interest area offset ARGB value color.
INVALID_FACE_CONTOURS_COLOR	Tried to input invalid face contour ARGB value color.

Message

Pre-define key messages used by the onMessage event.

Message	Description
INVALID_MINIMUM_SIZE	Face/QRCode width percentage in relation of the screen width is less than the set (setDetectionMinSize).
INVALID_MAXIMUM_SIZE	Face/QRCode width percentage in relation of the screen width is more than the set (setDetectionMaxSize).
INVALID_OUT_OF_ROI	Face bounding box is out of the set region of interest (setROI).
INVALID_TORCH_LENS_USAGE	Torch not available with camera lens "front" (setTorch).

To contribute and make it better

Clone the repo, change what you want and send PR. For commit messages we use Conventional Commits.

Contributions are always welcome!

---

Code with ❤ by the Yoonit Team