Original Provider¶

デフォルトとして、 StandardImageProvider を用意していますが、これらのクラスの機能だけでは対応できないとき、コンテンツ開発者が独自のデータプロバイダを実装できます。

1つのデータプロバイダは、固定サイズのタイルを単位にデータを提供します。たとえば典型的な地図画像プロバイダは 256×256 サイズの画像タイルを提供します。提供されるタイルは \(Z/X/Y\) 座標で区別されます。 Mapray エンジンはデータプロバイダにタイルを要求するときに \(Z/X/Y\) 座標を指定します。

座標系については Basics - Tile coordinates をご覧ください。

独自の地図画像プロバイダを定義¶

独自の地図画像プロバイダを定義するためには 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() );