Start using packagecloud in minutes
Join thousands of developers using packagecloud to distribute software securely, consistently, and affordably.
README
last updated: Fri 09/13/24 at 06:41:03 PM bylucas-yupistudios
BioPass ID Face Capture SDK
Latest Version
September 13, 2024 - [v1.0.5]
Table of Contents
Quick Start Guide
First, you will need a license key to use the SDK. To get your license key contact us through our website BioPass ID.
Check out our official documentation for more in depth information on BioPass ID.
1. Prerequisites
- iOS version: 14.0 or higher
- Swift: 5.0.0
- CocoaPods
- Info.plist
Add two rows to the ios/Info.plist:
- one with the key Privacy - Camera Usage Description and a usage description.
- and one with the key Privacy - Photo Library Usage Description and a usage description.
Or in text format add the key:
<key>NSCameraUsageDescription</key>
<string>Your camera usage description</string>
Privacy Manifest File.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>NSPrivacyCollectedDataTypes</key>
<array>
<dict>
<key>NSPrivacyCollectedDataType</key>
<string>NSPrivacyCollectedDataTypeOtherUserContent</string>
<key>NSPrivacyCollectedDataTypeLinked</key>
<false/>
<key>NSPrivacyCollectedDataTypeTracking</key>
<false/>
<key>NSPrivacyCollectedDataTypePurposes</key>
<array>
<string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
</array>
</dict>
<dict>
<key>NSPrivacyCollectedDataType</key>
<string>NSPrivacyCollectedDataTypeDeviceID</string>
<key>NSPrivacyCollectedDataTypeLinked</key>
<false/>
<key>NSPrivacyCollectedDataTypeTracking</key>
<false/>
<key>NSPrivacyCollectedDataTypePurposes</key>
<array>
<string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
</array>
</dict>
</array>
<key>NSPrivacyTracking</key>
<false/>
<key>NSPrivacyAccessedAPITypes</key>
<array>
<dict>
<key>NSPrivacyAccessedAPITypeReasons</key>
<array>
<string>CA92.1</string>
</array>
<key>NSPrivacyAccessedAPIType</key>
<string>NSPrivacyAccessedAPICategoryUserDefaults</string>
</dict>
</array>
</dict>
</plist>
2. Installation
With XCFramework Folder
Here you can find the latest releases. Download BioPassID.zip and unzip, then add the .xcframework folder to your project.
- Select your target;
- Click in the general tab;
- Go to the Frameworks, libraries and embedded content group;
- Drag and drop the xcframework folder to add to your project.
<!--
With Swift Package Manager
Clone the Package repository:
git clone https://github.com/yupistudios/BioPassID-swift-package
- Go to the XCode project;
- Access the menu File > Add Packages;
- In the window click in the button Add Local... and select the folder;
- Select your target;
- Click in the general tab;
- Go to the Frameworks, libraries and embedded content group;
- Click in the plus button;
- Select the BioPassID library and click the Add button.
-->
3. How to use
In SwiftUI
To call faceliveness inside a SwiftUI View is as easy as follow:
import faceliveness
import SwiftUI
@main
struct MyApp: App
// instantiate the FaceConfig
var config: FaceLivenessConfig!
@State var imageFace: UIImage? = nil
@State var isPresented = false
init()
config = FaceLivenessConfig()
// set your license key
config.licenseKey = "your-license-key"
// you can define a custom Callback to receive the Face image
func setImage(face: UIImage)
print("Face: ", face)
imageFace = face
func setAtributes(atributes: LivenessFaceAttributes)
print("atributes :", atributes.rollAngle)
print("atributes :", atributes.pitchAngle)
print("atributes :", atributes.yawAngle)
var body: some Scene
WindowGroup
NavigationView
VStack
Text("BioPass ID Face Liveness SDK")
.frame(maxHeight: .infinity, alignment: .top)
if (imageFace != nil)
Image(uiImage: self.imageFace!)
.resizable()
.frame(width: 400, height: 400)
Button
isPresented = true
label:
Text("Open Face Liveness")
.fullScreenCover(isPresented: $isPresented)
FaceLivenessView(with: config, onFaceCapture: image, atributes in
if image != nil
setImage(face: image)
setAtributes(atributes: atributes)
, onFaceDetected: atributes in
if(atributes != nil)
setAtributes(atributes: atributes)
, debug: false
)
.frame(maxHeight: .infinity, alignment: .top)
In UIKit
Example as a Fullscreen Modal:
import faceliveness
class MyAppViewController: UIViewController
private var faceLiveness: FaceLivenessView!
private var config: FaceLivenessConfig!
var licenseKey = "your-license-key"
override func viewDidLoad()
super.viewDidLoad()
config = FaceLivenessConfig()
//MARK: Configs iniciais
config.licenseKey = "your-license-key"
faceLiveness = FaceLivenessView(with: config, onFaceCapture: image, atributes in
if image != nil
self.handleCallback(image: image, atributes: atributes)
, onFaceDetected: atributes in
self.handleCallbackAtributes(atributes: atributes)
, debug: false
)
let contentView = UIHostingController(rootView: faceLiveness!)
addChild(contentView)
view.addSubview(contentView.view)
setupConstraints(contentView: contentView)
func handleCallback(image: UIImage, atributes: LivenessFaceAttributes)
print("App callback")
print("LIVENESS_LOG: print UIImage")
print(image)
print(atributes)
func handleCallbackAtributes( atributes: LivenessFaceAttributes)
print("App callback")
print("LIVENESS_LOG: print Atributes")
print(atributes)
Example as a SubView:
import faceliveness
class SecondViewController: UIViewController
private var faceLiveness: FaceLivenessView!
private var config: FaceLivenessConfig!
var licenseKey = ""
override func viewDidLoad()
super.viewDidLoad()
config = FaceLivenessConfig()
//MARK: Configs iniciais
config.licenseKey = "your-license-key"
faceLiveness = FaceLivenessView(with: config, onFaceCapture: image, atributes in
if image != nil
self.handleCallback(image: image, atributes: atributes)
, onFaceDetected: atributes in
self.handleCallbackAtributes(atributes: atributes)
, debug : false
)
let contentView = UIHostingController(rootView: faceLiveness!)
addChild(contentView)
view.addSubview(contentView.view)
setupConstraints(contentView: contentView)
(...)
func setupConstraints(contentView: UIHostingController<FaceLivenessView>)
contentView.view.translatesAutoresizingMaskIntoConstraints = false
contentView.view.topAnchor.constraint(equalTo: view.topAnchor).isActive = true
contentView.view.bottomAnchor.constraint(equalTo: view.bottomAnchor).isActive = true
contentView.view.leftAnchor.constraint(equalTo: view.leftAnchor).isActive = true
contentView.view?.rightAnchor.constraint(equalTo: view.rightAnchor).isActive = true
4. LicenseKey
First, you will need a license key to use the SDK. To get your license key contact us through our website BioPass ID.
To use Face Liveness SDK you need a license key. To set the license key needed is simple as setting another attribute. Simply doing:
var config = FaceLivenessConfig()
config.licenseKey = "your-license-key"
LivenessFaceAttributes
| Name | Type | Description |
| ----------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| faceProp | Float | Proportion of the area occupied by the face in the image, in percentage |
| faceWidth | Int | Face width, in pixels |
| faceHeight | Int | Face height, in pixels |
| ied | Int | Distance between left eye and right eye, in pixels |
| bbox | CGRect | Face bounding box |
| rollAngle | Float | The Euler angle X of the head. Indicates the rotation of the face about the axis pointing out of the image. Positive z euler angle is a counter-clockwise rotation within the image plane |
| pitchAngle | Float | The Euler angle X of the head. Indicates the rotation of the face about the horizontal axis of the image. Positive x euler angle is when the face is turned upward in the image that is being processed |
| yawAngle | Float | The Euler angle Y of the head. Indicates the rotation of the face about the vertical axis of the image. Positive y euler angle is when the face is turned towards the right side of the image that is being processed |
| averageLightIntensity | Float | The average intensity of the pixels in the image |
FaceLivenessConfig
You can also use pre-build configurations on your application, so you can automatically start using multiples features that better suit your application. You can instantiate each one and use it's default properties, or if you prefer you can change every config available. Here are the types that are supported right now:
FaceLivenessConfig
| Name | Type | Default value |
| ------------------ | ------------------------------- | ----------------------------- |
| licenseKey | String | "" |
| resolutionPreset | FaceResolutionPreset | FaceResolutionPreset.MEDIUM |
| fontFamily | String | facesdk_opensans_bold |
| faceDetection | FaceLivenessDetectionOptions | |
| mask | FaceLivenessMaskOptions | |
| titleText | FaceLivenessTextOptions | |
| loadingText | FaceLivenessTextOptions | |
| helpText | FaceLivenessTextOptions | |
| feedbackText | FaceLivenessFeedbackTextOptions | |
| backButton | FaceLivenessButtonOptions | |
FaceLivenessDetectionOptions
| Name | Type | Default value | Description |
| ------------------------ | ----- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| timeToCapture | Int | 3000 | Time it takes to perform an automatic capture, in miliseconds |
| maxFaceDetectionTime | Int | 60000 | Maximum facial detection attempt time, in miliseconds |
| minFaceProp | Float | 0.1 | Minimum limit of the proportion of the area occupied by the face in the image, in percentage |
| maxFaceProp | Float | 0.4 | Maximum limit on the proportion of the area occupied by the face in the image, in percentage |
| minFaceWidth | Int | 150 | Minimum face width, in pixels |
| minFaceHeight | Int | 150 | Minimum face height, in pixels |
| ied | Int | 90 | Minimum distance between left eye and right eye, in pixels |
| bboxPad | Int | 20 | Padding the face's bounding box to the edges of the image, in pixels |
| faceDetectionThresh | Float | 0.5 | Minimum trust score for a detection to be considered valid. Must be a number between 0 and 1, which 0.1 would be a lower face detection trust level and 0.9 would be a higher trust level |
| rollThresh | Float | 4.0 | The Euler angle X of the head. Indicates the rotation of the face about the axis pointing out of the image. Positive z euler angle is a counter-clockwise rotation within the image plane |
| pitchThresh | Float | 4.0 | The Euler angle X of the head. Indicates the rotation of the face about the horizontal axis of the image. Positive x euler angle is when the face is turned upward in the image that is being processed |
| yawThresh | Float | 4.0f | The Euler angle Y of the head. Indicates the rotation of the face about the vertical axis of the image. Positive y euler angle is when the face is turned towards the right side of the image that is being processed | |
| tooDarkThresh | Int | 50 | Minimum threshold for the average intensity of the pixels in the image |
| tooLightThresh | Int | 170 | Maximum threshold for the average intensity of the pixels in the image |
| faceCentralizationThresh | Float | 0.05 | Threshold to consider the face centered, in percentage |
FaceLivenessMaskOptions
| Name | Type | Default value |
| ----------------- | -------------- | -------------------------------------------- |
| enabled | Bool | true |
| backgroundColor | Color | ColorUtil.hexStringToColor(hex: "#CC000000") |
| frameColor | Color | Color.white |
| frameEnabledColor | Color | ColorUtil.hexStringToColor(hex: "#16AC81") |
| frameErrorColor | Color | ColorUtil.hexStringToColor(hex: "#E25353") |
FaceLivenessFeedbackTextOptions
| Name | Type | Default value |
| --------- | ------------------------ | -------------------------- |
| enabled | Bool | true |
| messages | FaceFeedbackTextMessages | FaceFeedbackTextMessages() |
| textColor | Color | Color.white |
| textSize | CGFloat | 14 |
FaceLivenessFeedbackTextMessages
| Name | Type | Default value |
| ------------------- | ------ | ----------------------------- |
| noDetection | String | "No faces detected" |
| multipleFaces | String | "Multiple faces detected" |
| faceCentered | String | "Face centered. Do not move" |
| tooClose | String | "Turn your face away" |
| tooFar | String | "Bring your face closer" |
| tooLeft | String | "Move your face to the right" |
| tooRight | String | "Move your face to the left" |
| tooUp | String | "Move your face down" |
| tooDown | String | "Move your face up" |
| invalidIED | String | "Invalid inter-eye distance" |
| faceAngleMisaligned | String | "Misaligned face angle" |
| tooDark | String | "Too dark" |
| tooLight | String | "Too light" |
FaceLivenessButtonOptions
| Name | Type | Default value |
| --------------- | --------------- | ----------------------------- |
| enabled | Bool | true |
| backgroundColor | Color | Color.white |
| buttonPadding | Int | 0 |
| buttonSize | CGSize | CGSize(width: 56, height: 56) |
| iconOptions | FaceIconOptions | |
| labelOptions | FaceTextOptions | |
FaceLivenessIconOptions
| Name | Type | Default value |
| --------- | ------ | ----------------------------- |
| enabled | Bool | true |
| iconFile | String | "" |
| iconColor | Color | Color.black |
| iconSize | CGSize | CGSize(width: 32, height: 32) |
FaceLivenessTextOptions
| Name | Type | Default value |
| --------- | ------- | ------------- |
| enabled | Bool | true |
| content | String | "" |
| textColor | Color | Color.black |
| textSize | CGFloat | 14 |
FaceLivenessResolutionPreset (enum)
| Name | Resolution |
| ------------------------------------- | ----------------- |
| FaceLivenessResolutionPreset.HIGH | 720p (1280x720) |
| FaceLivenessResolutionPreset.VERYHIGH | 1080p (1920x1080) |
How to change font family
To add the font files to your Xcode project:
- In Xcode, select the Project navigator.
- Drag your fonts from a Finder window into your project. This copies the fonts to your project.
- Select the font or folder with the fonts, and verify that the files show their target membership checked for your app’s targets.
Then, add the "Fonts provided by application" key to your app’s Info.plist file. For the key’s value, provide an array of strings containing the relative paths to any added font files.
In the following example, the font file is inside the fonts directory, so you use fonts/RobotoMono-BoldItalic.ttf as the string value in the Info.plist file.
Finally, just set the font by passing the font name when instantiating FaceConfig.
var config = FaceLivenessConfig()
config.fontFamily = "Poppins-Bold"
How to change icon
To add icon files to your Xcode project:
- In the Project navigator, select an asset catalog: a file with a .xcassets file extension.
- Drag an image from the Finder to the outline view. A new image set appears in the outline view, and the image asset appears in a well in the detail area.
Finally, just set the icon by passing the icon name when instantiating FaceConfig.
var config = FaceLivenessConfig()
config.licenseKey = "your-license-key"
// changing back button icon
config.backButton.iconOptions.iconFile = "ic_close"
Changelog
v1.0.5
- Added documentation;
- Added face detection;
- Added auto capture;
- Added debug parameter:
- If debug=true, the facial detection attributes that result in an invalid face will be printed in the UI;
- If debug=true, the face rectangle will be drawn in the UI.
Quick install instructions for:
copy
copy
copy
copy
copy
Other options:
Other options:
Other options:
Other options:
Other options:
Packages
Recent
| Name |
|---|
| facelivenesssdk-1.0.5.zip |