Git Product home page Git Product logo

unityplugin's Introduction

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

unityplugin's People

Contributors

acolgan avatar ajohnston33 avatar amarcolina avatar brycenewell-ul avatar craig-j avatar dwarph avatar elliotpadfieldul avatar hham avatar jamesmunro-ul avatar jamesprovan-ul avatar jcorvinus avatar jdonald avatar juliaronnebergerul avatar lazloringuh avatar mattfiler avatar mattgrayuh2 avatar mattgrayul avatar maxpalmer-uh avatar protodeep avatar rblenkinsopp avatar robertevans-ul avatar rodolphehoudas-ul avatar rorygames avatar tarumuh-ul avatar testmasterbright avatar themunro avatar ul-burge avatar vabrador avatar xelarse avatar zalo avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

unityplugin's Issues

All Android files should be together

It is totally fine to have multiple different Plugins folders, and they do not need to be located at the root of the Assets. For the android files currently located in the root Plugins folder, we should move those to a new Plugins folder at Assets/LeapMotionModules/Android/Plugins

Investigate ways to profile time/memory on worker thread

Currently we have no way of easily profiling performance or garbage on the worker thread, which can make it difficult to track down issues. It would be nice to be able to have a nice process for this to be able to catch issues like #30 sooner.

LeapUnityExtensions need some fixing

FlipZ was changed to not flip at all. It should be set to (1, 1, -1).
ToUnityScaled() doesn't scale. In its current form, it is equivalent to ToVector3(), simply converting a Leap.Vector object to a Unity Vector3 object.

There are several uses of ToUnityScaled() in the Orion assets. These also need to be changed to ToVector3().

Hand misaligned to images in Unity Visualizer

If the service is not running when the scene is started, and then started, the hands and images become misaligned. Unity also throws an exception. This only seems to happen in the Visualizer scene, not, for example, the AR scene.

MissingReferenceException: The object of type 'LeapImageRetriever' has been destroyed but you are still trying to access it.
Your script should either check if it is null or you should not destroy the object.
UnityEngine.Component.GetComponentCamera
Leap.Unity.LeapImageRetriever.ApplyCameraProjectionValues () (at Assets/LeapMotion/Scripts/LeapImageRetriever.cs:351)
Leap.Unity.LeapImageRetriever.HandleOnValidCameraParams (CameraParams camParams) (at Assets/LeapMotion/Scripts/LeapImageRetriever.cs:287)
Leap.Unity.LeapVRCameraControl.OnPreCull () (at Assets/LeapMotion/Scripts/VR/LeapVRCameraControl.cs:81)

bugvisualizermissalignment

Judder when moving hands in VR

See https://community.leapmotion.com/t/judder-in-vr-when-using-rigged-hands/4712

Developer reports horrible judder when using SkeletalHand-based hand models. Hand motion itself is fine, the judder occurs when the camera is moving (controlled by head tracking).

This sounds similar to the problem we had some time ago and which was fixed by parenting the hand objects to the HandController. In this earlier issue, attaching the HandController to a moving object caused the hands to judder when ever the parent object moved.

Hand always reports it is invalid

The hand constructor never set _isValid to true.

The IsValid concept has been removed from LeapC in platform. Mark this fixed when LeapC code is next merged here.

HandDrop destination seems fairly random

The position to which the hand model returns when tracking is lost seems fairly random. It isn't the starting point in the scene and it isn't the first tracked position of the hand. Just holding a hand steady in the Leap field of view and then covering the leap with the other hand so that the tracking is abruptly lost will result in the tracked hand model "dropping" to different positions on successive repetitions.

There is also a problem when hand re-identification occurs. If the hand switches chirality, the old hand remains stuck in the position of the switch. Oddly, in this case, the destination is consistent -- it doesn't move at all.

GetFixedFrame transforms more frames than it needs to

The current implementation of LeapProvider.GetFixedFrame calls GetTransformedFrame every time it obtains a new frame inside the inner loop. All but one of these frames is going to be discarded, and so the transformation is wasteful. It should acquire un-transformed frame objects, and only transform the once that is selected.

RigidHand prefabs don't scale well

If you scale the a parent of the hand objects, the capsule colliders get over scaled: https://community.leapmotion.com/t/unity-orion-physics-model-to-big/4752

In addition, the palm object's collider is set to be a few meters in size and then scaled down by its transform. This, apparently, leads to problems with interactions involving Unity physics: https://community.leapmotion.com/t/scaled-palm-bug/4816. Setting the proper size for the collider (in mm) and resetting the scale to (1,1,1) fixes the over scaling problem for the palm.

Make Abstract class for LeapProvider

We should add an abstract base for LeapProvider, that way we can provide alternate ways to provide frames into the scene. Currently there is no way to play back recordings for example.

Physics hands separate from graphics hands

See this post: https://community.leapmotion.com/t/unity3d-orion-rigidhand-not-following-capsulehand-during-movement/4780

"I have a project setup where I interact with the controls inside of a spaceship using Orion.
Problem is that the RigidHand hitbox does not follow the model of the hand as it should when the ship starts moving forward.

When the ship is idle everything works perfectly, but as soon as it starts moving, the RigidHand always drags up behind. Problem is probably due to a simple timing between updating the model of the hand and its hitboxes."

GetLeapMatrix does not belong in UnityMatrixExtension

UnityMatrixExtension by it's name is for extension methods, which GetLeapMatrix is not. Either we should move GetLeapMatrix to a different class, or rename UnityMatrixExtension to allow non-extension methods to make sense inside it.

Add custom editor helper

In our custom editor scripts we often keep doing similar tasks. For example: Specifying a custom editor for a single variable, or hiding/showing a field based on a condition.

I feel that we can consolidate these separate efforts into a single subclass of Editor to both reduce boilerplate and reduce errors.

Add component for notifying the user about disabled Images

When an app wants images but is not receiving them, we should be able to display a warning to the user warning them that the application will not function correctly until images are enabled. Optionally, we might be able to provide some sort of interface (a button for example) to enable images for the app for the duration of the application.

Leap.Finger.TransformedCopy doesn't propagate the fingerId correctly

The Finger constructor sets

_id = (handId *10) + fingerId

The fingerId itself is not stored in the Finger class. Later, when TransformedCopy is called, this _id is passed as fingerId to the constructor, which once again adds handId * 10.
The result is that the Id of the transformed copy is different from the original object.

PlugInLeapNotice prefab is broken

3 things:

  1. On the LeapC side, IsServiceConnected isn't working because of a bug in LeapC. This has been fixed in platform. -- the fix should be in the assets by now.
  2. I am getting null object errors when the prefab is in the scene, so it seems that something might be missing from the prefab? -- further investigation reveals that at some point, some code was changed to expect a UI.Image instead of GUITexture, but other scripts still expect GUITexture.
  3. We shouldn't need to check for a connection every frame. Probably a coroutine that runs every couple of seconds is more efficient.

There is no tracking in built scenes.

Using the most recent develop core assests and the develop service as of 3/9/16 tracking appears not to work in built scenes.

This issue also occurs when using the public builds of the service.

Remove ToUnity and ToUnityScaled

Currently ToUnity and ToUnityScaled don't do anything different than ToVector3. Either they should be changed so that they have a use, or they should be removed.

Capsule hand wrist collapses at scale .3 or less

At a scale of .3 or less, the two wrist spheres collapse to the same location (the palm becomes a triangle rather than a rectangle). The rigid hand palm also stops rotating with the hand.

capsulehandcollapse

The lack of palm collider rotation is probably an error with the quaternion conversion --also getting this error:

Look rotation viewing vector is zero
UnityEngine.Quaternion:LookRotation(Vector3, Vector3)
Leap.Unity.UnityMatrixExtension:Rotation(Matrix) (at Assets/LeapMotion/Scripts/Utils/LeapUnityExtensions.cs:54)
Leap.Unity.HandModel:GetPalmRotation() (at Assets/LeapMotion/Scripts/Hands/HandModel.cs:99)
Leap.Unity.RigidHand:UpdateHand() (at Assets/LeapMotion/Scripts/Hands/RigidHand.cs:37)
Leap.Unity.HandProxy:UpdateRepresentation(Hand, ModelType) (at Assets/LeapMotion/Scripts/HandProxy.cs:43)
Leap.Unity.LeapHandController:UpdateHandRepresentations(Dictionary`2, ModelType, Frame) (at Assets/LeapMotion/Scripts/LeapHandController.cs:111)
Leap.Unity.LeapHandController:FixedUpdate() (at Assets/LeapMotion/Scripts/LeapHandController.cs:85)


The CapsuleHands class is throwing a similar, but independent error, which probably causes the wrist issue:

Look rotation viewing vector is zero
UnityEngine.Quaternion:LookRotation(Vector3, Vector3)
Leap.Unity.CapsuleHand:updateCapsules() (at Assets/LeapMotion/Scripts/Hands/CapsuleHand.cs:175)
Leap.Unity.CapsuleHand:UpdateHand() (at Assets/LeapMotion/Scripts/Hands/CapsuleHand.cs:101)
Leap.Unity.HandProxy:UpdateRepresentation(Hand, ModelType) (at Assets/LeapMotion/Scripts/HandProxy.cs:43)
Leap.Unity.LeapHandController:UpdateHandRepresentations(Dictionary`2, ModelType, Frame) (at Assets/LeapMotion/Scripts/LeapHandController.cs:111)
Leap.Unity.LeapHandController:Update() (at Assets/LeapMotion/Scripts/LeapHandController.cs:74)

Issues in Leap.Hand.Basis and Leap.Hand.TransformedCopy

There are two issues in this method:

//TODO verify this calculation for both hands
_basis.zBasis = -Direction;
_basis.yBasis = -PalmNormal;
_basis.xBasis = _basis.zBasis.Cross(_basis.yBasis);

The first is that, as the comment present in code suggests, the cross product must be different for each hand, if a left-handed basis is expected for left hands, and a right-handed basis is expected for right hands.
The second is much more subtle. When you call the method Hand.TransformedCopy, a new Hand instance is created where the vectors Direction and PalmNormal are multiplied by a matrix, usually the LeapMatrix. Now, the LeapMatrix M, as currently provided by the method Controller.GetLeapMatrix, has a reflection on the Z axis, and thus we have that:

M(-Direction x -PalmNormal) != M(-Direction) x M(-PalmNormal)

Which is to say that the value of Hand.TransformedCopy(...).Basis.xBasis is wrong.

The following snippet illustrates the issue:

      Matrix leapMat = GetLeapMatrix();
      Frame frame = leap_controller_.Frame(); 
      Frame transformed = frame.TransformedCopy( leapMat );

      if (frame.Hands.Count > 0)
      {
          Assert.AreEqual(
              // _M_(-Direction x -PalmNormal)
              leapMat.TransformDirection(frame.Hands[0].Basis.xBasis).Normalized,

              // _M_(-Direction) x _M_(-PalmNormal)
              transformed.Hands[0].Basis.xBasis
              );
      }

The assertion always fails.

Switch to using text meta files

We should be using text meta files instead of binary. It will reduce repository size in the long run because we will only need to store patches upon commit instead of recommitting the entire binary file each time. It will also make merges easier for things like scenes or prefabs. It also makes it easier to tell what kind of modifications have been made to an object, since the format is fairly descriptive.

GetFixedFrame does not calculate timeline offset properly.

The timeline synchronization method previously used in HandController has not been properly ported over to LeapProvider.

There is a inspector-side variable called PerFrameFixedUpdateOffset but I am not sure why it exists. It is a constant value being passed into a smoothing structure (which can do nothing with a constant) and then used to calculate the correctedTimestamp. As far as I can see this is causing the physics hands to behave strangely and lag behind the graphical hands.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.