Controller Policies

Controller policies are a mechanism to turn on features that either change how the Leap Motion service/daemon operates or which can use additional computer resources. For example, the Optimize for HMD policy changes the hand recognition algorithms to expect to see the backs of hands more often then the palms of hands. Likewise, the Images policy instructs the service to send image data to your application, which adds a small amount of additional processing time and increases the size of a frame of tracking data.

Most policies can also be denied, typically because the user has disabled the feature in their Leap Motion control panel. For example, if the user has unchecked the “Allow Images” setting, then activating the Images policy in an application will fail.

The current policies available are:

  • Allow Pause and Resume — allows the application to pause and resume tracking.
  • Background Frames — receive tracking data when not the foreground, focused application.
  • Images — receive image data along with the rest of the tracking data.
  • Optimize for HMD — optimizes the tracking algorithm to recognize hands when the Leap Motion device is attached to a head-mounted display.

Allow Pause and Resume

Requesting the Allow Pause and Resume policy enables the setPaused() function, allowing your application to pause and resume the production of tracking data. Most applications should not request this policy. Pausing the service affects all Leap Motion applications. Activate this policy when you control the client computer and need to temporarily reduce resource usage.

Note that users can manually resume and pause the service using the Leap Motion control panel.

boolean isPausable = controller.isPolicySet(Controller.PolicyFlag.POLICY_ALLOW_PAUSE_RESUME);
controller.setPolicy(Controller.PolicyFlag.POLICY_ALLOW_PAUSE_RESUME);

Background Frames

Requesting background frames allows your application to receive tracking data when it is not the foreground, focused application. Ordinarily, the Leap Motion service/daemon only sends tracking data to an application when it has the operating system input focus. When you activate the Background Frames policy, your application will still receive frames when it loses focus to a non-Leap-enabled application — but not when another Leap-enabled application has the focus.

The background frames policy exists to help prevent Leap-enabled applications from conflicting with each other. If the user is actively working in one application — or just moving their hands for another reason — Leap-enabled applications in the background could otherwise receive unintended input. Typically, only mouse control or similar applications that don’t have their own GUI windows should request the Background Frames policy.

The background frames policy is denied when the user has unchecked the Allow Background Frames option in the control panel. Note that you can override the control panel setting using the Config class, but you must always ask the ask the user’s permission before doing so. If the user still denies permission and your application cannot function without it, simply exit, informing the user that background frames are necessary for your application.

boolean backgroundModeAllowed = controller.config().getInt32("background_app_mode") == 2;
if (!backgroundModeAllowed) {
    // Show dialog to request permission to allow background mode apps
    if(userPermission){
        controller.config().setInt32("background_app_mode", 2);
        controller.config().save();
    }
}
controller.setPolicy(Controller.PolicyFlag.POLICY_BACKGROUND_FRAMES);

Images

Requesting images enables the Frame.images() and Controller.images() functions, allowing your application to access data from the Leap Motion cameras.

The Images policy is denied if the user has unchecked the Allow Images option in the Leap Motion Control Panel. You can override the setting with the Config class, but you must ask the user’s permission before doing so. If the user still denies permission and your application cannot function without it, simply exit, informing the user that background frames are necessary for your application.

boolean imagesAllowed = controller.config().getInt32("tracking_images_mode") == 2;
if (!imagesAllowed) {
    // ask user for permission...
    if (userPermission) {
        controller.config().setInt32("tracking_images_mode", 2);
        controller.config().save();
    }
}
controller.setPolicy(Controller.PolicyFlag.POLICY_IMAGES);

Optimize for HMD

Requesting the Optimize for HMD policy tunes the hand recognition logic to better recognize hands when the Leap Motion device is attached to a head-mounted display. This primarily improves the classification of hands as left versus right and the direction of the palm. This policy does not improve tracking when the Leap Motion is mounted in a fixed, downward orientation.

controller.setPolicy(Controller.PolicyFlag.POLICY_OPTIMIZE_HMD);