# mmodeler の使い方

[English](README.en.md) | 日本語

![mmodeler](./mmodeler.jpg)

## 概要
mmodeler は、スマートフォンやタブレットのタッチ操作に最適化した、Blender風の3Dモデリングツールです。WebGPU と JavaScript で構築されており、直感的なジェスチャー操作によって、カメラ制御、オブジェクト編集、プリミティブ追加、ファイルの保存・読込に加えて、スカルプトモードによる自由な形状変形が行えます。

## 実行方法
- 実行ファイルは [./mmodeler.html](./mmodeler.html) です

mmodelerはwebgと同梱のコードで動作し、起動後の編集と保存はローカル環境で完結します。

ここから実行できます。
[https://jun-mizutani.github.io/webg/samples/mmodeler.html](https://jun-mizutani.github.io/webg/samples/mmodeler.html)

## モバイル操作体系
本ツールでは、編集画面（キャンバス）上での操作を以下のジェスチャーに割り当てています。PCではマウスで同様の操作が可能です。

### 基本ジェスチャー
最も重要な操作は、図形部分のダブルタップです。 ダブルタップすることでコマンドパレットが開いて多くの操作を実行できます。

- **1本指ドラッグ**: カメラの回転（オービット）
- **2本指ドラッグ**: カメラの平行移動（パン）
- **2本指回転**: ビューのロール回転。指で検出した回転角度の符号を反転し、現在の view 軸まわりにオービット姿勢として蓄積します。
- **ピンチ操作**: カメラのズーム
- **短いタップ**: 
    - オブジェクトモード：オブジェクトを選択。
    - 編集モード：ツールに応じて頂点または面を選択。
    - 頂点追加ツール中：タップ位置に頂点を追加。
- **ダブルタップ**: コマンド選択の基本操作
    - **図形上の場合**: 現在の選択状態を維持したままコマンドパレットを展開します。
    - **何もない領域の場合**: 矩形選択（ボックス選択）の準備状態になります（頂点数0のシーンではコマンドパレットを開きます）。
    - **Sculpt Mode 中の何もない領域の場合**: カメラ操作とブラシ操作を切り替えます。
- **長押し**:
    - **Object / Edit Mode の図形上**: モード切り替え（オブジェクトモード $\leftrightarrow$ 編集モード）を行います。
    - **Object / Edit Mode の何もない領域**: `Info` ボタンと同じ object info overlay を開きます。
    - **Sculpt Mode の図形上**: 現在のモードを保ち、ブラシ操作を続けます。
    - **Sculpt Mode の何もない領域**: `Brsh` と同じブラシ設定 overlay を開きます。
- **上方向フリック**: ビュー dock またはキャンバス下端から上へ素早くスワイプすると、「スカルプトモード」へ移行します。

### 特殊ボタン：左上の「↑」ボタン
このボタンはモードによって役割が変わります。
- **オブジェクト/編集モード**: **「追加選択（Shift相当）」**。ONの間はタップで選択を追加でき、選択済み要素を再度タップすると選択解除されます。
- **スカルプトモード**: **「ブラシ有効化（Armed）」**。ONの間だけ、1本指ドラッグがブラシによる変形操作になります。OFFの間はカメラ操作が優先されます。

## コマンドパレット
ダブルタップで表示される 4x4 のグリッドメニューです。Object / Edit Mode では `Next` ボタンで計4ページのメニューを切り替えて使用します。スカルプトモード では、ブラシ操作に絞った専用の1ページパレットに切り替わります。パレットは操作位置を妨げないよう、画面中心からの相対位置に基づいて自動的に配置されます。

### 第1ページ：基本編集と軸制限
基本的な変形コマンドと、変形時の軸制限オプションを配置しています。

![第1ページ: 基本編集と軸制限](./mm01.jpg)

| ボタン | 解説 |
| --- | --- |
| `G` | **移動**: 選択中のオブジェクト、面、頂点を移動します。ボタン押下後、画面を1本指でドラッグして位置を確認し、短いタップで確定します。 |
| `E` | **押し出し**: 編集モードで選択中の面または頂点を押し出します。ドラッグで移動量を調整します。 |
| `Vert` | **頂点選択モード**: 編集モードの選択対象を「頂点」に切り替えます。頂点単位の移動、削除、追加、ループ選択に使用します。 |
| `X` | **X軸制限**: 次に実行する変形操作（G/R/S/E/GG）の方向をワールドX軸に制限します。もう一度押すと制限なし（Free）に戻ります。 |
| `R` | **回転**: 選択中のオブジェクト、面、頂点を回転させます。ドラッグで角度を確認し、タップで確定します。 |
| `GG` | **エッジスライド**: 選択頂点が2つの隣接頂点に挟まれた中点である場合、そのエッジの直線上でスライドさせます。 |
| `Face` | **面選択モード**: 編集モードの選択対象を「面」に切り替えます。面の押し出し、削除、ループカットなどを実行できます。 |
| `Y` | **Y軸制限**: 次に実行する変形操作（G/R/S/E/GG）の方向をワールドY軸に制限します。もう一度押すと制限なし（Free）に戻ります。 |
| `S` | **拡大縮小**: 選択中のオブジェクト、面、頂点をスケールさせます。ドラッグで倍率を確認し、タップで確定します。 |
| `Cut` | **ループカット**: 編集モードで選択した四角面を分割します。単一の面を選択している場合は、プレビュー線を見ながら方向を選択します。 |
| `Undo` | **元に戻す**: 直前の編集操作（変形、プリミティブ追加、削除など）を1つ取り消します。 |
| `Z` | **Z軸制限**: 次に実行する変形操作（G/R/S/E/GG）の方向をワールドZ軸に制限します。もう一度押すと制限なし（Free）に戻ります。 |
| `Next` | 次のページへ切り替えます。 |
| `Chain` | **チェーン選択**: 選択頂点から隣接エッジの方向を選び、四角面だけでつながる頂点列をタップで確定選択します。 |
| `Redo` | **やり直し**: `Undo` で戻した操作を再度実行します。 |
| `N` | **法線制限**: 編集モードで、選択面の平均法線方向、または選択頂点周辺の平均法線方向へ変形を制限します。もう一度押すと制限なしに戻ります。 |

### 第2ページ：選択・表示切替・Sculpt 入口

![第2ページ: 選択・細分化・表示切替](./mm02.jpg)

| ボタン | 解説 |
| --- | --- |
| `Catm` | **Catmull-Clark細分化**: メッシュ全体を滑らかに細分化し、丸みのある形状にします。 |
| `A` | **全選択**: オブジェクトモードでは全オブジェクトを、編集モードでは全頂点または全面を選択します。 |
| `Add` | **頂点追加 / 面作成**: 3〜4個の頂点を選択中なら面を作成し、それ以外ではタップ位置に頂点を追加するツールに切り替わります。 |
| `Pr` | **投影切替**: 透視投影（Perspective）と平行投影（Orthographic）を切り替えます。正確な位置合わせには平行投影が便利です。 |
| `Subd` | **細分化**: 四角面のみのメッシュを1段階細分化し、面構造を保ったままポリゴン密度を上げます。 |
| `Inv` | **選択反転**: 現在の選択状態を反転させます。 |
| `Del` | **削除**: 選択中のオブジェクト、頂点、または面を削除します。 |
| `Wire` | **ワイヤーフレーム表示**: 表示を切り替えます。ONの間は、裏側にある頂点も選択対象になります。 |
| `M` | **Xミラー**: X=0 を基準としたミラー編集を有効にします。 |
| `Half` | **半分選択**: X座標が0より小さい側の要素を選択します。片側削除やミラー編集の準備に使用します。 |
| `Sclpt` | **Sculpt Mode**: スカルプトモードに入り、法線方向へ膨らませる Draw ブラシを選びます。Sculpt Mode に入った後は専用パレットからブラシ種類や方向を切り替えます。 |
| `Smth` | **スムーズシェーディング**: 陰影表示を滑らかに切り替えます。形状（頂点構造）は変えず、見た目だけを滑らかにします。 |
| `Lens` | **レンズプリセット**: カメラの画角（広角・標準・望遠）を切り替えて見え方を確認できます。 |
| `Next` | 次のページへ切り替えます。 |
| `Loop` | **ループ選択**: ループカットで作成された中点頂点から、カットライン方向に沿って頂点列を選択します。 |

### 第3ページ：ファイル操作・情報

![第3ページ: ファイル操作・オブジェクト管理](./mm03.jpg)

| ボタン | 解説 |
| --- | --- |
| `Load` | **読み込み**: ローカルファイルからモデルファイルや保存済み ModelAsset JSON を読み込みます。 |
| `O` | **原点リセット**: 選択中オブジェクトの原点（Origin）をワールド原点へ戻します。形状は維持したまま基準点のみを整えます。 |
| `Cood` | **座標表示**: 編集モードで選択中の頂点座標をオーバーレイ表示します。単一頂点選択時は直接数値を入力して更新可能です。 |
| `Info` | **情報表示**: 選択オブジェクトのサイズ（バウンディングボックス）、頂点数、ポリゴン数、原点を表示します。タップで閉じます。 |
| `Json` | **JSON保存**: 現在のシーンを gzip 圧縮済み JSON (`.json.gz`) として保存します。再編集に最適な形式です。 |
| `Shot` | **スクリーンショット**: 現在の表示画面を画像として保存します。 |
| `Glb` | **GLB保存**: 現在のシーンを GLB 形式で書き出します。他の3Dツールやビューアで利用可能です。 |
| `Join` | **統合**: オブジェクトモードで選択中の2つ以上のオブジェクトを1つにまとめます。 |
| `Next` | 次のページへ切り替えます。 |
| `New` | **新規作成**: 現在のシーンを破棄し、空のシーンから開始します。 |

### スカルプトモード専用ページ：ブラシ操作

スカルプトモード中は以下の専用1ページを表示します。

![Sculpt Mode 専用ページ](./mm05.jpg)

| ボタン | 解説 |
| --- | --- |
| `Draw` | **Drawブラシ**: 頂点を法線方向へ移動します。`Sclp+` では膨らみ、`Sclp-` では凹みます。 |
| `Brsh` | **ブラシ設定**: 半径、強度、減衰形状を overlay で編集します。 |
| `Pr` | **投影切替**: 透視投影と平行投影を切り替えます。 |
| `Blur` | **Blurブラシ**: 近傍頂点の平均位置へ近づけ、表面をならします。 |
| `M` | **Xミラー**: Sculpt のブラシ変形を X=0 基準で対称適用します。 |
| `Wire` | **ワイヤーフレーム表示**: 表示を切り替えます。 |
| `Grab` | **Grabブラシ**: カーソルの移動方向へ頂点を引っ張ります。 |
| `Sclp+` | **正方向**: Draw / Pinch などの符号を正方向にします。 |
| `Undo` | **元に戻す**: 直前の stroke や編集操作を取り消します。 |
| `Smth` | **スムーズシェーディング**: 表示上の陰影を滑らかにします。 |
| `Pinch` | **Pinchブラシ**: 頂点をカーソル中心へ寄せます。 |
| `Sclp-` | **負方向**: Draw / Pinch などの符号を負方向にします。 |
| `Redo` | **やり直し**: `Undo` で戻した操作を再実行します。 |
| `Edit` | **編集モードへ戻る**: スカルプトモードから編集モードへ戻ります。 |

### 第4ページ：プリミティブ追加と分割数

![第4ページ: プリミティブ追加と分割数](./mm04.jpg)

| ボタン | 解説 |
| --- | --- |
| `Cube` | **立方体**: 中心に原点を持つ立方体を追加します。 |
| `Torus` | **トーラス**: ドーナツ状の形状を追加します。分割数設定がリングとチューブの密度に反映されます。 |
| `Ball` | **球体**: 中心に原点を持つ球体を追加します。分割数設定が経緯度の密度に反映されます。 |
| `DCone` | **二重円錐**: 上下に頂点を持つ円錐を追加します。中心のリングが原点高さに配置されます。 |
| `Cyl` | **円柱**: 中心に原点を持つ円柱を追加します。分割数設定が円周の密度に反映されます。 |
| `Cone` | **円錐**: 円錐を追加します。底面と頂点の中間がオブジェクト原点になります。 |
| `Plane` | **平面**: XZ平面に配置される平面を追加します。床面や押し出しのベースとして利用します。 |
| `3`〜`32` | **分割数設定**: プリミティブ作成時の密度を指定します。数値が大きいほど滑らかになりますが、編集点数が増え負荷が高まります（初期値: 12）。 |
| `Next` | 第1ページへ戻ります。 |

## 詳細機能仕様

### 変形操作 (Transform)
`G/R/S/E/GG` のいずれかを選択した後、1本指ドラッグでプレビューを行います。
- **確定**: 短いタップで確定します。
- **継続操作**: 指を離した時点では確定されず、その位置を基準に再度ドラッグして微調整を行うことが可能です。
- **エッジスライド (GG)**: 選択頂点が2つの隣接頂点に挟まれた中点である場合に限り、そのエッジの直線上でスライドさせます。

### Sculpt Mode
Sculpt Mode は active object の頂点だけをブラシで直接変形する第 3 のモードです。
- **入口**: 通常パレットの `Sclpt`、または view dock / canvas 下端からの上方向 flick。
- **ブラシ種類**: `Draw` は法線方向、`Blur` は平均化、`Grab` はカーソル移動方向、`Pinch` はカーソル中心方向へ変形します。
- **ブラシ方向**: `Sclp+` は正方向、`Sclp-` は負方向です。Draw では膨らみ / 凹みの切り替えになります。
- **ブラシ設定**: `Brsh` で、半径、強度、減衰形状を overlay から編集できます。強度は 1.0 が強い入力値です。
- **X Mirror / Edit**: 専用パレットの `M` で左右対称 sculpt を切り替え、`Edit` で編集モードへ戻れます。
- **減衰形状 (Falloff)**:
    - `Sphere`: 半球状に滑らかに減衰。
    - `Triangle`: 距離に比例して直線的に減衰。
    - `Peak`: 中心付近で強く、急激に減衰。
    - `Flat`: 範囲内は均一に適用。
- **ストローク開始**: Sculpt Mode では `↑` を ON にした間だけ 1 本指ドラッグがブラシ stroke になり、OFF の間は camera orbit を優先します。何もない領域のダブルタップでも brush / camera を切り替えられます。
- **長押し**: Sculpt Mode の何もない領域では `Brsh` と同じく brush 設定 overlay を開きます。Sculpt Mode の図形上では現在の mode を保ちます。Object / Edit Mode の図形上では mode を切り替えます。
- **ブラシカーソル**: 表面を認識すると、法線に合わせて回転した「楕円」が表示されます。サイズは 3D 上の半径を画面に投影した実際の大きさに連動します。
- **X Mirror**: `M` が ON のときは、ブラシ変形も X=0 基準の対称位置へ同時に適用されます。

### ループカット (Loop Cut)
編集モードで四角面を選択して `Cut` を実行します。
- **伝播**: 選択した面を開始点として、隣接する四角面へ向かってカットを伝播させます。
- **方向選択**: 単一の面のみを選択している場合は、緑色のプレビュー線が表示されます。指を辺に近づけて方向を選び、タップで確定します。
- **X Mirror**: ON の場合、選択した側のカット方向を反対側のミラー面にも同時に適用します。

### ループ選択 (Select Loop)
`Loop` は、ループカットで作成された中点頂点列を効率的に選択するための機能です。
- **開始点**: ループカット後の中点頂点を「頂点選択モード」で選択してから実行します。
- **選択方向**: 選択頂点がエッジの中点であることを判定し、対辺側にある中点頂点へ向かって選択を広げます。
- **活用例**: `Cut` $\rightarrow$ `Loop` で中点列を選択し、そのまま `GG` でエッジに沿って位置調整を行う、といった使い方が可能です。

### 連続選択 (Chain Select)
`Chain` は、任意の頂点から隣接エッジの方向を指定し、四角面のみで繋がっている頂点列を選択します。
- **開始点**: 「頂点選択モード」で開始頂点を選択してから実行します。
- **方向選択**: プレビュー線を確認しながら方向（縦・横など）を選び、タップで確定します。
- **停止条件**: 立方体の角（90度）、三角面、五角面などに到達すると選択は停止します。

### 矩形選択 (Box Select)
図形が存在する状態で、何もない領域をダブルタップして開始します。
- **Sculpt Mode では例外**: 何もない領域のダブルタップは、camera / brush 操作を切り替えます。
- **操作**: ドラッグで選択範囲をプレビュー表示します。
- **確定**: 指を離した後、範囲を確認し、タップで選択を確定します。
- **修正**: 確定前に再度ドラッグすることで、範囲を引き直せます。
- **キャンセル**: 準備中またはプレビュー中に再度ダブルタップすると、キャンセルされます。

### 細分化 (Subdivision)
- **Subd (単純細分化)**: 四角面のみのメッシュを1段階細分化します。各面が四角形のメッシュを対象に、1つの面を4つの四角面へ分割します。三角面を含む場合は、面構成を確認するメッセージを表示します。
- **Catmull-Clark (スムージング細分化)**: 面の中心点やエッジの中点を用いてメッシュを再構成し、滑らかな形状にします。多様体（manifold）エッジと単純な境界を持つ形状を対象にし、それ以外の形状は境界の確認が必要な入力としてエラーを表示します。

### 選択・表示の仕様
- **マーカー**: 選択済みの頂点は赤く表示されます。また、両端の頂点が選択されているエッジも赤く表示されるため、ループ選択の結果を線として確認できます。
- **裏側選択**: `Wire` (ワイヤーフレーム) が ON の編集モードでは、視覚的に裏側に隠れている頂点も選択可能です。
- **陰影**: `Smth` は、頂点構造を変えずに表示上のシェーディングのみを滑らかにします。
- **追加選択**: 画面左上の `↑` ボタンが有効な間は、PC の Shift キーと同様に「追加選択」として動作します。

### ビュー dock (視点切り替え)
画面端（縦画面では上部、横画面では右端）に配置されたボタンで、以下の視点へ即座に切り替えられます。
- `X` / `-X`: 側面 / 反転側面
- `Y` / `-Y`: 上面 / 反転上面
- `Z` / `-Z`: 正面 / 反転正面

view dock の視点切り替えは、camera target と距離を維持したまま、オービット姿勢を標準方向へ戻します。2 本指回転で傾けた view roll もここでリセットされます。

## Blender との連携
専用の Blender アドオン (`blender_modelasset_io.py`) を使用することで、mmodeler と Blender 間でデータをやり取りできます。

### 導入方法
1. Blender の `Edit > Preferences > Add-ons > Install...` から `blender_modelasset_io.py` をインストールします。
2. `Webg ModelAsset JSON I/O` を有効化します。

### データの受け渡し
- **mmodeler $\rightarrow$ Blender**: mmodeler で `Json` (gzip圧縮済みJSON) として保存し、Blender の `File > Import > Webg ModelAsset JSON` で読み込みます。
- **Blender $\rightarrow$ mmodeler**: Blender でメッシュを選択し、`File > Export > Webg ModelAsset JSON` で書き出し、mmodeler の `Load` で読み込みます。
- **軸変換**: 標準設定で、Blender の Z-up と mmodeler の Y-up を相互に変換します（設定で OFF にすることも可能です）。
