DOT iOS Face Lite library

v5.2.0

Introduction

DOT iOS Face Lite provides components for face capture and related functionalities which are easy to integrate into an iOS application.

Requirements

Xcode 14+
iOS 11.0+
Swift or Objective-C
CocoaPods or Swift Package Manager

DOT iOS Face Lite is distributed as a binary XCFramework - DotFaceLite.xcframework with its dependencies stored in our public github repository. It can be easily integrated into Xcode project in: Project → Package Dependencies.

Use https://github.com/innovatrics/dot-ios-sdk-spm.git repository and choose the version you want to use. There you can select DotFaceLite package. All the required dependencies will be downloaded with the selected package.

Cocoapods

DOT iOS Face Lite is distributed as a XCFramework - DotFaceLite.xcframework using Cocoapods with its dependencies stored in our public github repository. It can be easily integrated into Xcode with custom definition of podspecs. First step is to insert following line of code on top of you Podfile.

Podfile

source 'https://github.com/innovatrics/innovatrics-podspecs'

Then DOT iOS Face Lite dependency must be specified in Podfile. Dependencies of DOT iOS Face Lite will be downloaded alongside it.

Podfile

source 'https://github.com/innovatrics/innovatrics-podspecs'

use_frameworks!

target 'YOUR_TARGET' do

pod 'dot-face-lite'

end

In case of CocoaPods problem with pod install, try to clone the private pod repository manually.

pod repo remove innovatrics
pod repo add innovatrics https://github.com/innovatrics/innovatrics-podspecs

Supported Architectures

DOT iOS Face Lite provides all supported architectures in the distributed XCFramework package. Device binary contains: arm64. Simulator binary contains: x86_64, arm64.

Permissions

Set the following permission in Info.plist:

Info.plist

<key>NSCameraUsageDescription</key>
	<string>Your usage description</string>

Basic Setup

Logging

DOT iOS Face Lite supports logging using a global Logger class. You can set the log level as follows:

import DotFaceLite

Logger.logLevel = .debug

Log levels:

info
debug
warning
error
none

Each log message contains dot-face-lite tag. Keep in mind that logging should be used just for debugging purposes.

Components

Overview

DOT iOS Face Lite provides both non-UI and UI components. Non-UI components are aimed to be used by developers who want to build their own UI using the DOT iOS Face Lite functionality. UI components are build on top of non-UI components. Components having UI are available as UIViewController classes and can be embedded into the application’s existing UI or presented using the standard methods.

List of Non-UI Components

FACE DETECTOR: A component for performing face detection on an image.
FACE AUTO CAPTURE CONTROLLER: A component for capturing good quality image of human face.

List of UI Components

FACE AUTO CAPTURE: A visual component for capturing good quality image of human face.

Non-UI Components

Face Detector

The FaceDetector class provides a face detection functionality.

Create a FaceDetector:

let faceDetector = FaceDetector()

To perform detection, call the following method on the background thread:

let result = try? faceDetector.detect(bgraRawImage: bgraRawImage)

Face Auto Capture Controller

The FaceAutoCaptureController class provides a stateful face auto capture functionality.

Create FaceAutoCaptureController:

let configuration = try! FaceAutoCaptureControllerConfiguration(
            minValidFramesInRowToStartCandidateSelection: 2
            candidateSelectionDurationMillis: 1000,
            detectionNormalizedRectangle: detectionNormalizedRectangle,
            validators: validators)
let controller = FaceAutoCaptureController(configuration: configuration)

FaceAutoCaptureControllerConfiguration

(Required) [-] validators: [FaceAutoCaptureDetectionValidator] - Array of validators which will be used to validate input image.
(Optional) [2] minValidFramesInRowToStartCandidateSelection: Int - Minimum number of valid frames in a row to start candidate selection.
(Optional) [1000] candidateSelectionDurationMillis: Int - Duration of candidate selection phase.
(Optional) [-] detectionNormalizedRectangle: RectangleDouble - Crop an input image to normalized detection rectangle and use that for face detection.

You can use detectionNormalizedRectangle to specify the region in the input image which will be used for face detection. For example, if you want to ignore top 30% and bottom 30% of the input image, you can do it as follows:

let detectionNormalizedRectangle = RectangleDouble(left: 0, top: 0.3, right: 1.0, bottom: 0.7)

If detectionNormalizedRectangle is set to nil(default) the full input image is used for face detection.

To capture a good quality face image, repeatedly call the process() method using the camera frames:

faceAutoCaptureController.process(bgraRawImage: bgraRawImage, timestampMillis: timestampMillis)

The controller evaluates the face image requirements for each frame. Once the controller detects enough (minValidFramesInRowToStartCandidateSelection) valid frames in a row, candidate selection is started with duration of candidateSelectionDurationMillis milliseconds. After the candidate selection is finished, the best face image candidate is returned by the delegate and the face auto capture process is over.

In case you want to force the capture event, call the requestCapture() method. After you call the next process() method, the input image will be returned as a result by the delegate and the face auto capture process will be finished.

faceAutoCaptureController.requestCapture();

In case you want to restart the face auto capture process, call the restart() method.

faceAutoCaptureController.restart();

UI Components

View Controller Configuration

Components containing UI are embedded into the application as view controllers. All view controllers can be embedded into your own view controller or presented directly. Each view controller can be configured using its *Configuration class and each view controller can have its appearance customized using its *Style class.

To present view controller:

let viewController = FaceAutoCaptureViewController.create(configuration: .init(), style: .init())
viewController.delegate = self
self.present(viewController, animated: true, completion: nil)

To embed view controller into your view controller:

override func viewDidLoad() {
    super.viewDidLoad()

    let viewController = FaceAutoCaptureViewController.create(configuration: .init(), style: .init())
    addChild(viewController)
    view.addSubview(viewController.view)
    viewController.view.translatesAutoresizingMaskIntoConstraints = false
    viewController.didMove(toParent: self)

    NSLayoutConstraint.activate([
        viewController.view.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
        viewController.view.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
        viewController.view.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor),
        viewController.view.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor)
    ])
}

Safe Area

DOT iOS Face Lite view controllers ignore safe area layout guide when they layout their subviews. Therefore, for example if you push DOT iOS Face Lite view controller using UINavigationController, you will get incorrect layout. If you want to respect safe area layout guide, you should embed DOT iOS Face Lite view controller in a container view controller and setup the layout constraints accordingly.

Face Auto Capture

The view controller with instructions for obtaining quality face images suitable for matching.

You can configure FaceAutoCaptureViewController using FaceAutoCaptureConfiguration. You can customize the appearance of FaceAutoCaptureViewController ` using `FaceAutoCaptureStyle. You can handle the FaceAutoCaptureViewController ` events using its delegate `FaceAutoCaptureViewControllerDelegate.

To create FaceAutoCaptureViewController:

let viewController = FaceAutoCaptureViewController.create(configuration: .init(), style: .init())
viewController.delegate = self
self.present(viewController, animated: true, completion: nil)

To start the face auto capture process call the start() method. You can start the process any time.

In case you want to handle detection data, implement faceAutoCaptureViewController(:processed:) delegate callback. This callback is called with each processed camera frame. The faceAutoCaptureViewControllerCandidateSelectionStarted(:) delegate callback is called only once during the whole process, when candidate selection is started. When the face auto capture process finishes successfully, the result will be returned via the faceAutoCaptureViewController(:captured:) callback.

In case you want to force the capture event, call the requestCapture() method. The most recent image will be returned via the faceAutoCaptureViewController(:captured:) callback asynchronously.

Call restart() method in order to start over the face auto capture process. You can also call restart() method to stop and start over ongoing process.

In case you want to stop the face auto capture process prematurely, call the stopAsync() method. The faceAutoCaptureViewControllerStopped(:) callback indicates that the processing is over.

Customization of UI Components

Localization

String resources can be overridden in your application and alternative strings for supported languages can be provided following these two steps:

Add your own Localizable.strings file to your project using standard iOS localization mechanism. To change a specific text override corresponding key in this Localizable.strings file.
Set the localization bundle to the bundle of your application (preferably during the application launch in your AppDelegate).

Use this setup if you want to use standard iOS localization mechanism, which means your iOS application uses system defined locale.

import DotFaceLite

Localization.bundle = .main

Custom Localization

You can override standard iOS localization mechanism by providing your own translation dictionary and setting the Localization.useLocalizationDictionary flag to true. Use this setup if you do not want to use standard iOS localization mechanism, which means your iOS application ignores system defined locale and uses its own custom locale.

import DotFaceLite

guard let localizableUrl = Bundle.main.url(forResource: "Localizable", withExtension: "strings", subdirectory: nil, localization: "de"),
      let dictionary = NSDictionary(contentsOf: localizableUrl) as? [String: String]
else { return }

Localization.useLocalizationDictionary = true
Localization.localizationDictionary = dictionary

Localizable.strings

"dot.face_lite_auto_capture.instruction.candidate_selection" = "Stay still...";
"dot.face_lite_auto_capture.instruction.face_centering" = "Center your face";
"dot.face_lite_auto_capture.instruction.face_not_present" = "Position your face into the circle";
"dot.face_lite_auto_capture.instruction.face_too_far" = "Move closer";
"dot.face_lite_auto_capture.instruction.face_too_close" = "Move back";
"dot.face_lite_auto_capture.instruction.lighting" = "Turn towards light";

Common Classes

`ImageSize`

Class which represents a size of an image. To create an instance:

let imageSize = ImageSize(width: 100, height: 100)

`BgraRawImage`

Class which represents an image.

To create an instance from CGImage:

let bgraRawImage = BgraRawImageFactory.create(cgImage: cgImage)

To create an instance from CIImage:

let bgraRawImage = BgraRawImageFactory.create(ciImage: ciImage, ciContext: ciContext)

To create CGImage from BgraRawImage:

let cgImage = CGImageFactory.create(bgraRawImage: bgraRawImage)

To create CIImage from BgraRawImage:

let ciImage = CIImageFactory.create(bgraRawImage: bgraRawImage, ciContext: ciContext)

Technical release. No changes.

5.1.1 - 2023-02-21

Added

support for Swift Package Manager

5.1.0 - 2023-02-08

Added

shared dependency DotCore
shared dependency DotCamera

Changed

types moved to DotCore: BgraRawImage, BgraRawImageFactory, CGImageFactory, CIImageFactory, ImageSize, RectangleDouble, PointDouble, IntervalFloat, IntervalDouble
types moved to DotCamera: CameraFacing, CameraPreviewScaleType

5.0.0 - 2023-01-27

Changed

New SDK versioning: All libraries (DOT Document, DOT Face, DOT Face Lite and DOT NFC) are released simultaneously with a single version name. Libraries with the same version name work correctly at build time and at run time.
text of localization key dot.face_lite_auto_capture.instruction.face_not_present to Position your face into the circle
all UI components will return images with aspect ratio 4:3

Fixed

maximal resolution of images returned from all UI components was too high
@objc prefix pattern to DOTFL*

1.1.2 - 2022-10-24

Fixed

verification of validator dependencies

Changed

minimal required version to Xcode 14+

Added

FaceAutoCaptureDetectionValidator.dependencyIdentifiers

Changed

FaceAutoCaptureControllerConfiguration.init() throws
SizeTooSmallValidator and SizeTooLargeValidator threshold interval from [0,1] to [0,inf]
FaceAutoCaptureConfiguration.sizeInterval from [0,1] to [0,inf]

1.1.1 - 2022-08-15

Fixed

crash when camera device is not available
camera session lifecycle
camera permission issue

1.1.0 - 2022-07-11

Fixed

camera permission issue

Added

DotFaceLiteLibrary.versionName

1.0.0 - 2022-05-19

First release

DOT iOS Face Lite library

v5.2.0#

v5.2.0