mechanism-studio

Browser-based planar mechanism kinematics and curve synthesis studio.

mechanism-studio は、4節リンクとスライダクランクをブラウザ上で動かし、coupler point の軌跡を観察し、手描きやサンプルで与えた target curve に近い 4節リンクを探索する小規模スタジオです。

UI の見た目だけを整えたデモではなく、平面機構の position analysis、curve preprocessing、類似変換に対して頑健な評価関数、restart 付きの確率的探索、Web Worker による非同期実行までを一つのリポジトリにまとめています。

Preview

同梱している sample は次の 3 つです。

• bean-loop : 閉曲線。full rotation を含む coupler curve の探索デモ向き
• near-line : 開曲線。直線に近い区間を狙う classic な題材
• wiper-arc : 開曲線。ワイパーのような rocker motion の確認向き

このリポジトリで見せたいこと

• 幾何拘束を pure function として実装する力
• 数値探索を UI と Worker に分離して組み込む力
• 可視化しながらアルゴリズムの前提と限界を説明する力
• 依存を増やしすぎずに最後まで完成させる力

主な機能

• 4節リンクの作図、closure 切り替え、アニメーション、coupler curve 表示
• スライダクランクの作図、tracer point 軌跡表示
• target curve の手描き入力
• sample curve のワンクリック読み込み
• 現在の軌跡をそのまま target にする機能
• 4節リンク寸法と coupler point を探索する optimizer
• target に合わせた similarity alignment overlay
• 上位候補の比較と即時適用
• target.json / trajectory.csv / state.json / scene.svg の書き出し
• open / closed を保った scene.svg の export
• target.json の再読み込み
• Node 組み込みテストランナーによる 14 件のテスト

まず触るときの流れ

1. npm run dev で起動する
2. bean-loop か near-line を読み込む
3. 探索を開始 を押して候補を待つ
4. 上位候補を適用して、元の軌跡との差を見比べる

この順で触ると、「機構の forward kinematics」と「curve synthesis の近似探索」がどうつながっているかが追いやすいです。

セットアップ

依存パッケージはありません。Node.js 18 以上だけで動きます。

npm run dev

起動後に http://localhost:4173 を開いてください。

テスト

npm test

静的チェックとテストをまとめて走らせる場合は次です。

npm run verify

探索器の挙動を同梱 sample でまとめて確認する benchmark は次です。複数回流してばらつきを見たいときは --runs を付けます。

npm run benchmark
node scripts/benchmark.mjs --preset=quick --runs=2 --format=markdown

使い方

1. 機構を動かす

左側パネルで 4節リンク または スライダクランク を選び、リンク長や tracer point を調整します。再生 を押すと入力角が連続更新されます。

2. target curve を作る

次のいずれかで target を用意できます。

• scene 上で手描きする
• 同梱 sample を読み込む
• 現在の軌跡をそのまま target にする
• target.json を読み込む

3. 探索する

4節リンク を選んだ状態で 探索を開始 を押すと、Worker が候補を返します。Quick / Balanced / Deep / Exhaustive の preset で探索の重さを切り替えられます。Balanced 以上では restart を複数回走らせ、最後に高サンプルで再評価します。結果カードからその場で候補を適用できます。

検証メモ

同梱 sample に対する benchmark 結果は benchmark-report.md に置いています。closed target は cyclic shift を含む比較になるため、open target より計算が重くなります。

理論背景として確認した資料は references.md にまとめています。README だけでは説明しきれない前提を後追いできるようにしました。

2〜3 分でコードを追うなら

最初に見る場所は次の 5 つです。

1. src/domain/fourbar/kinematics.js — 4節リンクの position analysis
2. src/domain/curve/score.js — curve preprocessing と score
3. src/domain/optimization/search.js — ヒューリスティック探索
4. src/workers/optimizer.worker.js — UI スレッドからの分離
5. src/ui/scene.js — SVG scene の描画、alignment overlay、export

この順で読むと、幾何拘束から UI までの流れが追いやすくなります。

ディレクトリ構成

mechanism-studio/
├─ README.md
├─ index.html
├─ package.json
├─ public/
│  ├─ previews/
│  │  ├─ bean-loop.png
│  │  ├─ near-line.png
│  │  └─ wiper-arc.png
│  └─ samples/
│     ├─ bean-loop.json
│     ├─ near-line.json
│     └─ wiper-arc.json
├─ scripts/
│  ├─ benchmark.mjs
│  ├─ check.mjs
│  └─ dev-server.mjs
├─ src/
│  ├─ app/
│  │  ├─ defaults.js
│  │  ├─ derived.js
│  │  ├─ optimization-presets.js
│  │  ├─ sample-presets.js
│  │  └─ store.js
│  ├─ domain/
│  │  ├─ common/
│  │  ├─ curve/
│  │  ├─ fourbar/
│  │  ├─ optimization/
│  │  └─ slidercrank/
│  ├─ styles/
│  │  └─ app.css
│  ├─ ui/
│  │  ├─ scene.js
│  │  └─ templates.js
│  ├─ workers/
│  │  └─ optimizer.worker.js
│  └─ main.js
├─ docs/
│  ├─ architecture.md
│  ├─ benchmark-report.md
│  ├─ design-decisions.md
│  ├─ math-model.md
│  ├─ optimization.md
│  ├─ references.md
│  └─ test-plan.md
└─ tests/
   ├─ curve-io.spec.js
   ├─ curve-score.spec.js
   ├─ curve-svg.spec.js
   ├─ curve-transform.spec.js
   ├─ derived.spec.js
   ├─ fourbar.spec.js
   ├─ grashof.spec.js
   ├─ optimizer-smoke.spec.js
   └─ search-progress.spec.js

設計上のポイント

UI と計算コアを分離

• src/domain/ に機構学、曲線処理、探索を集約
• src/ui/ は HTML と SVG の描画に専念
• src/workers/optimizer.worker.js で探索を UI スレッドから分離

これにより、テストは domain を直接 import して実行できます。

4節リンクの position analysis

入力クランク角を与え、

1. 入力リンク先端 A を求める
2. A 中心の円と O4 中心の円の交点から B を選ぶ
3. AB 上の局所座標 (couplerLocalX, couplerLocalY) を world 座標へ変換する

という流れで coupler point を求めています。重いソルバや外部ライブラリは使っていません。

curve scoring

自由描画の生点列はばらつくので、そのまま比較しません。比較前に次を行っています。

• polyline の簡略化
• 弧長ベースの再サンプリング
• 重心合わせ
• スケール正規化
• 最適回転の推定
• 閉曲線では cyclic shift、開曲線では逆順比較も考慮

score は位置・回転・スケールの違いにある程度鈍感です。その代わり、scene では similarity alignment overlay を使って候補軌跡と mechanism を target に重ねて表示します。

optimizer

optimizer は厳密解法ではなく、best + differential + noise 型の確率的探索です。単発実行だけだと seed に引っ張られやすいため、現在は restart ensemble を回し、最後に高サンプルで再評価してから上位候補を返します。実装を複雑にしすぎず、UI から観察可能な範囲で十分な候補を返すことを優先しました。

制約

• 力、トルク、慣性を扱う dynamics simulator ではありません
• optimizer の対象は 4節リンクのみです
• 一般的な SVG path import には対応していません
• CAD 互換の拘束編集や干渉判定はありません
• 閉曲線探索は full rotation を前提とした評価になっています
• fit は similarity-invariant な shape score であり、scene 上では overlay 用の alignment を別途適用しています

今後の改善案

• target curve の SVG path import
• 同一 target に対する候補の重ね描きビュー
• 複数 closure の mini preview 比較
• 同一 coupler curve を描く cognate mechanism の表示
• open curve の方向拘束や部分区間拘束

ドキュメント

• architecture.md
• benchmark-report.md
• design-decisions.md
• math-model.md
• optimization.md
• references.md
• test-plan.md