Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/adarosecannon/handy-work

Framework Agnostic Hand tracking for WebXR
https://github.com/adarosecannon/handy-work

aframe hand-tracking threejs webxr

Last synced: 12 days ago
JSON representation

Framework Agnostic Hand tracking for WebXR

Host: GitHub
URL: https://github.com/adarosecannon/handy-work
Owner: AdaRoseCannon
License: mit
Created: 2021-06-18T12:37:14.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2024-02-23T09:21:50.000Z (11 months ago)
Last Synced: 2024-10-29T13:52:39.196Z (3 months ago)
Topics: aframe, hand-tracking, threejs, webxr
Language: JavaScript
Homepage: https://aframe-xr-starterkit.glitch.me/
Size: 2.99 MB
Stars: 94
Watchers: 6
Forks: 11
Open Issues: 8
Metadata Files:
- Readme: README-AFRAME.md
- License: LICENSE

Awesome Lists containing this project

README

# AFrame Handy Controls

The controls provide the ability to render hands and attach objects to individual joints.

It also fires events for when poses have been held for certain lengths of time.

The following are exposed on the component itself so you can hook into the library

* handyWorkUpdate
* dumpHands
* loadPose
* setPose
* getPose

Use the following properties to customise the component

Child entities with the `data-left`, `data-right` or `data-none` properties have their position and
rotation set to match the tracked points from the WebXR API:

`data-left` and `data-right` are used for tracked hands or controllers where the hardware has controllers
which are explicity handed. i.e. Oculus Quest. Some hardware has a single ambiguously handed controller
this will be exposed as `data-none` because it has no handedness. Screen based transient inputs will also
be exposed under `data-none`.

* grip (where someone would hold an object)
* ray (the target ray space from WebXR)
* screen-0 (1st transient input)
* screen-1 (2nd transient input)
* screen-2 (3rd transient input)
* screen-n ({n+1}th transient input)

* wrist
* thumb-metacarpal
* thumb-phalanx-proximal
* thumb-phalanx-distal
* thumb-tip
* index-finger-metacarpal
* index-finger-phalanx-proximal
* index-finger-phalanx-intermediate
* index-finger-phalanx-distal
* index-finger-tip
* middle-finger-metacarpal
* middle-finger-phalanx-proximal
* middle-finger-phalanx-intermediate
* middle-finger-phalanx-distal
* middle-finger-tip
* ring-finger-metacarpal
* ring-finger-phalanx-proximal
* ring-finger-phalanx-intermediate
* ring-finger-phalanx-distal
* ring-finger-tip
* pinky-finger-metacarpal
* pinky-finger-phalanx-proximal
* pinky-finger-phalanx-intermediate
* pinky-finger-phalanx-distal
* pinky-finger-tip

### Events

The component and each child emit events when they happen these events are

#### Standard WebXR API Events

* "select"
* "selectstart"
* "selectend"
* "squeeze"
* "squeezeend"
* "squeezestart"

#### Poses

* pose_[name]
* pose_[name]_fuseShort
* pose_[name]_fuseLong

Where name is one of the poses in `/poses`

You can see what the currently detected pose is by listening for `"pose"` events and inspecting `"event.detail.pose"`

#### Gamepad Events

These are very hardware dependent. If it is able to get access to the input profile data from the WebXR
input profiles repo then this will fire off events as named in that. Such as thumbstickmoved or a-buttondown x-buttonup.

Otherwise it will just fire events like button0down button0up or axes0moved

To find out what a particular piece of hardware is using listen for `"gamepad"` events and inspect the `event.detail.event`.

### Magnetic Actions

Add data-magnet is set to the classname for elements it's to be drawn to in a magnetic fashion so that when the joint approaches that element the whole hand will get pulled towards it and aligned with the element.

Only set 1 `data-magnet` per hand. You can configure the magnetic elements by setting their data-magnet range e.g. `data-magnet-range="0.2,0.1,120,80"`. Where the first number is where the magnetism starts and the second the range at which the hand is totally moved to the destination location. The second set of numbers are how aligned the hand needs to be before magnetism starts (degrees between 0 and 360) , where the second number is what counts as fully aligned. In that example, which is the default it will start approaching from 0.2m and if the hand is within 0.1m it will be placed on the `#sword` handle.

For physics systems it probably won't work well when you use magnet elements you probably want to use the real joint location, do declare an additional that a joint should ignore magnet effects add `data-no-magnet` to it.

The object currently attracting the controller will have it's ID noted on the `data-magnet` element as a `data-magnet-target` which you can read in JavaScript through the object's dataset.

The magnet finding function always picks the first element it detects in it's range. Not the closest element. You can
sort the order magnets are tested by setting the `data-magnet-priority` property on elements. The default value is `1` if you want it to be low priority set `data-magnet-priority="0"` or lower like `"-1"` fractions are fine too. If you want it to be higher priority set it to a higher number such as `data-magnet-priority="10"`.

```html

```

### Example use case:

```html

```

## Magnet Helpers

In `magnet-helpers.js` you can find a few helpful components for dealing with the magnetic behaviour for advanced hand interactions.

### linear-constraint

linear-constraint is designed to place the element it's attached to
place elements as close as possible to the target element whilst being restrained along a line
defined by the `axis`, between the `min` and `max` on either side of the original position
of the object when this component is first run.

This is useful for creating magnetic lines. Put linear-constraint on a magnetic element and set it's target
to the **non-magnet** version of the hand element with the data-magnet property. i.e. the same part but with `data-no-magnet`

Vector3
Vector3
| Property | Type | Description | Default |
| :------------------------ | :---------- | :--------------------------------------------------------------------------------- | :------------------- |
| axis | vec3 | Axis upon which the element is constrained, does not need to be normalized. | {"x":0,"y":0,"z":-1} |
| max | number | How far can it travel along the axis | Infinity |
| min | number | How far can it travel opposite to the axis | -Infinity |
| radius | number | Outside this distance it will not work | Infinity |
| useFixedValueIfOutOfRange | boolean | Should the object remain at a fixed position if out of the radius. | false |
| valueIfOutOfRange | number | Value the object should be set to if out of the radius | 0 |
| step | number | Steps it should take from the origin. | 0 |
| target | selectorAll | Element it should try to follow | |
| part | string | If applied to a 3D model this is the name of the part that should be used instead. | "" |
| enabled | boolean | Whether it should currently run or not | true |
| upEventName | string | Name of event to trigger when t is increasing | "" |
| upEventThreshold | number | Threshold to trigger up event | 0 |
| downEventName | string | Name of event to trigger when t is decreasing | "" |
| downEventThreshold | number | Threshold to trigger up event | 0 |

### attach-to-model

Each frame attach-to-model will move an object to the same position as part of the 3D model of it's parent element.

This is useful for attaching magnetic elements to moving elements of a 3D model so it can be grabbed in different ways.

| Type | Description | Default |
| :----- | :--------------------- | :------ |
| string | Name of part to follow | "" |

### grab-magnet-target

This should be added to the hand elements with the `data-magnet`.

When one of the `startEvents` events is fired it will start a grab action where it will
consider itself grabbing whatever magnetic item it is currently being attracted to and fires the "grabbed" event
on the object.

If the object has `data-pick-up` set then the object will be reparented to the hand element that fired
the grab event. The "pickup" event will be fired on the object.

If the object has `data-pick-up="parent"` set then the object's parent will be reparented to the hand element that fired
the grab event. The "pickup" event will be fired on the object's parent.

When either the release event is fired or the object stops being magnet target then it will consider itself released.
it will reparent objects back to where they were originally and fire the "putdown" event on what was held if it had been picked up.
If the held object has `data-reset-transform` set then it will also restore it's oriingal position. Otherwise the world position and rotation of the object will remain the same.

Finally the "released" event is fired on whatever was being held.