概要と約束事
コマンドを呼ぶ前に知っておく必要があるのは、次の 4 つです。
getState() の全フィールド。URL パラメータデータ指定・招待リンク・中継接続・ビュー状態。座標系
2 つの系があります。取り違えると、エラーは出ないのに違う場所を触ります。
| 系 | 何に使うか |
|---|---|
| 実座標（real, m） | 計測値・カメラ API・クリック座標・所見のピン・書き出し |
| 整列（シーン）フレーム | selectBox の min/max、alignedBounds、querySelection の返り値、断面の範囲 |
変換は次のとおりです。
scene = Rz(-alignYaw) · (real - offset)offset と alignYaw は getState().frame と queryCrs から取れます。 先頭のソースが確定した時点で決まり、全ソースを削除するまで不変です。
なぜ 2 系あるのか——平面直角座標系の点群は座標値が数万 m のオーダーになり、 float32 のまま GPU に載せると点が震えます。COPC ヘッダの cube 中心を 固定オフセットとして減算し、原点付近に正規化してから描画しているためです。
整列フレームで箱を組むときは、必ず alignedBounds を起点にしてください。
const { alignedBounds: b } = oniyanma.getState() // [minX,minY,minZ, maxX,maxY,maxZ]
const zTop = b[5] - (b[5] - b[2]) * 0.2 // 上端 20%
await oniyanma.execute('selectBox', { min: [b[0], b[1], zTop], max: [b[3], b[4], b[5]] })CRS は記録するだけ
座標参照系（EPSG）と鉛直基準（orthometric = 標高 / ellipsoidal = 楕円体高 / unknown）は queryCrs で確認できますが、再投影は行いません。
日本ではジオイド高が 30〜40 m あるので、標高の値を報告する前に基準を確認してください。
resident 基準
点数を返すものは、断りが無い限り resident 基準です。 「いま表示されている LOD サンプルの中で条件を満たす点の数」であって、 原本の全点走査ではありません。
対象: querySelection · queryBoxCount · queryElevation · queryClasses · queryLayers · exportSelection · 確認ゲートが返す wouldAffect
寄れば LOD が細かくなり、同じ範囲でも数は増えます。 桁を見る用途には使えますが、厳密な点数として扱わないでください。
サーフェス
入口ごとの読み書き分離です。
| サーフェス | 実行できるもの |
|---|---|
all（既定） | 全 61 コマンド |
read | readonly の 18 コマンドだけ |
read の入口から書きコマンドを呼ぶと、実行時に拒否されます （ツール定義を絞るだけでは、名前を知っていれば通ってしまうため）。 拒否メッセージには実行可能なコマンドの一覧が付きます。→ コマンド層という設計
発行者（actor）
ディスパッチのたびに注入され、編集コマンドは Command ログに焼き込みます。
kind | 由来 | 確認ゲート |
|---|---|---|
human | UI / ⌘K / ショートカット | 通らない |
ai | AI コンソール（name にモデル名、prompt に指示文の冒頭） | 通る |
api | window.oniyanma / MCP 経由 | 通る |
返り値とエラーの約束
成功。 副作用だけのコマンドは { ok: true }。値を返すものは JSON オブジェクトです。 「できなかったが例外ではない」場合は { ok: false } を返します （例: 選択が無い状態の zoomToSelection）。
ドライラン。 破壊的コマンドを機械が confirm 無しで呼ぶと、 { preview: true, command, wouldAffect, note } が返ります。実行されていません。
エラー。 例外（Promise の reject）として投げられます。 メッセージは「次に何をすればよいか」が読める形にしてあります。
所見の型 crack がありません（定義済み: damage）。defineFindingType で作れますdeleteSelection は書き込みコマンドなので、読み取り専用サーフェスでは実行できません。
この入口では状態の問い合わせだけが可能です（利用可能: getCamera, measureDistance, …）「見つかりません」で終わらせず、原因と代替手段を添えるのは、 AI がそのまま次の一手を選べるようにするためです。
非同期
executeCommand は Promise を返します。 同期的に済むコマンドも含めて await してください （loadData / addData / addSurface / setBackend は実際に非同期です）。