mouse-gesture

マウス / ポインターの軌跡をジェスチャーとして認識し、軌跡プレビューを描画するための TypeScript ユーティリティです。

GitHub: https://github.com/Mekann2904/mouse-gesture

npm install @mekann2904/mouse-gesture

特徴

• ポインター軌跡を U, D, L, R の方向シーケンスとして認識
• [x, y] と { x, y } の両方の点形式に対応
• ジェスチャー文字列のバリデーション
• ジェスチャーを矢印表示に変換
• プレビュー用に軌跡を正規化
• SVG 文字列または Canvas へ軌跡を描画
• 認識後のきれいな正規化済みアニメーション SVG を生成
• ランタイム依存なし

基本的な使い方

import {
  recognizeMouseGesture,
  mouseGestureArrows,
  validateMouseGestureSequence,
} from '@mekann2904/mouse-gesture';

const points = [
  [0, 0],
  [40, 0],
  [40, 40],
];

const gesture = recognizeMouseGesture(points);

console.log(gesture); // "RD"
console.log(mouseGestureArrows(gesture)); // "→ ↓"
console.log(validateMouseGestureSequence(gesture));
// { valid: true, code: "ok", message: "OK" }

SVG で軌跡を描画する

import { mouseGestureTrailSvg } from '@mekann2904/mouse-gesture';

const svg = mouseGestureTrailSvg(
  [[0, 0], [40, 0], [40, 40]],
  {
    width: 320,
    height: 180,
    padding: 24,
    stroke: '#ff0d00',
  },
);

document.body.innerHTML = svg;

認識後の正規化済みアニメーションを表示する

import { animatedMouseGestureTrailSvg } from '@mekann2904/mouse-gesture';

const svg = animatedMouseGestureTrailSvg(
  [[0, 0], [1, 0], [1, 1]],
  {
    width: 320,
    height: 180,
    padding: 24,
    backgroundStroke: '#94a3b8',
    durationMs: 2400,
  },
);

ユーザーが描いた生の軌跡をそのまま見せ続けるのではなく、認識できたジェスチャーをきれいな標準形状に置き換えて表示したいときに使えます。

ブラウザサンプル

リポジトリには Vite 製のブラウザサンプルがあります。これは npm パッケージには含めていません。

cd examples/browser
npm install
npm run dev

サンプルでは、ドラッグ中はユーザーが描いた生の軌跡を表示し、マウスを離して認識できたら、正規化されたきれいなジェスチャー形状に置き換えます。

API 概要

主な exports:

• recognizeMouseGesture(points, options?)
• validateMouseGestureSequence(sequence, options?)
• mouseGestureArrows(sequence, separator?)
• normalizeMouseTrace(points, options?)
• mouseGestureTrailPath(points, options?)
• mouseGestureTrailSvg(points, options?)
• animatedMouseGestureTrailSvg(points, options?)
• drawMouseGestureTrail(canvasContext, points, options?)
• parsePointList(input)
• serializePointList(points)

recognizeGesture, gestureTrailSvg, animatedGestureTrailSvg など、mouse という名前を含まない汎用 alias も export しています。

認識仕様

• マンハッタン距離がしきい値未満の隣接点は無視します。
• 同じ方向が連続した場合は 1 つにまとめます。
• デフォルトでは 4 方向を超えるシーケンスは認識失敗として空文字を返します。
• 画面座標に合わせて、Y が正方向に増える移動は D として扱います。

recognizeMouseGesture([[0, 0], [20, 0], [20, 20]]); // "RD"
recognizeMouseGesture([[0, 0], [2, 2], [20, 2]]); // "R"

オプション:

recognizeMouseGesture(points, {
  maxDirections: 4,
  minSegmentManhattanDistance: 8,
});

バリデーション

デフォルトでは予約済みジェスチャーはありません。

validateMouseGestureSequence('DRUL').valid; // true

アプリ側で予約済みジェスチャーを持ちたい場合は、明示的に渡してください。

validateMouseGestureSequence('DRUL', {
  reservedSequences: ['DRUL'],
});

型

import type {
  MouseGesturePoint,
  MouseGestureSequence,
  MouseGestureRecognitionOptions,
  MouseGestureTrailRenderOptions,
} from '@mekann2904/mouse-gesture';

開発

npm install
npm test
npm pack --dry-run

ライセンス

MIT