Runtime Configuration

The Leap Motion system stores many options in configuration files. These include most of the user-settable options in the Leap Motion Control Panel, service control settings, and feature control settings. These options can be set at runtime using the Config class, when starting the Leap Motion service/daemon as a command line option, or in a JSON-formatted configuration file.

Important These settings affect all running Leap-enabled applications, not just your own. Use caution when changing settings on computers that you don’t personally control. Changes could interfere with the operation of the user’s other applications.

Tracking Control Settings

The tracking settings control the tracking data available to an application.

  • images_mode : integer

    Enables or disables tool tracking. Set to a value of 0 to disable images; set to a value of 2 to enable images.

    Since this setting is controlled by the user, you should ask for permission before changing its value.

    Note that applications must still invoke the image policy API at runtime to receive images. Simply enabling images on the service is not sufficient.

    bool areImagesEnabled = controller.config().getInt32("tracking_images_mode") == 2;
    if (!areImagesEnabled) {
        // Show dialog to request permission to turn on images
        if(permissionGranted){
            controller.config().setInt32("tracking_images_mode", 2);
            controller.config().save();
        }
    }
    
  • image_processing_auto_flip : boolean

    When enabled, the Leap Motion device can be used with either the long side of the device with the green LED facing toward or away from the user. The service detects the orientation and flips the images from the device before analyzing them. When disabled, the images are never flipped and tracking recognizes hands much better when the green LED side of the device is facing the user (or downward in a HMD mount).

    Since this setting is controlled by the user, you should ask for permission before changing its value.

    // read
    bool autoFlip = controller.config().getBool("tracking_processing_auto_flip");
    
    // write
    controller.config().setBool("tracking_processing_auto_flip", false);
    controller.config().save();
    

Service Control Settings

The service control settings change how the Leap Motion service (Windows) or daemon (OS X and Linux) operate.

  • robust_mode_enabled : boolean

    Robust mode improves tracking when excessive ambient IR light is present. However, it also lowers the framerate significantly. If the resulting framerate is too low, turning on robust mode might cause worse tracking performance than not enabling it in the first place.

    Robust mode can be enabled in the control panel and by setting the robust_mode_enabled configuration parameter. When enabled, the system enters robust mode when excessive ambient IR light is detected.

    Set this parameter to true to enable; false to disable.

    // read
    bool robustMode = controller.config().getBool("robust_mode_enabled");
    
    // write
    controller.config().setBool("robust_mode_enabled", false);
    controller.config().save();
    

    Since this setting is controlled by the user, you should ask for permission before changing its value.

  • avoid_poor_performance : boolean

    Since this setting is controlled by the user, you should ask for permission before changing its value.

    // read
    bool avoidPoorPerformance = controller.config().getBool("avoid_poor_performance");
    
    // write
    controller.config().setBool("avoid_poor_performance", false);
    controller.config().save();
    
  • background_app_mode arg : integer

    Determines whether applications can receive tracking data when not the focused, foreground application.

    Since this setting is controlled by the user, you should ask for permission before changing its value.

    bool backgroundModeAllowed = controller.config().getInt32("background_app_mode") == 2;
    if (!backgroundModeAllowed) {
        // Show dialog to request permission to allow background mode apps
        if(permissionGranted){
            controller.config().setInt32("background_app_mode", 2);
            controller.config().save();
        }
    }
    
  • cpu_affinity_mask arg : integer

    Processor affinity controls which CPU cores that a process will run on in a multi-core system. You can control the processor affinity of the Leap Motion service using the cpu_affinity_mask configuration parameter. This parameter takes an integer value that is converted into a bitmask that specifies which CPU cores the threads of the service will run on (i.e. 3, which is 0011 in binary, would specify that the threads will run on cores 1 and 2). A value of 0 means that the default OS-defined behavior is unchanged.

    The mask is passed to the Windows SetProcessorAffinityMask() API. This configuration parameter is not supported on other operating systems.

    Changes to this value only take affect when the service is restarted. Generally, it makes sense to set this value in the config.json file or on the command line to LeapSvc:

    {
      "configuration": {
        "cpu_affinity_mask": 1,
        "process_niceness": 6
      }
    }
    
  • process_niceness arg : integer

    Thread priority controls the priority of threads spawned by the Leap Motion service. Thread priority is controlled by the process_niceness configuration parameter. Specifying 0 means that the OS default priority is assigined; a value of 1-9 assigns a specific priority (1 = lowest, 9 = highest).

    Changes to this value only take affect when the service is restarted. Generally, it makes sense to set this value in the config.json file or on the command line to LeapSvc. This setting is used on Windows only.

  • no_cp_startup : boolean

    Detemines whether the Leap Motion Control panel application launches when the computer boots up. Set to true to suppress automatically launching the control panel; false (the default) to allow.

    // read
    bool controlPanelOnStartup = controller.config().getBool("no_cp_startup");
    
    // write
    controller.config().setBool("no_cp_startup", false);
    controller.config().save();
    
  • auto_check_updates : boolean

    Determines whether the Leap Motion service will automatically check for software updates.

    Since this setting is controlled by the user, you should ask for permission before changing its value.

    // read
    bool autoUpdateCheck = controller.config().getBool("auto_check_updates");
    
    // write
    controller.config().setBool("auto_check_updates", false);
    controller.config().save();
    
  • auto_install_updates : boolean

    Determines whether the Leap Motion service will automatically install software updates. the auto_check_updates setting must be true for the srvice to discover updates in the first place.

    // read
    bool autoInstallUpdates = controller.config().getBool("auto_install_updates");
    
    // write
    controller.config().setBool("auto_install_updates", false);
    controller.config().save();
    
  • show_tray_messages : boolean

    Allow notification area messages to be displayed by the service/daemon icon. Set true (the default) to allow; false to supress messages.

    This setting should only be used on computers you control.

    // read
    bool showNotifications = controller.config().getBool("show_tray_messages");
    
    // write
    controller.config().setBool("show_tray_messages", false);
    controller.config().save();
    
  • metrics_enabled : boolean

    Allows metric collection.

    This setting should only be used on computers you control.

    // read
    bool enableMetrics = controller.config().getBool("metrics_enabled");
    
    // write
    controller.config().setBool("metrics_enabled", false);
    controller.config().save();
    

Power Saving Options

Power saving options include the Control Panel Power Saving and Low Resource Mode settings. Power savings for computers running on battery power is on by default, but can be turned off using a configuration parameter.

The power-saving-related configuration parameters are:

  • power_saving_adapter : boolean

    Limits the frame rate to save power, even when the computer is plugged into AC power.

    // read
    bool acPowerSaver = controller.config().getBool("power_saving_adapter");
    
    // write
    controller.config().setBool("power_saving_adapter", false);
    controller.config().save();
    
  • power_saving_battery : boolean

    Limits the frame rate to save power when the computer is running on battery power.

    // read
    bool batteryPowerSaver = controller.config().getBool("power_saving_battery");
    
    // write
    controller.config().setBool("power_saving_battery", false);
    controller.config().save();
    
  • low_resource_mode_enabled : boolean

    Limits the frame rate to reduce USB bandwidth.

    // read
    bool lowResourceMode = controller.config().getBool("low_resource_mode_enabled");
    
    // write
    controller.config().setBool("low_resource_mode_enabled", false);
    controller.config().save();
    

Setting a value of false for one of these options disables it; a value of true enables it.

The effects of these options are not additive. If you enable both power saving and low resource modes, the resulting framerate will be the minimum value set by either option alone.

The power saving configuration parameters are ignored when images are enabled. (Low resource mode is still effective.)

WebSocket Options

The WebSocket options control how programs can connect to the WebSocket server provided by the Leap Motion service.

Important If you change these values, other programs on the client computer that expect the default WebSocket settings will fail to connect.

Key string Value type Default value Purpose
websockets_enabled boolean true Enables or disables all connections
websockets_allow_remote boolean false Allows non-localhost clients to connect
ws_port integer 6437 Used for connections from HTTP clients
wss_port integer 6436 Used for connections from HTTPS clients

Note that changes to the port numbers do not take effect until the Leap Motion service or daemon restarts. Generally, it makes more sense to set these values on the command line or in the config.json file rather than using the Config class:

{
  "configuration": {
    "websockets_enabled": true,
    "websockets_allow_remote": false,
    "ws_port": 51000,
    "wss_port": 51001
  }
}

Feature Control Settings

Two sets of configuration settings control how individual tracking features operate.

InteractionBox Options

The interaction box options control the size and location of the region used by the InteractionBox class to compute normalized coordinates.

Key string Value type Default value Purpose
interaction_box_auto boolean true Sets the height based on the user’s hands
interaction_box_height integer 200 mm The current height setting
interaction_box_scale float 0.8 Scales the dimensions of the box

The height parameter sets the center height of the interaction area above the Leap Motion device. The size of the box also changes with height to maximize the interaction area while keeping the entire box within the field of view. You can view the interaction box in the Visualizer by pressing the L key (twice).

Note that there is currently (version 2.2.5+) a bug that prevents setting the InteractionBox height manually. The height only changes when the interaction_box_auto setting is true and only in respose to the user’s hand movement.

Since the interaction_box_auto and interaction_box_height settings can be set by the user, you should ask for permission before changing the values.

For more information, see InteractionBox.

Setting Configuration Options

Configuration prameters can be set on the command line when invoking the Leap Motion service/daemon executable, (LeapSvc on Windows and leapd on OS X and Linux), in a configuration file, and in application code using the Leap Motion API.

On the Command Line

To set configration parameters on the command line, run LeapSvc in a console window, specifying the desired options:

  • Windows:

    LeapSvc --option_name=value --another_option=value
    
  • Mac and Linux:

    leapd   --option_name=value --another_option=value
    

Normally LeapSvc or leapd are installed as a service or daemon and run automatically. Before running LeapSvc manually, you must stop the service if it is already running. You can do this using the standard Windows net command (using an admin account):

  • Windows:

    net stop LeapService
    
  • Mac:

    sudo launchctl unload /Library/LaunchDaemons/com.leapmotion.leapd.plist
    
  • Linux:

    sudo service leapd stop
    

As an example, the following command runs the service with auto-orientation and images turned on:

  • Windows:

    LeapSvc  --image_processing_auto_flip=true  --images_mode=2
    
  • Mac and Linux

    leapd –image_processing_auto_flip=true –images_mode=2

Important: Command line configuration settings can be ignored when the Leap Motion Control Panel is already running.

In a Configuration file

You can add options to a JSON-formatted configuration file. The options file can be specified on the LeapSvc command line using the --config parameter or you can add your options to the standard config file.

A configuration file must be valid JSON. A configuration file specifying the options discussed in this document looks like:

{
  "configuration": {
    "cpu_affinity_mask": 3,
    "images_mode": 2,
    "power_saving_adapter": false,
    "power_saving_battery": false,
    "process_niceness": 5,
    "robust_mode_enabled": false,
    "tracking_hand_enabled": true
  }
}

On the command line, you can specify the config file as follows:

LeapSvc –config=/path/to/config.json

leapd –config=/path/to/config.json

The Leap Motion system also maintains two standard JSON-formatted configuration files. One is used by the service/daemon, the other is used by the Leap Motion Control Panel application. When both the service and the control panel are running, shared settings are kept in sync. Otherwise, the control panel settings take precedence. In other words, if the service/daemon is already running when the control panel launches, settings are updated to match those found in the control panel configuration file. If the control panel is running when the service/daemon starts, the control panel settings still take precedence over any found in the service configuration file – or set on the command line.

Editing these configuration files while the service/daemon or control panel is running does not change the current runtime setting. We recommend quitting the control panel and shutting down the service/daemon before making changes.

The configuration files are named config.json and can be found in the following locations:

OS Control Panel Config Location Service/Daemon Config Location
Android /sdcard/user/Leap\ Motion /sdcard/Leap\ Motion
Linux $HOME/Leap\ Motion /var/Leap\ Motion
OS X $HOME/Library/Application\ Support/Leap\ Motion /Library/Application\ Support/Leap\ Motion
Windows %AppData%/Leap Motion %ProgramData%/Leap Motion

Note that some of these folders are located within hidden directories.