ウラノスGEX 4次元時空間情報基盤用 共通ライブラリ(JavaScript版)

[!NOTE] このパッケージは ODS-IS-STID/ouranos-gex-lib-for-JavaScript の非公式forkです。元実装との互換性を維持しながら、npm配布対応と各種不具合修正・機能改善を行っています。

概要

• 任意の座標を空間IDに変換するライブラリです。
• 空間ID仕様については以下のリンクを参照して下さい。

共通ライブラリ利用方法

1. npmインストール

   npm install @hakobune8/spatial-id-javascript

2. モジュールのロード

   import { Space } from '@hakobune8/spatial-id-javascript';

   CommonJSからも利用できます。

   const { Space } = require('@hakobune8/spatial-id-javascript');

注意事項

• ライブラリの入力可能な緯度の最大、最小値は「±85.0511287798」とします。
• 精度レベルの指定範囲は、0から35とします。
• 経度の限界値は±180ですが、180と-180は同じ個所を指すこととZFXY形式のインデックスの考え方により、180はライブラリ内部では-180として扱われます。(180の入力は可能とします。)
• 座標から変換できる最大高度は alt < 33,554,432 mです。最小高度はズームごとに -33,554,432 + 33,554,432 / 2^zoom m（端点を含む）となり、getMinimumAltitude(zoom) で取得できます。この範囲はZFXYのルートボクセルおよびtilehashの階層表現によるものです。

詳細仕様

コンストラクタ

新しい空間オブジェクトを返します。

Space( input, zoom? )

input

座標及び高度または空間 ID を以下のフォーマットで指定することができます。

• LngLatWithAltitude: 緯度経度及び高度を含むオブジェクト。（例: { lng: number, lat: number, alt?: number }）
• ZFXYTile: ZFXY（3次元タイル番号）を示す文字列。（例: /15/6/2844/17952）
• TileHash: ZFXY をハッシュ化した値。（例: 100213200122640）

zoom

ズームレベル（分解能）を整数で指定することができます。
この引数は省略も可能で、デフォルトは 25 です。

補助コンストラクタ

Space.boundingSpaceForGeometry( geometry, minZoom? )

geometry に渡された GeoJSON の Geometry オブジェクトに対して、最小分解能（ズームレベル）での空間IDを返す。 minZoom が指定している場合は、より少ない分解能（ズームレベル）の空間IDが作られるにしても、 minZoom での空間IDを返す。 3D座標の3番目の値は高度（m）として扱われ、XYZすべてを包含する共通の空間IDを返します。高度0をまたいで異なるtilehashルートに属するGeometryは、単一の空間IDでは表現できないためエラーとなります。

Space.spacesForGeometry( geometry, zoom, options? )

geometry に渡された GeoJSON の Geometry オブジェクトに対して、その Geometry と指定の zoom での分解能（ズームレベル）の空間IDの共通集合を配列として返す。 3D Geometryでは、水平形状と全頂点の最小～最大高度が作る範囲を覆うボクセルを返します。2D Geometryは従来どおり f=0 として扱います。2D座標と3D座標の混在はサポートしません。

交差する親タイルだけを再帰的に探索するため、離れたMultiPolygonや穴を含むPolygonでもbbox全体は走査しません。同期APIが巨大な配列を生成し続けることを防ぐため、既定で返却する空間数を100,000件、交差判定する候補を1,000,000件までに制限します。options.maxSpaces と options.maxCandidates で上限を変更できます。上限超過時はbboxによる事前上限見積りを含むエラーを返します。さらに大きな結果には、ズームを下げるかGeometryを分割してください。現在は非同期・ストリーミング形式を提供していません。

メソッド

Space のメソッドのドキュメンテーションは下記となります。

.center

• 現在の空間オブジェクトの中央点 (3Dの {lng: number, lat: number, alt: number} 型)

.alt

• 現在の空間オブジェクトの最低高さ (floor)

.zoom

• 現在の空間オブジェクトのズームレベル（分解能）

.zfxy

• 現在の空間オブジェクトが表現している ZFXY を ZFXYTile 型 ({ z: number, f: number, x: number, y: number })

.id, .tilehash

• 現在の空間オブジェクトが表現している ZFXY の tilehash の文字列

.zfxyStr

• 現在の空間オブジェクトが表現している ZFXY を URL のパス型に変換したもの

.up(by?: number)

• f の正方向（上）へ by セル移動した、新しい単一の Space を返します。by は返却件数ではなく移動量で、省略時は 1 です。

.down(by?: number)

• f の負方向（下）へ by セル移動した、新しい単一の Space を返します。by は返却件数ではなく移動量で、省略時は 1 です。

.north(by?: number), .east(by?: number), .south(by?: number), .west(by?: number)

• 指定方向へ by セル移動した、新しい単一の Space を返します。by は返却件数ではなく移動量で、省略時は 1 です。
• タイル座標では北が y の負方向、南が y の正方向、東が x の正方向、西が x の負方向です。
• 負の by は反対方向への移動として扱います。Xは日付変更線で周回し、YはWeb Mercatorの北端・南端でクランプされます。

.move(by: Partial<Omit<ZFXYTile, 'z'>>)

• 現在の空間オブジェクトから x、y、f の相対移動量を適用した、新しい単一の Space を返します。正のXは東、正のYは南、正のFは上です。
• Xはズームレベルの範囲で周回し、YとFは表現可能な範囲でクランプされます。

const space = new Space('/5/3/10/12');

space.up(2).zfxy;    // { z: 5, f: 5, x: 10, y: 12 }
space.down(2).zfxy;  // { z: 5, f: 1, x: 10, y: 12 }
space.north(2).zfxy; // { z: 5, f: 3, x: 10, y: 10 }
space.south(2).zfxy; // { z: 5, f: 3, x: 10, y: 14 }
space.east(2).zfxy;  // { z: 5, f: 3, x: 12, y: 12 }
space.west(2).zfxy;  // { z: 5, f: 3, x: 8, y: 12 }

space.move({x: 1, y: 5, f: -1}).zfxy;
// { z: 5, f: 2, x: 11, y: 17 }（東1、南5、下1セル）

.surroundings()

• 現在の空間オブジェクトのまわりにあるすべての空間オブジェクトを配列で返す。

.parent(atZoom?: number)

• 現在の空間オブジェクトから、分解能（ズームレベル）を atZoom のズームレベルまで下げる。デフォルトでは1段階下げます。

.children()

• 現在の空間オブジェクトから、分解能（ズームレベル）を一つ上げて、そこに含まれるすべての空間オブジェクトを返す。

.contains()

• 指定された緯度経度が、指定されたボクセル内に含まれるかどうかを判定して bool 値を返す。

.vertices3d()

• 現在の空間オブジェクトの3Dバウンディングボックスを作る8点の座標を配列として返す。