Appearance
Quick Start
This quick start guide describes the basic flow for measuring vital signs using Binah.ai SDK.
The SDK supports three measurements modes:
- Face Measurement
- Finger Measurement
- Polar Measurement
Deprecation Warning
Finger measurements are deprecated and will be removed in future versions of Binah.ai's SDK.
A sample flow for face measurement follows. A similar flow can be applied for finger measurements. See Measurement Modes for more information about measurement modes.
Creating a Measurement Session
A session is an interface for performing vital sign measurements.
- When creating a session, it is essential to define the measurement mode. The SDK supports three measurement modes:
- Face Measurements (Front Camera): This mode utilizes the front camera for capturing face-related measurements.
- Finger Measurements (Rear Camera): In this mode, the rear camera is used to take measurements from the user's finger.
- Polar Measurements (External PPG Sensor): This mode enables measurements using the Polar Verity Sense sensor.
- Only a single session can be created at any given time. Terminate the previous session before creating a new session.
- When switching to a different measurement mode (for example, from face to finger, or from finger to face), the current session must be terminated, and a new session must be created.
- A session is intended for a single user. When measuring the vital signs of another user, a new session must be created. See Demographic Info.
The following code can be used to create a session with the relevant parameters:
Note
- For simplicity, the code sample below uses
self
(the current class), as the implementor of all the session builder listeners.
Swift
do {
let licenseDetails = LicenseDetails(licenseKey: "<ENTER_YOUR_LICENSE_KEY>")
let session = try FaceSessionBuilder()
.withImageListener(self)
.withVitalSignsListener(self)
.withSessionInfoListener(self)
.build(licenseDetails: licenseDetails)
}
catch {
let e = error as NSError
print("Received Error. Domain: \(e.domain) Code: \(e.code)")
}
do {
let licenseDetails = LicenseDetails(licenseKey: "<ENTER_YOUR_LICENSE_KEY>")
let session = try FaceSessionBuilder()
.withImageListener(self)
.withVitalSignsListener(self)
.withSessionInfoListener(self)
.build(licenseDetails: licenseDetails)
}
catch {
let e = error as NSError
print("Received Error. Domain: \(e.domain) Code: \(e.code)")
}
Objective-c
BNHLicenseDetails *licenseDetails = [[BNHLicenseDetails alloc] initWithLicenseKey:@"<ENTER_YOUR_LICENSE_KEY>"];
BNHFaceSessionBuilder *sessionBuilder = [[[[[BNHFaceSessionBuilder alloc] init]
withImageListener:self]
withVitalSignsListener:self]
withSessionInfoListener:self];
NSError *error = nil;
id<BNHSession> _Nullable session = [sessionBuilder buildWithLicenseDetails:licenseDetails
error:&error];
if (error != nil) {
NSLog(@"Received Error. Domain: %@ Code: %ld", error.domain, (long)error.code);
}
BNHLicenseDetails *licenseDetails = [[BNHLicenseDetails alloc] initWithLicenseKey:@"<ENTER_YOUR_LICENSE_KEY>"];
BNHFaceSessionBuilder *sessionBuilder = [[[[[BNHFaceSessionBuilder alloc] init]
withImageListener:self]
withVitalSignsListener:self]
withSessionInfoListener:self];
NSError *error = nil;
id<BNHSession> _Nullable session = [sessionBuilder buildWithLicenseDetails:licenseDetails
error:&error];
if (error != nil) {
NSLog(@"Received Error. Domain: %@ Code: %ld", error.domain, (long)error.code);
}
Waiting for the Session to Transition into ready State
The application can receive session state updates by implementing onSessionStateChange
as part of SessionInfoListener.
Swift
func onSessionStateChange(sessionState: SessionState) {
DispatchQueue.main.async {
if (sessionState == .ready) {
print("Session is ready to start measuring")
}
}
}
func onSessionStateChange(sessionState: SessionState) {
DispatchQueue.main.async {
if (sessionState == .ready) {
print("Session is ready to start measuring")
}
}
}
Objective-C
- (void)onSessionStateChangeWithSessionState:(BNHSessionState)sessionState {
dispatch_async(dispatch_get_main_queue(), ^{
if (sessionState == BNHSessionStateReady) {
NSLog(@"Session is ready to start measuring");
}
});
}
- (void)onSessionStateChangeWithSessionState:(BNHSessionState)sessionState {
dispatch_async(dispatch_get_main_queue(), ^{
if (sessionState == BNHSessionStateReady) {
NSLog(@"Session is ready to start measuring");
}
});
}
Note
For more information on session states and state transitions, see Session State section.
Starting a Measurement
A measurement can be started by calling the start
method
Swift
do {
let measurmentDuration = 60
try session.start(measurmentDuration: measurmentDuration)
}
catch {
let nsError = (error as NSError)
print("Received Error. Domain: \(nsError.domain) Code: \(nsError.code)")
}
do {
let measurmentDuration = 60
try session.start(measurmentDuration: measurmentDuration)
}
catch {
let nsError = (error as NSError)
print("Received Error. Domain: \(nsError.domain) Code: \(nsError.code)")
}
Objective-C
NSInteger measurementDuration = 60;
[session startWithMeasurementDuration:measurementDuration error:&error];
if (error != nil) {
NSLog(@"Received Error. Domain: %@ Code: %ld", error.domain, (long)error.code);
}
NSInteger measurementDuration = 60;
[session startWithMeasurementDuration:measurementDuration error:&error];
if (error != nil) {
NSLog(@"Received Error. Domain: %@ Code: %ld", error.domain, (long)error.code);
}
Receiving Results During a Measurement
The application can receive instantaneous vital signs values by implementing onVitalSign
as part of VitalSignsListener.
Swift
func onVitalSign(vitalSign: VitalSign) {
// Handle vital sign result
}
func onVitalSign(vitalSign: VitalSign) {
// Handle vital sign result
}
Objective-C
- (void)onVitalSignWithVitalSign:(BNHVitalSign *)vitalSign {
// Handle vital sign result
}
- (void)onVitalSignWithVitalSign:(BNHVitalSign *)vitalSign {
// Handle vital sign result
}
During the measurement, the instantaneous vital sign values are available only for specific vital signs, while the results of all vital signs are received once the measurement has been completed.
Note
For more information on receiving and handling vital sign information, see Vital Signs.
Stopping a Measurement
The measurement is stopped either after the measurement duration (provided in the start function) has ended, or when the stop
method is called.
Swift
do {
try session.stop()
}
catch {
let nsError = (error as NSError)
print("Received Error. Domain: \(nsError.domain) Code: \(nsError.code)")
}
do {
try session.stop()
}
catch {
let nsError = (error as NSError)
print("Received Error. Domain: \(nsError.domain) Code: \(nsError.code)")
}
Objective-C
[session stopAndReturnError:&error];
if (error != nil) {
NSLog(@"Received Error. Domain: %@ Code: %ld", error.domain, (long)error.code);
}
[session stopAndReturnError:&error];
if (error != nil) {
NSLog(@"Received Error. Domain: %@ Code: %ld", error.domain, (long)error.code);
}
Note
Calling the stop
method initiates the calculation of the final results. See Vital Signs
Important
When the measurement stops, the session will transition to the stopping state.
The stopping state reflects that the session has initiated a stopping process that ends when the session state transitions to ready. At this point, a new measurement can be started.
Receiving Final Results
The application can receive final vital sign results and vital sign confidence levels by implementing onFinalResults
as part of VitalSignsListener.
Swift
func onFinalResults(results: VitalSignsResults) {
// Handle the final results of the measurements
}
func onFinalResults(results: VitalSignsResults) {
// Handle the final results of the measurements
}
Objective-C
- (void)onFinalResultsWithResults:(BNHVitalSignsResults *)results {
// Handle the final results of the measurements
}
- (void)onFinalResultsWithResults:(BNHVitalSignsResults *)results {
// Handle the final results of the measurements
}
The final results are computed when the session is in stopping state. For more information about receiving and handling the final results, see Vital Signs.
Terminating a Session
It is recommended to terminate the session whenever the measuring screen is not visible.
Swift
session.terminate()
session.terminate()
Objective-C
[session terminate];
[session terminate];
Important
Terminating the current session is mandatory in order to create a new session. When calling terminate()
, the session will transition to terminating state.
The terminating state means that the session has started a termination process that ends when the session state transitions to terminated.