Skip to main content

How to use Ruler Feature

This tutorial will guide you on how to use a ruler feature using Banuba API. The API provides ready-made documented methods making it easy for developers to call AR features in their apps.


The ruler feature requires a distance to phone feature and face tracking feature. Please, make sure your licence plan includes both by contacting your sales manager or fill in the website form to request it.

Resource preparation#

Get Test Ruler effect#

  1. Contact your sales manager to get test_Ruler effect.

Integrating Face Ruler feature into your iOS app#

  1. Build your project with Banuba SDK.

  2. Use the test_Ruler effect or your version of this effect to enable ruler feature.


    You also need to disable ARKit on sdk initializing:

    let configuration = EffectPlayerConfiguration(renderMode: renderMode, useARKitWhenAvailable: false)
    sdkManager.setup(configuration: configuration)
  3. Set Offline mode for Face Tracking feature, so Ruler feature will be able to estimate distance up to 3 meters.

  4. Create Listener to read Ruler feature result. For this you can use this example code:

    import BanubaEffectPlayer
    import BanubaSdk
    class RulerListener: BNBFrameDataListener {
    var m_sdk_manager: BanubaSdkManager
    init(sdk_manager: BanubaSdkManager) {
    m_sdk_manager = sdk_manager;
    func onFrameDataProcessed(_ frameData: BNBFrameData?) {
    guard let curEffect = m_sdk_manager.currentEffect() else {return}
    if let fd = frameData {
    do {
    try BNBObjC.safeCall {
    let rulerValue = fd.getRuler()
    print("Ruler value is " + String(rulerValue))
    catch {
    print("Unexpected non-vending-machine-related error: \(error)")
  5. Create Listener instance

    var rulerListener: RulerListener! = nil

    and subscribe it to Ruler Value changes:

    rulerListener = RulerListener(sdk_manager: sdkManager)
    sdkManager.effectPlayer?.add(rulerListener as BNBFrameDataListener)

    don't forget to unsubscribe the Listener before changing effect:

    sdkManager.effectPlayer?.remove(rulerListener as BNBFrameDataListener)
    rulerListener = nil
  6. Now you can run your application to test the Ruler Feature values in application log.


Put face in frame to find distance using Ruler Feature. Without face in frame, getter will fail and write error in log.

Last updated on