高度なトピック

Z/X/Y 座標の \(Z\) はズームレベルを表し、 \(Z > 0\) となる整数です。 \(X\) はそのズームレベル上のタイルの水平方向の位置、 \(Y\) は垂直方向の位置を表し、 \(0 \le X, Y \le 2^Z - 1\) となる整数です。 北緯および南緯約 85.0511 度以上を除外した、正方形のメルカトル世界地図上に Z/X/Y 座標が定義されます。 \(Z\) 座標が \(z\) のタイルは、この正方形地図を縦横均等に \(2^z\) 分割された領域に対応します。 \(X\) 座標は一番左側のタイルが \(0\) で、一番右側のタイルが \(2^z - 1\) になり、 \(Y\) 座標は一番上側のタイルの \(0\) で、一番下側のタイルが \(2^z - 1\) になります。 数式で表すと、経度 \(\lambda\), 緯度 \(\phi\) と Z/X/Y 座標の関係は次のようになります。ここで \(\mathrm{gd}\) はグーデルマン関数を、 \(c_1, c_2\) は任意の整数を表します。

独自のDEMデータプロバイダを定義するには DemProvider を利用します。 このクラスは、コンストラクタ引数で指定される DemProvider.Hook により動作が決定します。 独自の動作をするような DemProvider.Hook を実装することで実現することができます。

DemProvider.Hook を実装するには、下記二つの関数を定義する必要があります。

• init( options?: { signal?: AbortSignal } ): Promise<DemProvider.Info>
• requestTile( z: number, x: number, y: number, options?: { signal?: AbortSignal } ): Promise<ArrayBuffer>

init() はタイルプロバイダを初期化してリクエストできる状態にするメソッドです。 レンダラが一度だけ呼び出します。 この関数の戻り値としてこのプロバイダの情報をリターンする必要があります。 リクエストできる状態に遷移できなかった場合は必ず例外をスローしなければなりません。

requestTile() はMaprayエンジンがタイルをリクエストするときに呼び出すメソッドです。 この関数は init() が呼ばれ、エラーが起きなかった場合にのみ呼ばれる関数です。 このメソッドの z , x , y パラメータはタイルの座標で、カメラ位置に応じてアクセスされるタイルは変わります。 signal パラメータは、タイルのリクエストを取り消すときに設定します。

以下は単純なDEMデータプロバイダ MyDemProviderHook の実装例です。 この例では https://user-server/... にタイルデータが配信されている想定で書かれています。

/**
 * https://user-server/ で配信されるタイルを表示するためのプロバイダーフック
 */
export class MyDemProviderHook implements DemProvider.Hook {

    async init()
    {
        // 何らかのAPI呼び出しなどを行いタイル情報を取得し、必要な情報をリターンします。
        const response = await fetch( `https://user-server/...json`, {
            headers: {
                Authorization: "Bearer: (アクセストークン)", // アクセストークンなど接続に必要な認証情報を付与します
            },
        } );

        if ( !response.ok ) {
            throw new Error( "Failed to get info" );
        }

        const info = await response.json();

        // 必要に応じて認証情報などをインスタンス変数などで保持します。
        const resolution_power = info.resolution_power;
        return {
            resolution_power: resolution_power,
        };
    }


    async requestTile( z: number, x: number, y: number ): Promise<ArrayBuffer>
    {
        // サーバへアクセスを行いタイルデータを取得します。
        const url = "https://user-server/" + z + "/" + x + "/" + y + ".bin";

        const response = await fetch( url, {
            headers: {
                Authorization: "Bearer: (アクセストークン)", // アクセストークンなど接続に必要な認証情報を付与します
            },
        } );

        if ( !response.ok ) {
            throw new Error( "Failed to get tile" );
        }

        return await response.arrayBuffer();
    }

}

上記のように init(), requestTile() の最後の引数 { signal?: AbortSignal } は省略することができます。

MyDemProviderHook を利用するには、下記のように DemProvider の引数に Hook を指定します。

new DemProvider( new MyDemProviderHook() );

独自の地図画像プロバイダを定義するためには ImageProvider を利用します。 このクラスは、コンストラクタ引数で指定される ImageProvider.Hook により動作が決定します。 独自の動作をするような ImageProvider.Hook を実装することで実現することができます。

ImageProvider.Hook を実装するには、下記二つの関数を定義する必要があります。

• init( options?: { signal?: AbortSignal } ): Promise<DemProvider.Info>
• requestTile( z: number, x: number, y: number, options?: { signal?: AbortSignal } ): Promise<ImageProvider.SupportedImageTypes>

init() はタイルプロバイダを初期化してリクエストできる状態にするメソッドです。 レンダラが一度だけ呼び出します。 この関数の戻り値としてこのプロバイダの情報をリターンする必要があります。 リクエストできる状態に遷移できなかった場合は必ず例外をスローしなければなりません。

requestTile() はMaprayエンジンがタイルをリクエストするときに呼び出すメソッドです。 この関数は init() が呼ばれ、エラーが起きなかった場合にのみ呼ばれる関数です。 このメソッドの z , x , y パラメータはタイルの座標で、カメラ位置に応じてアクセスされるタイルは変わります。 signal パラメータは、タイルのリクエストを取り消すときに設定します。

以下は単純な地図画像プロバイダ MyImageProviderHook の実装例です。 この例では https://user-server/images/... にタイルデータが配信されている想定で書かれています。

/**
 * https://user-server/images/ で配信される画像タイルを表示するためのプロバイダーフック
 */
export class MyImageProviderHook implements ImageProvider.Hook {

    async init()
    {
        // 何らかのAPI呼び出しなどを行いタイル情報を取得し、必要な情報をリターンします。
        const response = await fetch( `https://user-server/images/...json`, {
            headers: {
                Authorization: "Bearer: (アクセストークン)", // アクセストークンなど接続に必要な認証情報を付与します
            },
        } );

        if ( !response.ok ) {
            throw new Error( "Failed to get info" );
        }

        const info = await response.json();

        // 必要に応じて認証情報などをインスタンス変数などで保持します。
        const image_size = info.image_size;
        const min_level = info.min_level;
        const max_level = info.max_level;
        return {
            image_size: image_size,
            zoom_level_range: new ImageProvider.Range( min_level, max_level ),
        };
    }


    async requestTile( z: number, x: number, y: number ): Promise<ImageProvider.SupportedImageTypes>
    {
        // サーバへアクセスを行いタイルデータを取得します。
        const url = "https://user-server/images/" + z + "/" + x + "/" + y + ".png";

        return await new Promise( (resolve, reject) => {
                const image = new Image();
                image.onload  = event => resolve( image );
                image.onerror = event => reject( new Error("Failed to load image") );
                image.src = url;
        } );
    }

}

上記のように init(), requestTile() の最後の引数 { signal?: AbortSignal } は省略することができます。

MyImageProviderHook を利用するには、下記のように ImageProvider の引数に Hook を指定します。

new ImageProvider( new MyImageProviderHook() );

Viewer#getElevation() と Viewer#getRayIntersection() により得られる値は、その時の状況により精度が変化します。 これは現在メモリ内に存在するもっとも精度が高いDEMデータを使い、即時に値を計算しているからです。

Viewer#getElevation() は、さらに詳細なDEMデータが DemProvider により取得することができれば、そのデータをリクエストします。そのため、時間を置いてこのメソッドを呼び出すと、さらに正確な値を取得できることがあります。

これに対し Viewer#getRayIntersection() は新たにDEMデータをリクエストしません。このメソッドは基本的に現在画面に表示されてる場所が対象になり、一般的に、近くに表示されている部分は精度が高く、遠くに表示されている部分は精度が低くなります。