MIRGRID Developers

ドキュメント / 使い方

はじめに

MIRGRID Web SDK（@mirgrid/web-sdk）は、地球上の場所を「セル」という小さな立方体の単位で扱うための JavaScript ライブラリです。計算の中身は WebAssembly で動くので、ブラウザでも Node.js でも同じ関数を呼べます。

この SDK でできること

  • 緯度・経度・高さや平面直角座標系の座標を、セルとその空間アドレス（セルの ID）に変換できます。
  • セルの集合どうしの和・積・差を求めたり、距離を測ったり、範囲で切り出したり、2 時点の差分をとったりできます。
  • 点群（PLY・LAS・LAZ）や 3D モデル（glTF・GLB・OBJ・STL）をブラウザの中でセルにして、WebGL2 で表示できます。
  • MIRGRID が配信するデータ（MGVX packet）を読んで、描画に使える配列にできます。

インストール

npm でインストールします。

npm install https://developers.mirgrid.com/download/mirgrid-web-sdk-0.1.1.tgz

パッケージのファイルは、ダウンロードのページからも入手できます。

初期化する

関数を使う前に、init() を一度だけ呼んで WebAssembly のモジュールを読み込みます。init() は Promise を返すので、await で終わるのを待ってください。

ブラウザとバンドラ

ブラウザや、Vite などのバンドラを使うときは、引数なしで init() を呼びます。

import init, { spatial_voxel_size_m } from '@mirgrid/web-sdk';

await init();
console.log(spatial_voxel_size_m(24));

1

init() は、パッケージの voxel_core.js と同じ場所にある voxel_core_bg.wasm を読み込みます。バンドラを使わずにファイルをそのまま配るときは、この 2 つのファイルを同じディレクトリに置いてください。wasm ファイルを別の場所に置く場合は、init({ module_or_path: '/assets/voxel_core_bg.wasm' }) のように URL を渡します。

Node.js

Node.js では init() が wasm ファイルを自分で読み込めないので、ファイルの中身を読んで渡します。

import { readFileSync } from 'node:fs';
import init from '@mirgrid/web-sdk';

const wasmUrl = new URL(import.meta.resolve('@mirgrid/web-sdk/voxel_core_bg.wasm'));
await init({ module_or_path: readFileSync(wasmUrl) });

最初の例: 場所を空間アドレスにする

東京駅のあたりの 1 点を、一辺 1 m のセルの空間アドレスに変換してみます。

import init, {
  spatial_geodetic_to_ecef,
  spatial_ecef_to_voxel,
  spatial_hilbert_cellid_hex,
  spatial_voxel_size_m,
} from '@mirgrid/web-sdk';

await init();

// 経度・緯度は度、高さは楕円体高（m）で渡します
const [x, y, z] = spatial_geodetic_to_ecef(139.767125, 35.681236, 40);
const level = 24;
const [vx, vy, vz] = spatial_ecef_to_voxel(x, y, z, level);
const address = spatial_hilbert_cellid_hex(vx, vy, vz, level);

console.log('ECEF:', x, y, z);
console.log('セルの一辺:', spatial_voxel_size_m(level), 'm');
console.log('セルの番号:', vx, vy, vz);
console.log('空間アドレス:', address);

実行すると、次のように出力されます。

ECEF: -3959690.4856980876 3350094.2679115087 3699543.3691692664
セルの一辺: 1 m
セルの番号: 4428917 11738702 12088151
空間アドレス: 0000000002e9380374bc9e7c5e140000

この例では、次の 3 つの手順で変換しています。

  1. spatial_geodetic_to_ecef で、経度・緯度・高さを ECEF に変換します。ECEF は、地球の中心を原点にした x・y・z の直交座標（単位は m）です。引数は経度が先で、緯度があとです。
  2. spatial_ecef_to_voxel で、ECEF の点がどのセルに入るかを求めます。セルの大きさはレベルで決まります。レベルは 1〜30 で、数が大きいほどセルが細かくなります。レベル 24 のセルは一辺 1 m です。結果はセルの番号（x・y・z の 3 つの整数）です。
  3. spatial_hilbert_cellid_hex で、セルの番号を空間アドレスにします。空間アドレスはセルの ID で、32 桁の 16 進の文字列です。同じ場所を同じレベルで変換すれば、いつも同じ空間アドレスになります。

高さは楕円体高で渡します。手元の高さが標高のときは、ジオイド高を足してから渡してください（高さとジオイド高を参照）。

動作環境

  • ブラウザ: WebAssembly と ES Modules に対応したブラウザで動きます。セルを画面に描く @mirgrid/web-sdk/render.mjs は WebGL2 を使います。WebGL2 が使えない環境では、描画器を作るときに Error になります。
  • Node.js: 座標の変換、セルの集合の計算、ファイルのセル化、配信データの読み込みは Node.js でも使えます。描画（render.mjs）は使えません。ここに載せた例は、Node.js 26 で動かして確かめています。

次に読む文書

場所とセルの関係をもう少し詳しく知りたいときは、位置と空間アドレスを読んでください。レベルごとのセルの大きさ、ENU や平面直角座標系との変換を説明しています。

たくさんのセルをまとめて扱うときはセルの集合、点群や 3D モデルをセルにして表示するときはファイルをセルにして表示する、MIRGRID の配信データを読むときは配信データを読むへ進んでください。関数の引数と戻り値はAPI リファレンスにまとめています。