DOT iOS Palm library
v8.5.0
Introduction
DOT iOS Palm provides components for palm capture and related functionalities which are easy to integrate into an iOS application.
Requirements
Xcode 15.1+
iOS 12.0+
Swift or Objective-C
CocoaPods or Swift Package Manager
Distribution
Modularization
DOT iOS Palm is divided into core module and optional feature modules. This enables you to reduce the size of the library and include only modules that are actually used in your use case.
DOT iOS Palm is divided into following modules:
dot-palm-core
(Required) - provides API for all the features and functionalities.dot-palm-detection
(Optional) - enables the palm detection feature.
Each feature module can have other modules as their dependency and cannot be used without it, see the table below.
Module | Dependency |
|
|
Swift Package Manager
DOT iOS Palm can be easily integrated into Xcode project in: Project → Package Dependencies.
Use https://github.com/innovatrics/dot-ios-sdk-spm.git
repository and choose version you want to use. There you can select set of DotPalm*
packages you want to use. All the required dependencies will be downloaded with the selected package set.
Cocoapods
In order to integrate DOT iOS Palm into your project, the first step is to insert the following line of code on top of your Podfile
.
source 'https://github.com/innovatrics/innovatrics-podspecs'
Then, add the module(s) which you want to use to your Podfile
. All the required dependencies will be downloaded with the selected module(s).
source 'https://github.com/innovatrics/innovatrics-podspecs'
use_frameworks!
target 'YOUR_TARGET' do
pod 'dot-palm-detection'
end
In case of CocoaPods problem with
|
Supported Architectures
DOT iOS Palm provides all supported architectures in the distributed XCFramework package.
Device binary contains: arm64
.
Simulator binary contains: x86_64
, arm64
.
Licensing
In order to use DotSdk in your iOS application, it must be licensed. The license can be compiled into the application as it is bound to Bundle Identifier specified in the General tab in Xcode.
The Bundle ID can be also retrieved in runtime by calling DotSdk.shared.bundleId
.
In order to obtain the license, please contact your Innovatrics’ representative specifying Bundle ID. After you have obtained your license file, add it to your Xcode project and use it during the DotSdk initialization, as shown below.
Permissions
Set the following permission in Info.plist
:
<key>NSCameraUsageDescription</key>
<string>Your usage description</string>
Basic Setup
Initialization
Before using any of the components, you need to initialize DOT SDK with the license, DotPalmLibrary
object and list of feature modules you want to use. Each module can be accessed by its singleton *Module
class. DOT iOS Palm is distributed as a set of XCFramework packages. Each module is distributed as a single XCFramework package, see the table below.
Module | Class | XCFramework |
| DotPalmDetectionModule | DotPalmDetection.xcframework |
DOT SDK Sample shows how to initialize DOT SDK with DotPalmLibrary
. DotSdk.shared.initialize()
method should be called on background thread.
After you have successfully finished initialization, you can use all added features by importing only DotPalmCore
Swift module in your source files. Keep in mind that if you try to use any feature which was not added during initialization DOT SDK will generate fatal error.
Deinitialization
When you have finished using the DOT iOS Palm, it is usually a good practice to deinitialize it in order to free the memory. You can deinitialize DOT iOS Palm only after the complete process is finished and not within the life cycle of individual components. This can be performed using the DotSdk.shared.deinitialize()
method. If you want to use the DOT iOS Palm components again, you need to call DotSdk.shared.initialize()
again.
Logging
DOT iOS Palm supports logging using a global Logger
class. You can set the log level as follows:
import DotPalmCore
Logger.logLevel = .debug
Log levels:
debug
info
warning
error
none
Each log message contains DotPalm
tag. Keep in mind that logging should be used just for debugging purposes.
Components
Overview
DOT iOS Palm 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 Palm functionality. UI components are built 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
- PALM DETECTOR
A component for performing palm detection on an image.
- PALM AUTO CAPTURE CONTROLLER
A component for capturing good quality images of a human palm.
List of UI Components
- PALM AUTO CAPTURE
A visual component for capturing good quality images of a human palm.
Non-UI Components
Palm Detector
The PalmDetector
class provides a palm detection functionality. This component requires dot-palm-detection
module.
Create a PalmDetector
:
let palmDetector = PalmDetector()
To perform detection, call the following method on the background thread:
let palms = try palmDetector.detect(bgraRawImage: bgraRawImage, limit: 1)
Palm Auto Capture Controller
The PalmAutoCaptureController
class provides a stateful palm auto capture functionality. This component requires dot-palm-detection
module.
You can configure PalmAutoCaptureController
using PalmAutoCaptureController.Configuration
.
Create PalmAutoCaptureController
:
let configuration = try! PalmAutoCaptureController.Configuration(
validators: validators,
minValidFramesInRowToStartCandidateSelection: 2
candidateSelectionDurationMillis: 1000,
detectionNormalizedRectangle: detectionNormalizedRectangle)
let controller = PalmAutoCaptureController(configuration: configuration)
You can use detectionNormalizedRectangle
to specify the region in the input image which will be used for palm 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 palm detection.
To capture a good quality palm image, repeatedly call the process()
method using the camera frames:
let processingResult = try palmAutoCaptureController.process(bgraRawImage: bgraRawImage, timestampMillis: timestampMillis)
The controller evaluates the palm 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 palm image candidate is returned and the palm auto capture process is over.
UI Components
Camera handling
Camera lifecycle
DOT iOS Palm view controller will start the camera in viewWillAppear(:)
lifecycle method.
DOT iOS Palm view controller will stop the camera in viewDidDisappear(:)
lifecycle method.
Camera permission
DOT iOS Palm view controller will check the camera permission right before the camera is started. If the camera permission is granted the view controller will start the camera. If the camera permission is denied the view controller will call
*ViewControllerNoCameraPermission(:)
callback. Implement this callback in order to navigate the user further in your app workflow. If the camera permission is not determined the view controller will use iOS API -
AVCaptureDevice.requestAccess(for: .video) method to request the camera permission. This method will present the system
dialog to the user of the app. The user of the app can grant or deny the camera permission and then the view controller will proceed the same way as it does during the camera permission check as was explained at the beginning of this
section.
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 = PalmAutoCaptureViewController(configuration: .init(), style: .init())
viewController.delegate = self
navigationController?.pushViewController(viewController, animated: true)
To embed view controller into your view controller:
override func viewDidLoad() {
super.viewDidLoad()
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 Palm view controllers ignore safe area layout guide when they layout their subviews. Therefore, for example if you push DOT iOS Palm view controller using UINavigationController
, you will get incorrect layout. If you want to respect safe area layout guide, you should embed DOT iOS Palm view controller in a container view controller and setup the layout constraints accordingly.
Palm Auto Capture
The view controller with palm placeholder which is used for capturing palm images. This component requires dot-palm-detection
module.
You can configure PalmAutoCaptureViewController
using PalmAutoCaptureViewController.Configuration
.
You can customize the appearance of PalmAutoCaptureViewController
using PalmAutoCaptureViewController.Style
.
You can handle the PalmAutoCaptureViewController
events using its delegate PalmAutoCaptureViewControllerDelegate
.
To create PalmAutoCaptureViewController
:
let viewController = PalmAutoCaptureViewController(configuration: .init(), style: .init())
viewController.delegate = self
present(viewController, animated: true)
In order to start the palm auto capture process call the start()
method.
In case you want to handle detection data, implement palmAutoCaptureViewController(:processed:)
delegate callback. This callback is called with each processed camera frame. When the palm auto capture process finishes successfully, the result will be returned via the palmAutoCaptureViewController(:captured:)
callback.
In case you want to force the capture event, call the requestCapture()
method. The most recent image will be returned via the palmAutoCaptureViewController(:captured:)
callback asynchronously.
Call start()
method again in case you need to start over the palm auto capture process. You can also call start()
method to stop and start over ongoing process as well.
In case you want to stop the palm auto capture process prematurely, call the stopAsync()
method. The callback in the method argument indicates that the processing is over.
Quality Attributes of the Output Image
You may adjust quality requirements for the output image. To perform this, you can use pre-defined builders - QualityAttributeThresholds.Builder
- from QualityAttributeThresholdPresets
with recommended thresholds and pass it to PalmAutoCaptureViewController.Configuration
by setting the qualityAttributeThresholds
. You can also create your own instance of QualityAttributeThresholds
from scratch or based on pre-defined builders according to your needs.
Possible ways how to create QualityAttributeThresholds
:
// The standard preset
let standard = PalmAutoCaptureViewController.Configuration.QualityAttributeThresholdPresets.standard.build()
// Modified thresholds based on the standard preset
let modified = try PalmAutoCaptureViewController.Configuration.QualityAttributeThresholdPresets.standard
.minConfidence(minConfidence)
.minSharpness(nil)
.build()
// Custom thresholds
let custom = try PalmAutoCaptureViewController.Configuration.QualityAttributeThresholds.Builder()
.minConfidence(minConfidence)
.minSharpness(minSharpness)
.build()
Available presets (pre-defined builders with thresholds) in QualityAttributeThresholdPresets
:
standard
- The resulting image suitable for evaluation on Digital Identity Service. See the thresholds.
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 thisLocalizable.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 DotPalmCore
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 DotPalmCore
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
"dot_palm.palm_auto_capture.instruction.brightness_too_high" = "Less light needed";
"dot_palm.palm_auto_capture.instruction.brightness_too_low" = "More light needed";
"dot_palm.palm_auto_capture.instruction.palm_out_of_bounds" = "Center palm";
"dot_palm.palm_auto_capture.instruction.palm_not_detected" = "Scan palm";
"dot_palm.palm_auto_capture.instruction.size_too_small" = "Move closer";
"dot_palm.palm_auto_capture.instruction.size_too_large" = "Move back";
"dot_palm.palm_auto_capture.instruction.sharpness_too_low" = "More light needed";
"dot_palm.palm_auto_capture.instruction.candidate_selection" = "Hold still...";
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)
DetectionPosition
Class which represents a palm corners. To create an instance:
let detectionPosition = DetectionPosition(topLeft: topLeft, topRight: topRight, bottomRight: bottomRight, bottomLeft: bottomLeft)
Security guidelines
The effectiveness of our video injection prevention feature can be strengthened if the application that implements it includes security recommendations from Apple: App integrity. Which ensure its authenticity that it was downloaded only from the App Store and the transmission of its sensitive data cannot be modified.
OWASP Mobile Application Security
We also strongly recommend following the OWASP Mobile Application Security guidelines. The OWASP Mobile Application Security (MAS) flagship project provides a security standard for mobile apps (OWASP MASVS) and a comprehensive testing guide (OWASP MASTG) that covers the processes, techniques, and tools used during a mobile app security test, as well as an exhaustive set of test cases that enables testers to deliver consistent and complete results.
Appendix
Changelog
8.5.0 - 2024-10-24
First release