MIRGRID Developers

空間の問いに、
CLI 1 本で答える。

点群・BIM(IFC)・2D 図面(DXF)・点検表を、地球固定の格子のセル(空間アドレス)に載せる SDK です。「この部材から 0.5 m 以内の変状は?」「2×3×2 m の設備は置ける?」に、digital-twin-sdk が JSON で答えます。Claude Code や Codex などの AI エージェントに道具として渡す前提で作っています。

macOS(Apple Silicon)版をダウンロードWindows(x64)版をダウンロード

digital-twin-sdk 0.5.0(2026-10-13 公開)。チェックサムと以前の版

インストーラは無く、実行ファイル 1 つで動きます。
Linux 版はまだありません。

東京駅の空間アドレス 経度 139.7671248 / 緯度 35.6812362 / 楕円体高 40 m
levelセルの一辺空間アドレス(32 桁の 16 進)
L16256 m0000000002e9380374bc9c0000000000
L2016 m0000000002e9380374bc9e7c40000000
L241 m0000000002e9380374bc9e7c5e140000
L2625 cm0000000002e9380374bc9e7c5e151000
L286.25 cm0000000002e9380374bc9e7c5e151f40
L3015.6 mm0000000002e9380374bc9e7c5e151f51

同じ地点を level だけ変えて cell-at で引いた値です。level を 2 上げるとセルの一辺は 1/4 になり、アドレスの末尾が決まっていきます。セルは索引と表示のためのもので、mm を測るのは元の点群です。

問いと、呼び方と、答え

駿府城 東御門橋の点群(LAZ)と小さな建物の IFC を 1 つのプロジェクトに入れ、3 つの問いを聞いた実際の出力です。

橋と建物のあいだは、どこをとっても 3 m 以上離れている?

clears が答えです。minSeparationM はセル幅(0.5 m)どまりの下限で、mm の離隔は元の点群(points-query)で測ります。

digital-twin-sdk interference --project site \
  --a bridge --b building --clearance-m 3
{
  "level": 25,
  "cellSizeM": 0.5,
  "requiredClearanceM": 3.0,
  "overlapCellCount": 0,
  "minSeparationM": 9.5,
  "clears": true
}

出力の一部(ほかに、近かった物の一覧と接触・包含の判定が付きます)

橋から見て、建物はどちら側にある?

方位はセルの位置で決めます。座標を自分で引き算して判断しないでください。

digital-twin-sdk direction --project site --a bridge --b building
{
  "schemaVersion": 1,
  "op": "direction",
  "aCellCount": 1950,
  "bCellCount": 279,
  "directions": ["east_of"],
  "offsetEnuM": [20.5, 0.0, -2.25],
  "gapEnuM": [9.5, 0.0, 0.0],
  "overlapAxes": { "east": false, "north": true, "up": true }
}

高さ 0.5〜2.5 m に空いている場所は? そのうち、まだ誰も見ていない場所は?

点が無いことは、空いていることではありません。スキャナの据付位置(--sensor-origin)から見通せたセルだけが「空き」と確かめられ、残りは unknownCellCount に数えられます。

digital-twin-sdk free-space --project site --height-m 0.5,2.5
{
  "frame": "site",
  "level": 25,
  "heightBandM": [0.5, 2.5],
  "occupiedCellCount": 2229,
  "freeCellCount": 8298,
  "unknownCellCount": 8137,
  "outputPath": "site/derived/free.csv"
}

出力の一部(ほかに、空き空間の塊ごとの体積と範囲が付きます)

このプロジェクトの作り方 
digital-twin-sdk project init site --name 東御門橋 \
  --origin 138.38514,34.97774,54 --epsg 6676 --level 25 --datum JGD2011
digital-twin-sdk project add-source site bridge.laz --coord-system 6676 \
  --geoid-height 36.0 --sensor-origin 138.38514,34.97774,64 --actor human
digital-twin-sdk project add-source site building.ifc --offset 20,0,0 --actor human

はじめる

  1. ダウンロードして展開する

    macOS は tar.gz、Windows は zip です。中身は実行ファイルと、AI エージェントが最初に読む AGENTS.md・CLAUDE.md・docs/。

    ダウンロードと入れ方

  2. PATH に置く

    署名していないため、macOS は隔離属性を外し、Windows は Unblock-File を通してから PATH に足します。手順はダウンロードのページにあります。

  3. 動くか確かめる

    digital-twin-sdk version

    {"sdkVersion":"0.5.0",...} が返れば入っています。全引数は digital-twin-sdk --help です。

  4. 現場をプロジェクトにする

    digital-twin-sdk project init site \
  --name 現場A --epsg 6676 --datum JGD2011 \
  --origin 138.38514,34.97774,54
digital-twin-sdk project add-source site scan.laz \
  --coord-system 6676 --geoid-height 36.0 \
  --actor ai
digital-twin-sdk project status site --pretty

    原点・座標系・セルの細かさはプロジェクトが覚えます。project status が次にできることを返します。

AI エージェントに使わせる

エージェント向けの文書は Markdown のまま読めます。一覧は /llms.txt。

  1. 自分のツールを作るフォルダに、この配布物の AGENTS.md・CLAUDE.md・docs/ をコピーする。
  2. そのフォルダで Claude Code / Codex を起動する。エージェントは AGENTS.md から docs/AI_AGENT_GUIDE.md を読み、 digital-twin-sdk --help で引数を確かめてから CLI を呼びます。
  3. 頼み方の例:
    • 「site/ にプロジェクトを作って model.ifc と plan.dxf(mm)を取り込み、状態を見せて」
    • 「部材 G1 から 0.5 m 以内にある変状を全部挙げて」
    • 「この 2×3×2 m の設備を置ける場所を探して、入口からの搬入経路も」
    • 「この CLI を呼んで点検表(CSV)を取り込み、評価 C 以上の箇所を一覧にする Python スクリプトを書いて」

うまく使わせるコツ:

  • 空間の計算はエージェントに書かせず、CLI に任せる。 距離・包含・上下関係を座標から自分で計算させると誤りやすい。
  • 「無い」と「分からない」を区別させる。 SDK は分からないときに null を返す。0 や空と読み替えないよう、エージェントのガイドに書いてある。
  • 社内の評価(橋梁 12 問)では、Claude / Codex の大型モデルはこのガイドと --help だけで CLI を使いこなした (外したのは正解の定義(境界の扱い)が SDK と違う 3 問だけ)。3〜8B の小型ローカル LLM は引数の誤りが多く、このままでは向かない。
AGENTS.md 配布物に入っている、エージェントが最初に読む入口

MIRGRID SDK を道具として使う(AI エージェント向けの入口)

空間の問い(どこに何があるか・距離・包含・空き・経路・図面)は、PATH 上の digital-twin-sdk CLI で答える。 作業を始める前に docs/AI_AGENT_GUIDE.md を読むこと。 全引数は digital-twin-sdk --help が正本 (サブコマンド単位の --help は無い)。

守ること:

  • 空間の計算を自分で書かない。 距離・包含・上下・見通し・離隔は CLI(objects-near / objects --box-enu / interference / direction / visible など)に任せる。セルの座標を自分で比べて結論を出さない。
  • CLI の出力は stdout の JSON。 エラーは stderr の {"error":{"code":...,"message":...}} 1 行(exit 1)。 message の指示に従って引数を直して呼び直す。
  • null を 0 や「無い」と読み替えない。 分からないことを SDK は null で返す。距離・離隔はセル幅どまりの下限。
  • 現場の作業はプロジェクト経由。 迷ったら digital-twin-sdk project status DIR --pretty。 書き戻す操作には --project DIR --actor ai を付ける。人間が上げた原本(by: human)を消さない。
  • 物を引くときは相手のレイヤを --cells で必ず渡す(省くと物を持たない統合セルを引いてエラーになる)。 最も近いものを探すときは --radius-m を十分大きく取り --limit 1(既定の半径は 1 m)。
  • 「配管」「壁」などの意味づけはあなたの仕事。SDK は名前・種別・属性への素朴な一致しかしない。
  • 形を作って確かめるときは model を使う(model create / extrude → constrain → check --rasterize)。 寸法・距離・向きは model measure / model check に任せ、自分で計算しない。satisfied: null は 「判定できない」(reason を読む)で、満たした・破ったのどちらでもない。仕様は docs/SPATIAL_CREATION_SDK_REFERENCE.md。

ドキュメント

配布物の docs/ に入っている文書と同じものです。

はじめに

リファレンス

形式と格子