Skip to content

Latest commit

 

History

History
223 lines (142 loc) · 12.3 KB

README.md

File metadata and controls

223 lines (142 loc) · 12.3 KB
Raw

Ultraleap Unity Plugin

documentation mail discord GitHub

openupm-tracking openupm-tracking-preview

The Ultraleap Unity Plugin empowers developers to build Unity applications using Ultraleap's hand tracking technology. It includes various assets, examples, and utilities that make it easy to design and build applications using hand tracking in XR projects.
Get set up with the Ultraleap Plugin for Unity. Discover the available features of the Ultraleap Plugin for Unity. Contribute to the Open Source repository to make your mark and help others.

Getting Started

To use this plugin you will need the following:

  1. The latest Ultraleap Hand Tracking Software. You can get this here.
  2. An Ultraleap Hand Tracking Camera - follow setup process here.
  3. Unity 2021.3 LTS or newer. UnityPlugin packages have been tested to work against 2021.3 LTS and 2022.3 LTS.
  4. Follow one of the Installation workflows listed below.

More detailed Getting Started documentation is available on our website

Please note:

  • Due to the ever changing landscape of package dependencies in Unity we cannot guarantee compatibility with every plugin or variant of Unity, but aim to provide support for any LTS versions that are under continuous support from Unity.
  • If you are sourcing the Unity Plugin directly from this repository, you may find that it does not function well with earlier versions of Unity.

Installation

There are several ways you can consume this plugin. We've listed several recommended workflows for different users below. This list is by no means exhaustive

OpenUPM (Recommended)

This workflow is the easiest way to get up and running and makes updating packages simple.

If you are familiar with OpenUPM, follow the OpenUPM instructions.

OpenUPM Setup

Setup only needs to be performed once per Unity project. In Edit -> Project Settings -> Package Manager, add a new scoped registry with the following details:

Name: Ultraleap
URL: https://package.openupm.com
Scope(s): com.ultraleap

scoped_registry.png

OpenUPM Adding, Upgrading or Removing Packages

Open the Package Manager (Window -> Package Manager) and navigate to "My Registries" in the dropdown at the top left of the window.

my_registries.png

Ultraleap UPM packages should be available in the list. Click on the package you wish to install/modify.

Note: Ultraleap Tracking contains the Core, Hands and Interaction Engine modules. There are older packages created independently by a third party for these modules that are no longer updated.

packagelist.png

(Optional) When clicking the package, it will automatically select the latest version. If you want to pick or change to a different version, click the arrow on the left of the package name and then "See all versions".

packageversions.png

The package can be installed or removed using buttons in the bottom right. (The install button is replaced with "Upgrade to <version>" if the package is currently installed)

packageinstall.png

OpenUPM CLI

If you prefer to use a CLI to modify your packages or need to be able to perform actions from a terminal (e.g. CI) then you may find the OpenUPM CLI helpful. See Getting Started with OpenUPM-CLI.

Unity Package (Legacy)

You can find the .unitypackage releases of the Ultraleap Pugin for Unity attached to each release here

Please note, .unitypackages do not handle package dependencies or updates and is therefore only recommended if you wish to modify the package.

Detailed instructions are available in the foldout below.

Legacy .unitypackage

.unitypackage Summary

.unitypackage files are the legacy consumption method available if you prefer it or which still can be helpful if you:

  1. need to modify the package content and
  2. don't expect to upgrade to a newer version

If you don't need to modify package content, the OpenUPM Consumer workflow is recommended. If you do and expect to upgrade to a newer version, the Local UPM Package Contributor workflow is recommended as it enables you to version control your changes using git and resolve any potential conflicts when upgrading.

.unitypackage Adding

  1. Import the package (Assets -> Import Package -> Custom Package) which can be downloaded from our Unity developer site or the releases section of this repository.

.unitypackage Upgrading

  1. (Optional) If you have made any changes to a package you may want to save those changes elsewhere.
  2. Delete the package content you want to upgrade from Assets/ThirdParty/Ultraleap.
  3. Import the .unitypackage you wish to change to.

.unitypackage Removing

  1. Delete the package you want to remove from Assets/ThirdParty/Ultraleap.

Contributor Workflows

Contributor workflows are used by UnityPlugin developers and are recommended for community members that want to contribute back to the source repository.

Local UPM Package

Local UPM Package Summary

This workflow takes a few steps to setup and enables you to:

  • Modify UPM package content from within one (or many) Unity project(s).
  • Manage changes using git.
  • Contribute changes back to the remote repository.

(Note) Git LFS is required when importing via this method.

Local UPM Package Setup

  1. Clone or submodule the repository.
    1. The repository should not be cloned/submoduled into Unity reserved project folders, i.e. Assets, Library, ProjectSettings or Packages. Creating another folder such as "LocalPackages" is recommended.
    2. (Note) If you don't plan to share your project and would like to use the same UPM packages across multiple Unity projects it may be ideal to clone to a common place on your machine.

Local UPM Package Adding

You can add packages from the repository to your project in one of two ways:

  1. (Sharable) Edit your project manifest.json (Project/Packages/manifest.json) to add the relative paths from your Unity project's Packages folder to the Packages in the repository Packages folder. For more information see the Unity Manual. Below is an example if you had cloned the repository to LocalPackages within your Unity project.

    "com.ultraleap.tracking": "file:../LocalPackages/unityplugin/Packages/Tracking",
"com.ultraleap.tracking.preview": "file:../LocalPackages/unityplugin/Packages/Tracking Preview",

  2. (Not sharable) Open the package manager (Window -> Package Manager) and click "Add package from disk…". Point it to the desired package within the repository Packages folder. Repeat to add all the packages you want to reference locally. This will use an absolute file path from your machine, so will not be a sharable solution without modifying the path to work on the new machine.

Local UPM Package Upgrading

Changing package versions is done through the git repository itself. Released versions can be found by checking the repository tags.

Local UPM Package Removing

  1. Open the package manager (Window -> Package Manager).
  2. Navigate to "In Project" in the dropdown. packagesinproject.png
  3. Select the package you want to remove and click remove in the bottom right.

Contributing

Our vision is to make it as easy as possible to design the best user experience for hand tracking use cases in XR. We learn and are inspired by the creations from our open source community - any contributions you make are greatly appreciated.

  1. Fork the Project
  2. Create your Feature Branch:
    git checkout -b feature/AmazingFeature
  3. Commit your Changes:
    git commit -m "Add some AmazingFeature"
  4. Push to the Branch:
    git push origin feature/AmazingFeature
  5. Open a Pull Request

License

Use of Ultraleap's Unity Plugin is subject to the Apache V2 License Agreement.

Community Support

Our Discord Server, Github Discussions and Developer Forum are places where you are actively encouraged to share your questions, insights, ideas, feature requests and projects.

Links

Ultraleap Unity Plugin Documentation