hand-guest-control 0.1.0 → 0.3.0

package/README.md

@@ -1,16 +1,6 @@
 # hand-guest-control
 
-Hand gesture detection and state management using MediaPipe landmarks. Extracted from `mn-hand-control`.
-
-## Demo UI (test package in browser)
-
-```bash
-cd npm/hand-guest-control
-npm install
-npm run demo
-```
-
-Open **http://localhost:5180** — webcam + live hand state overlay.
+Hand gesture detection and action mapping from MediaPipe landmarks. TypeScript types included.
 
 ## Install
 
@@ -18,70 +8,54 @@ Open **http://localhost:5180** — webcam + live hand state overlay.
 npm install hand-guest-control @mediapipe/tasks-vision
 ```
 
-Or local workspace link during development:
-
-```bash
-npm install ../npm/hand-guest-control
-```
-
 ## Usage
 
-### Core — gesture state machine
-
-```javascript
-import { HandStateManager, HAND_STATES } from 'hand-guest-control';
+```typescript
+import { HandStateManager, HAND_STATES, GESTURE_ACTIONS } from 'hand-guest-control';
+import { createHandLandmarker } from 'hand-guest-control/mediapipe';
 
 const manager = new HandStateManager({
-  rotationSensitivity: 4,
   waitingTimeout: 10000,
   startingDelay: 3000,
-  debug: false
+  swipeSource: 'index' // 'index' | 'wrist'
 });
 
-// landmarks from MediaPipe HandLandmarker
-const { state, rotation } = manager.processLandmarks(landmarks);
-
-if (state === HAND_STATES.OPEN) {
-  // zoom in
-}
-
-if (state === HAND_STATES.SWIPE_NEXT) {
-  // next item
-}
+const landmarker = await createHandLandmarker();
+const results = await landmarker.detectForVideo(videoCanvas, Date.now());
+const { state, primaryAction, actions, rotation, palmDirection } =
+  manager.processLandmarks(results.landmarks?.[0]);
 ```
 
-### MediaPipe helper
+## Default actions
+
+| Gesture | Action |
+|---------|--------|
+| Swipe left / right | `swipe_left` / `swipe_right` |
+| Open palm / closed fist | `zoom_out` / `zoom_in` |
+| Palm left / right / up / down | `rotate_left` / `rotate_right` / `rotate_up` / `rotate_down` |
+| Thumb up | `ok` |
+
+Override via `actionMap`. Set `mapActions: false` to get states only.
+
+## Config
+
+```typescript
+new HandStateManager({
+  swipeSource: 'index',
+  swipeMinRange: 0.03,
+  swipeCooldownMs: 2000,
+  palmDirectionThreshold: 0.025,
+  rotationActionThreshold: 0.5,
+  enableContinuousRotation: true,
+  mapActions: true,
+  actionMap: { /* partial override */ }
+});
+```
 
-```javascript
-import { createHandLandmarker } from 'hand-guest-control/mediapipe';
+Invalid config throws `ConfigValidationError`.
 
-const landmarker = await createHandLandmarker({
-  minHandDetectionConfidence: 0.6
-});
+## Exports
 
-const results = await landmarker.detectForVideo(videoElement, Date.now());
-const { state, rotation } = manager.processLandmarks(results.landmarks?.[0]);
-```
+`HandStateManager`, `HandGestureDetector`, `ActionMapper`, `mapGestureToAction`, `validateHandConfig`, `mergeHandConfig`, `HAND_STATES`, `GESTURE_ACTIONS`, `DEFAULT_CONFIG`, `DEFAULT_ACTION_MAP`, `createHandLandmarker`
 
-## API
-
-| Export | Description |
-|--------|-------------|
-| `HandStateManager` | Main state machine — `processLandmarks(landmarks)` → `{ state, rotation }` |
-| `HandGestureDetector` | Low-level gesture detection |
-| `HAND_STATES` | State constants (`open`, `closed`, `swipe_next`, …) |
-| `LANDMARKS` | MediaPipe landmark indices |
-| `HAND_CONNECTIONS` | Landmark pairs for debug drawing |
-| `DEFAULT_CONFIG` | Default configuration object |
-| `createHandLandmarker` | MediaPipe setup with GPU→CPU fallback |
-
-## Hand states
-
-- `not_detected` — no hand in frame
-- `waiting` — hand lost for extended period
-- `starting` — cooldown after re-detection
-- `open` — open palm (zoom)
-- `closed` — closed fist
-- `pointing` — index finger extended
-- `flipping` — middle finger gesture
-- `swipe_next` / `swipe_previous` — horizontal swipe while pointing
+Types: `HandConfig`, `GestureResult`, `HandState`, `GestureAction`, `Landmark`, `ActionMap`, …