@svenflow/micro-handpose 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +98 -0
- package/package.json +3 -2
package/README.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# @svenflow/micro-handpose
|
|
2
|
+
|
|
3
|
+
Tiny, fast hand landmark detection for the browser. WebGPU-powered, zero dependencies.
|
|
4
|
+
|
|
5
|
+
- **57KB** JS (9KB gzipped) + 7.7MB weights (served via CDN)
|
|
6
|
+
- **2.2ms** median inference (455 FPS) — ~2x faster than MediaPipe
|
|
7
|
+
- **21 landmarks** per hand, 100% identical output to the PyTorch reference
|
|
8
|
+
- TypeScript types included
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npm install @svenflow/micro-handpose
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Usage
|
|
17
|
+
|
|
18
|
+
```typescript
|
|
19
|
+
import { createHandpose } from '@svenflow/micro-handpose'
|
|
20
|
+
|
|
21
|
+
const handpose = await createHandpose()
|
|
22
|
+
const result = await handpose.detect(canvas)
|
|
23
|
+
|
|
24
|
+
if (result) {
|
|
25
|
+
console.log(result.score) // 0.99
|
|
26
|
+
console.log(result.handedness) // 'left' | 'right'
|
|
27
|
+
console.log(result.landmarks) // 21 { x, y, z } points
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
// Clean up GPU resources when done
|
|
31
|
+
handpose.dispose()
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## API
|
|
35
|
+
|
|
36
|
+
### `createHandpose(options?): Promise<Handpose>`
|
|
37
|
+
|
|
38
|
+
Creates and initializes the detector. Downloads weights and compiles the WebGPU pipeline. Call once, then reuse.
|
|
39
|
+
|
|
40
|
+
#### Options
|
|
41
|
+
|
|
42
|
+
| Option | Type | Default | Description |
|
|
43
|
+
|--------|------|---------|-------------|
|
|
44
|
+
| `weightsUrl` | `string` | jsdelivr CDN | Base URL for `weights.json` and `weights.bin`. Set this to self-host weights. |
|
|
45
|
+
| `scoreThreshold` | `number` | `0.5` | Minimum confidence to return a detection (0-1). |
|
|
46
|
+
|
|
47
|
+
### `handpose.detect(source): Promise<HandposeResult | null>`
|
|
48
|
+
|
|
49
|
+
Runs inference on an image source. Returns `null` if no hand is detected.
|
|
50
|
+
|
|
51
|
+
**Accepted input types:** `HTMLCanvasElement`, `OffscreenCanvas`, `ImageBitmap`, `HTMLImageElement`, `HTMLVideoElement`, `ImageData`
|
|
52
|
+
|
|
53
|
+
#### `HandposeResult`
|
|
54
|
+
|
|
55
|
+
```typescript
|
|
56
|
+
{
|
|
57
|
+
score: number // Confidence (0-1)
|
|
58
|
+
handedness: 'left' | 'right'
|
|
59
|
+
landmarks: Landmark[] // 21 points
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Each `Landmark` has `x`, `y` (normalized image coordinates, 0-1) and `z` (relative depth).
|
|
64
|
+
|
|
65
|
+
The 21 landmarks follow MediaPipe ordering: `wrist`, `thumb_cmc`, `thumb_mcp`, `thumb_ip`, `thumb_tip`, `index_mcp` ... `pinky_tip`.
|
|
66
|
+
|
|
67
|
+
### `handpose.dispose(): void`
|
|
68
|
+
|
|
69
|
+
Releases GPU resources.
|
|
70
|
+
|
|
71
|
+
## Self-hosting weights
|
|
72
|
+
|
|
73
|
+
By default, weights are fetched from jsdelivr CDN. To self-host:
|
|
74
|
+
|
|
75
|
+
```typescript
|
|
76
|
+
const handpose = await createHandpose({
|
|
77
|
+
weightsUrl: '/models/handpose'
|
|
78
|
+
})
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The detector expects `weights.json` and `weights.bin` at that path.
|
|
82
|
+
|
|
83
|
+
## Browser requirements
|
|
84
|
+
|
|
85
|
+
Requires [WebGPU](https://webgpureport.org). Supported in Chrome 113+, Edge 113+, and Firefox Nightly.
|
|
86
|
+
|
|
87
|
+
## Performance
|
|
88
|
+
|
|
89
|
+
Benchmarked on Apple M2:
|
|
90
|
+
|
|
91
|
+
| | Median | p99 |
|
|
92
|
+
|---|---|---|
|
|
93
|
+
| **micro-handpose** | 2.2ms | 3.1ms |
|
|
94
|
+
| MediaPipe (WASM) | 4.5ms | 8.2ms |
|
|
95
|
+
|
|
96
|
+
## License
|
|
97
|
+
|
|
98
|
+
MIT
|
package/package.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"publishConfig": {
|
|
4
4
|
"access": "public"
|
|
5
5
|
},
|
|
6
|
-
"version": "0.1.
|
|
6
|
+
"version": "0.1.1",
|
|
7
7
|
"description": "Tiny, fast hand landmark detection. WebGPU-powered, 2ms inference, zero dependencies.",
|
|
8
8
|
"type": "module",
|
|
9
9
|
"main": "dist/index.js",
|
|
@@ -38,7 +38,8 @@
|
|
|
38
38
|
},
|
|
39
39
|
"files": [
|
|
40
40
|
"dist",
|
|
41
|
-
"weights"
|
|
41
|
+
"weights",
|
|
42
|
+
"README.md"
|
|
42
43
|
],
|
|
43
44
|
"sideEffects": false,
|
|
44
45
|
"license": "MIT"
|