Skip to content
This repository has been archived by the owner on Nov 15, 2022. It is now read-only.

Commit

Permalink
1.0.0-beta.3 release
Browse files Browse the repository at this point in the history
  • Loading branch information
@rblenkinsopp
rblenkinsopp committed Oct 27, 2021
1 parent 382feb1 commit f2f28e5
Show file tree
Hide file tree
Showing 3 changed files with 99 additions and 82 deletions.
109 changes: 70 additions & 39 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,56 +2,87 @@

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres
to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## 1.0.0-beta.3

### Added

- Signed Windows installer to replace the previous PowerShell based installer. Installation will remove previous
versions of the API Layer.
- Added support for the `XR_EXT_hand_joints_motion_range` extension. Since Ultraleap hand-trackers are optical-based
systems, the returned hand pose is always based on the unobstructed joint locations.
- Added support for the linear velocity reporting of the palm joint (`XR_HAND_JOINT_PALM_EXT`).

### Changed

- Updated Ultraleap tracking client to v5.2.0.
- Updated OpenXR SDK to v1.0.20.
- OpenXR API layer DLL is now signed.
- Use `XR_KHR_win32_convert_performance_counter_time` or `XR_KHR_convert_timespec_time` extensions for accurate internal
timestamp conversions.
- Removed configurations variables `ULTRALEAP_OPENXR_TIME_WARP_HEAD` and `ULTRALEAP_OPENXR_TIME_WARP_VIEW` as they are
no longer required now that [Issue #6](https://github.com/ultraleap/OpenXRHandTracking/issues/6) is resolved.
- Removed 32-bit support as the Ultraleap tracking client v5 doesn't currently have support for Windows 32-bit.

## 1.0.0-beta2
### Fixed

- Fixed support for UWP/AppContainer applications, including WebXR, when used in conjunction with the
[Ultraleap 4.1 Tracking SDK](https://developer-archive.leapmotion.com/downloads/external/v4-1-hand-tracking/windows?version=4.1.0).
[Issue #8](https://github.com/ultraleap/OpenXRHandTracking/issues/8)
- Correct wrist position (was incorrectly reporting the elbow position as the wrist position).
[Issue #10](https://github.com/ultraleap/OpenXRHandTracking/issues/10)
- Fixed temporal warping so that the user's hands no longer move when held static and the user's head is rapidly
moved. [Issue #6](https://github.com/ultraleap/OpenXRHandTracking/issues/6)

## 1.0.0-beta.2

### Added

- The uninstaller is included with the install as `UninstallOpenXR.cmd` to allow easy uninstallation. An entry is also
added to Windows add/remove programs list.
- The License, Readme, Changelog and version information are all now included in an install for easy reference.
- Added log file output (to complement existing `XR_EXT_debug_utils` support) only warnings and errors are logged by
default, but this can be controlled with the `ULTRALEAP_OPENXR_DEBUG` environment variable.
- Clarified in the Readme that this is an implicit OpenXR api layer, and does not need explicitly enabling.
- The uninstaller is included with the install as `UninstallOpenXR.cmd` to allow easy uninstallation. An entry is also
added to Windows add/remove programs list.
- The License, Readme, Changelog and version information are all now included in an installation for easy reference.
- Added log file output (to complement existing `XR_EXT_debug_utils` support) only warnings and errors are logged by
default, but this can be controlled with the `ULTRALEAP_OPENXR_DEBUG` environment variable.
- Clarified in the Readme that this is an implicit OpenXR api layer, and does not need explicitly enabling.

### Changed

- Removed SteamVR <1.14 specific workaround for `xrGetSystemProperties` extension support.
[Issue #5](https://github.com/ultraleap/OpenXRHandTracking/issues/5)
- Removed SteamVR <1.14 specific workaround for `xrGetSystemProperties` extension support.
[Issue #5](https://github.com/ultraleap/OpenXRHandTracking/issues/5)

### Fixed

- Fixed support for UWP/AppContainer applications, including WebXR, when used in conjunction with the
[Ultraleap 4.1 Tracking SDK](https://developer-archive.leapmotion.com/downloads/external/v4-1-hand-tracking/windows?version=4.1.0)
.
[Issue #8](https://github.com/ultraleap/OpenXRHandTracking/issues/8)

## 1.0.0-beta.1

## 1.0.0-beta1
### Added

- Initial support for the `XR_EXT_hand_tracking` extension
- Initial support for the `XR_EXT_hand_tracking` extension

### Known Issues

- This API layer does not currently report the linear or angular velocity of the hands.
If requested, the XrHandJointVelocitiesEXT structure will be returned with the validity bits unset.
[Issue #1](https://github.com/ultraleap/OpenXRHandTracking/issues/1)

- The underlying Ultraleap service currently return the same joint radius for all joints.
[Issue #2](https://github.com/ultraleap/OpenXRHandTracking/issues/2)

- `XrSystemHandTrackingPropertiesEXT.supportsHandTracking` will always return `XR_TRUE` when this API layer is enabled,
regardless of if a device is connected. `XrHandJointLocationsEXT.isActive` indicates if hand-tracking information is
currently available for the requested hand-tracker.
[Issue #3](https://github.com/ultraleap/OpenXRHandTracking/issues/3)
- The user's virtual hands may appear to move relative to the head when the head is moved quickly, even when the user's
hands are remaining still. This is due to the temporal warping settings and the fact that the hand position and view
position are updated at different rates.
[Issue #6](https://github.com/ultraleap/OpenXRHandTracking/issues/6)

- Unreal Engine 4.25 currently ships with version 1.0.0 of the OpenXR loader which has a
[known issue](https://github.com/KhronosGroup/OpenXR-SDK-Source/pull/91) which prevents OpenXR API layers from
functioning correctly. This will be resolved when Unreal Engine ships with a newer OpenXR loader, or the existing
OpenXR loader DLLs are manually updated.
[Issue #4](https://github.com/ultraleap/OpenXRHandTracking/issues/4)
- This API layer does not currently report the linear or angular velocity of the hand joints other than the palm. If
requested, the XrHandJointVelocitiesEXT structure will be returned with the validity bits unset.
[Issue #1](https://github.com/ultraleap/OpenXRHandTracking/issues/1)

- The underlying Ultraleap service currently return the same joint radius for all joints.
[Issue #2](https://github.com/ultraleap/OpenXRHandTracking/issues/2)

- `XrSystemHandTrackingPropertiesEXT.supportsHandTracking` will always return `XR_TRUE` when this API layer is enabled,
regardless of if a device is connected. `XrHandJointLocationsEXT.isActive` indicates if hand-tracking information is
currently available for the requested hand-tracker.
[Issue #3](https://github.com/ultraleap/OpenXRHandTracking/issues/3)

- The user's virtual hands may appear to move relative to the head when the head is moved quickly, even when the user's
hands are remaining still. This is due to the temporal warping settings and the fact that the hand position and view
position are updated at different rates.
[Issue #6](https://github.com/ultraleap/OpenXRHandTracking/issues/6)

- Unreal Engine 4.25 currently ships with version 1.0.0 of the OpenXR loader which has a
[known issue](https://github.com/KhronosGroup/OpenXR-SDK-Source/pull/91) which prevents OpenXR API layers from
functioning correctly. This will be resolved when Unreal Engine ships with a newer OpenXR loader, or the existing
OpenXR loader DLLs are manually updated.
[Issue #4](https://github.com/ultraleap/OpenXRHandTracking/issues/4)
5 changes: 2 additions & 3 deletions LICENSE.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,2 @@
This Software is subject to the Ultraleap SDK License Agreement and is provided for the purpose of internal evaluation
and demonstration only. The Ultraleap SDK License Agreement is available at
https://central.leapmotion.com/agreements/SdkAgreement and are available from Ultraleap on request.
This Software is subject to the Ultraleap SDK License Agreement and is provided for the purpose of internal evaluation and demonstration only.
The Ultraleap SDK License Agreement is available at https://central.leapmotion.com/agreements/SdkAgreement and are available from Ultraleap on request.
67 changes: 27 additions & 40 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,15 @@ Any application which uses the `XR_EXT_hand_tracking` will be able to use this l
You will require an OpenXR runtime to be installed to use this API layer. The correct runtime will depend on your
platform and XR hardware, some of the most common platforms are listed below:

* [Microsoft Windows Mixed Reality](https://docs.microsoft.com/en-us/windows/mixed-reality/openxr-getting-started)
* [Valve SteamVR](https://store.steampowered.com/newshub/app/250820/view/2396425843528787269)
* [Oculus OpenXR](https://developer.oculus.com/documentation/native/pc/dg-openxr/)

* [Microsoft Windows Mixed Reality](https://docs.microsoft.com/en-us/windows/mixed-reality/openxr-getting-started)
* [Valve SteamVR](https://store.steampowered.com/newshub/app/250820/view/2396425843528787269)
* [Oculus OpenXR](https://developer.oculus.com/documentation/native/pc/dg-openxr/)

#### Required OpenXR Extensions

The runtime is required to support the `XR_KHR_win32_convert_performance_counter_time` (Windows) or
`XR_KHR_convert_timespec_time` (Unix) extensions. All major runtimes (including those listed above) support these.

### Ultraleap Software

You will require the current
Expand All @@ -37,29 +42,24 @@ The latest version of this API layer can be installed from the

## Installing

Once downloaded follow the following steps to install the API layer.
Once downloaded run the EXE installer to installer the API layer.

- Extract the downloaded `.zip`
- Right click the `Install.cmd` script and select "Run as administrator"
- Type "Yes" at the prompts accept the license agreement and to start the installation
- Wait for the installation to complete.

You can verify that the installation has been successfully completed by installing the
[Microsoft Mixed Reality OpenXR Developer Tools App](https://www.microsoft.com/store/productId/9n5cvvl23qbt) from the
Microsoft Store. Once this is opened, navigate to the "System Status" tab, and you should see `XR_EXT_hand_tracking`
listed in the Extensions section, and `XR_APILAYER_ULTRALEAP_hand_tracking` listed under the API Layers section.

This method of verification has only been confirmed with the Windows Mixed Reality OpenXR runtime, but should work with
others as well.

## Setup

The API layer will report hand-tracking as supported when this API layer is installed. To be able to actively use the
hand tracking the following must all be true:

- Leap Motion v4 Software installed and running
- Ultraleap hand-tracking device attached and operating correctly
- User's hands visible to the Ultraleap hand-tracking device.
- Leap Motion v5 Software installed and running
- Ultraleap hand-tracking device attached and operating correctly
- User's hands visible to the Ultraleap hand-tracking device.

## Configuration

Expand All @@ -71,47 +71,34 @@ method such as the [Ultraleap VR Developer Mount](https://www.ultraleap.com/prod
The position of the Ultraleap tracking device, relative to your view position can be configured using the following
environment variables (position relative to the interpupillary line).

![Leap Mounting Diagram](https://developer.leapmotion.com/documentation/v4/HMD_Mounting.png)
![Ultraleap Mounting Diagram](https://developer.leapmotion.com/documentation/v4/HMD_Mounting.png)

These environment variables must be set prior to the OpenXR application starting, if they are left unset,
the default values (in brackets) are used:
These environment variables must be set prior to the OpenXR application starting, if they are left unset, the default
values (in brackets) are used:

- `ULTRALEAP_OPENXR_POS_X` - Position in X in meters (default: 0.0m)
- `ULTRALEAP_OPENXR_POS_Y` - Position in Y in meters (default: 0.0m)
- `ULTRALEAP_OPENXR_POS_Z` - Position in Z in meters (default: -0.08m/-8cm)
- `ULTRALEAP_OPENXR_TILT_ANGLE` - Tilt angle downwards in degrees from the forward facing horizontal (default 0)

### Temporal Warping

The position of the hands in the scene is interpolated to compensate for differences between the captured hand-tracking
frame and the update time of the user's view. This is controlled by two environment variables:

- `ULTRALEAP_OPENXR_TIME_WARP_HAND` - +/- timestamp offset in milliseconds for the hand position (default: +10ms)
- `ULTRALEAP_OPENXR_TIME_WARP_VIEW` - +/- timestamp offset in milliseconds for the view position (default: -25ms)

These parameters can be different for each different headset runtime and can be tuned appropriately. These can help
stabilise the hand-position in space if the view position is moved rapidly.
- `ULTRALEAP_OPENXR_POS_X` - Position in X in meters (default: 0.0m)
- `ULTRALEAP_OPENXR_POS_Y` - Position in Y in meters (default: 0.0m)
- `ULTRALEAP_OPENXR_POS_Z` - Position in Z in meters (default: -0.08m/-8cm)
- `ULTRALEAP_OPENXR_TILT_ANGLE` - Tilt angle downwards in degrees from the forward facing horizontal (default 0)

### Logging

By default, `%PROGRAMFILES%\Leap Motion\OpenXR\Logs\UltraleapOpenXR.log` will log errors and warnings generated during
application usage of OpenXR. The logging location, and level can be controlled by the following environment variables:

- `ULTRALEAP_OPENXR_LOG_LEVEL` - The logging level, supported levels are `all`, `debug`, `info`, `warn`, and `error`
(default: "warn")
- `ULTRALEAP_OPENXR_LOG_PATH` - The location of the log file (default:
`%PROGRAMFILES%\Leap Motion\OpenXR\Logs\UltraleapOpenXR.log`)
- `ULTRALEAP_OPENXR_LOG_LEVEL` - The logging level, supported levels are `all`, `debug`, `info`, `warn`, and `error`
(default: "warn")
- `ULTRALEAP_OPENXR_LOG_PATH` - The location of the log file (default:
`%PROGRAMFILES%\Leap Motion\OpenXR\Logs\UltraleapOpenXR.log`)

## Disabling the API layer

If you wish to disable the API layer, this can be achieved by defining the
`DISABLE_XR_APILAYER_ULTRALEAP_HAND_TRACKING_1` environment variable to any value.

## Uninstalling

You can remove the API layer by right clicking the included `Uninstall.cmd` script and selecting "Run as administrator".
This will remove the installed files and registry keys. Uninstallation can also be performed from the Windows "Add or
Remove Programs" area of the system settings.
Uninstallation can be performed from the Windows "Add or Remove Programs" area of the system settings.

## Known issues

Expand Down

0 comments on commit f2f28e5

Please sign in to comment.