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 LeapConfig 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.
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" value: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" value:false];
[controller.config save];
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" value: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" value: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" value: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" value: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" value: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" value: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" value: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" value:false];
[controller.config save];
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" value: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" value: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" value: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.)
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 LeapConfig class:
{
"configuration": {
"websockets_enabled": true,
"websockets_allow_remote": false,
"ws_port": 51000,
"wss_port": 51001
}
}
Two sets of configuration settings control how individual tracking features operate.
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 LeapInteractionBox.
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.
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.
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.