開発者ガイド

maprayJS API はすべて mapray 名前空間に含まれています。例えば mapray 名前空間に含まれる Viewer クラスは、 mapray.Viewer のようにな記述で説明します。

前節の方法でライブラリをインポートした場合、次のような JavaScript での記述で mapray.Viewer クラスのインスタンスを生成することができます。

var viewer = new mapray.Viewer(...);

このとき viewer 変数に代入されたオブジェクトは、概念上 mapray.Viewer クラスのインスタンスなので、 mapray.Viewer クラスのインスタンスメソッド mapray.Viewer#getElevation() を次のように呼び出すことができます。

viewer.getElevation(...);

クラスはインスタンスメソッド以外にクラスメソッドを持つこともあります。例えば mapray.GeoMath クラスにはクラスメソッド mapray.GeoMath.createMatrix() があり、JavaScript 上でもこれと同じ記法で呼び出すことができます。

mapray.GeoMath.createMatrix();

本ドキュメントではインスタンスのメンバー (インスタンスメソッドまたはインスタンスプロパティ) とクラスのメンバー (クラスメソッドまたはクラスプロパティ) は次のような記述で区別します。

JavaScript 上での名前空間はオブジェクトとそのプロパティにより実現しています。

最上位の名前空間である mapray を表現するオブジェクトは、ライブラリのインポート時に mapray 変数に代入されます。 そのオブジェクトには mapray 名前空間のメンバーと同名のプロパティを持ち、そのメンバーを表現するオブジェクトにアクセスできます。

例えばライブラリインポート後に JavaScript で mapray.GeoMath 式を評価すると、結果は mapray 名前空間のメンバーである GeoMath クラスを表現するオブジェクトになります。

そのため次のように、 mapray.GeoMath 式の評価結果を GeoMath 変数に代入すると、ソースコード上は GeoMath だけで mapray.GeoMath クラスを使うことができます。

var GeoMath = mapray.GeoMath;

GeoMath.createMatrix();
GeoMath.createVector3();

maprayJS API では最上位の名前空間がすべて mapray なので、以降本ドキュメントでは mapray.Viewer を Viewer のように省略して記述します。 実際のソースコード上では省略することができません。

一般的なコンテンツではマウス操作などにより、カメラの視点は時間の経過とともに変化します。

Camera インスタンスのプロパティを連続的に設定することにより、このようなアニメーションは可能ですが、レンダリングコールバックを 使うとこれを適切な頻度とタイミングで行うことができます。

例えば次のように RenderCallback のサブクラスを定義し、フレーム毎に呼び出される RenderCallback#onUpdateFrame() メソッドをオーバライドします。

class MyRenderCallback extends mapray.RenderCallback {
    constructor()
    {
        super();
        // 初期化コード
        ...
    }

    onUpdateFrame( delta_time )  // override
    {
        // this.viewer.camera のプロパティを更新
        ...
    }
}

そして Viewer のコンストラクタを呼び出すときに、オプションに MyRenderCallback のインスタンスを与えます。

new mapray.Viewer( container, { render_callback: new MyRenderCallback() } );

Viewer インスタンスが生成された後、定期的に MyRenderCallback#onUpdateFrame() メソッドが呼び出されます。

mapray エンジンはレンダリング時に地表の形状や地図画像のデータを、インターネットなど外部から取得します。

デフォルトの地表の形状 (DEM データ) はコンテンツのサーバーからの相対パス /dem/ から取得します。 この場合はコンテンツ提供者は /dem/ に DEM データを配置する必要があります。

これらのデータは Viewer コンストラクタにデータプロバイダを指定することによって変更することができます。

DEM データを指定するときは dem_provider オプションに DemProvider の実装クラスのインスタンスを指定します。

maprayJS ライブラリは DemProvider の実装クラスとして StandardDemProvider を用意しています。 たとえば http://server/dem/ から DEM データを取得したいときは、 Viewer コンストラクタのオプションを次のように指定します。

var provider = new mapray.StandardDemProvider( "http://server/dem/", ".bin" );
new mapray.Viewer( container, { dem_provider: provider } );

地図画像データを指定するときは Viewer コンストラクタの image_provider オプションに ImageProvider の実装クラスのインスタンスを指定します。

maprayJS ライブラリでは ImageProvider の実装クラスとして StandardImageProvider を用意しています。 たとえば http://server/map/ から地図画像データ (拡張子が .png 、サイズが 256×256、レベルが 0 から 10) を取得したいときは、 Viewer コンストラクタのオプションを次のように指定します。

var provider = new mapray.StandardImageProvider( "http://server/map/", ".png", 256, 0, 10 );
new mapray.Viewer( container, { image_provider: provider } );

maprayJS ライブラリが用意している StandardDemProvider や StandardImageProvider はサイト認証などの機能がないので、 これらだけでは不十分なことがあります。その場合、 DemProvider や ImageProvider のサブクラスをコンテンツ開発者が 実装する必要があります。詳細は「データプロバイダの作成」を参照してください。

Camera インスタンスの near プロパティ (近接平面距離) と far プロパティ (遠方平面距離) に設定する値には注意が必要です。

これらの値は mapray エンジンが内部で使用している WebGL で必要になるパラメータです。

これらの値をコンテンツ開発者が指定しなければならない理由は、そのコンテンツにとって適切な値を mapray エンジンが決定することが困難だからです。

一般的には次のことが言えますが、これらは互いに相反します。

• mapray エンジンにとって far/near の値が小さいほどよい
• コンテンツ開発者にとって near を極限まで小さく far を極限まで大きくしたい

様々な環境で高い品質のレンダリングをするためには far/near が 10000 以下になることをおすすめします。

簡単な指針としては near は手前のものが隠れない程度に大きくします。そして far は near の 10000 倍程度にします。 ただしもっと遠くを見る必要がある場合は、品質が落ちる可能性がありますが far を大きくなるように調整します。

地心座標系は、地球の中心に原点を置き、X 軸をグリニッジ子午線と赤道との交点方向に、Y 軸を東経 90 度の方向に、 Z 軸を北極の方向にとって、空間上の位置を (x, y, z) の数値の組で表現する 3 次元直交座標系です。

球面座標系は、地球を近似した半径 R = 6378137 の球体を考え(半径 R は地球楕円体モデル GRS80 の長半径と同じ値に設定しました。GRS80 は楕円体ですが、この座標系は真球を想定しています。)、空間上の点を緯度 φ 経度 λ, 高さ h の数値の組で表現します。

大まかな意味としては、 φ は赤道からの北方向を正とする角度、 λ はグリニッジ子午線からの東方向を正とする角度、 h は球体面からの空方向を正とする距離を表します。

より正確な定義として、地心直交座標系における点の座標を (x, y, z) としたとき、以下の関係式が成り立ちます。

地心座標系 (x, y, z) から球面座標系 (λ, φ, h) への変換は次のようになります。 ただし pow(x, x) + pow(y, y) > 0 という条件で、 c₁, c₂ は任意の整数になります。 (以下、pow(a, b)はaのb乗を表します)

なお、半径 R は maprayJS API で GeoMath.EARTH_RADIUS として定義されています。

視点座標系は、カメラの位置 (投影中心) を原点とし、X 軸をカメラの右方向、Y 軸をカメラの上方向、Z 軸をカメラの後ろ方向とする 3 次元直交座標系です。

カメラの位置と方向は、(地心座標系での) 視点座標系の原点位置と XYZ 軸の方向により決まります。 それは Camera インスタンスの view_to_gocs プロパティに (視点座標系から地心座標系へ位置座標を変換するための) 変換行列を設定することによって決まります。

maprayJS API が想定する 4x4 変換行列 M は、3 次元位置 ( p_x, p_y, p_z ) を次の式で変換します。

このとき、変換後の 3 次元座標は ( q_x/q_w, q_y/q_w, q_z/q_w ) とします。

Camera インスタンスの view_to_gocs プロパティに設定する変換行列 A は、次のように第 4 行が (0, 0, 0, 1) でなければなりません。

Z/X/Y 座標の Z はズームレベルを表し、 Z > 0 となる整数です。 X はそのズームレベル上のタイルの水平方向の位置、 Y は垂直方向の位置を表し、 0 <= X, Y <= pow(2,Z) - 1 となる整数です。

北緯及び南緯約 85.0511 度以上を除外した、正方形のメルカトル世界地図上に Z/X/Y 座標が定義されます。

Z 座標が z のタイルは、この正方形地図を縦横均等に pow(2,z) 分割された領域に対応します。

X 座標は一番左側のタイルが 0 で、一番右側のタイルが pow(2,z) - 1 になり、 Y 座標は一番上側のタイルの 0 で、一番下側のタイルが pow(2,z) - 1 になります。

数式で表すと、経度 λ, 緯度 φ と Z/X/Y 座標の関係は次のようになります。ここで gd はグーデルマン関数を、 c₁, c₂ は任意の整数を表します。

独自の DEM データプロバイダを定義するためには DemProvider のサブクラスを実装します。

このときサブクラスでは次のメソッドをオーバライドします。

• requestTile(z, x, y, callback)
• cancelRequest(id)
• getResolutionPower()

requestTile() は maprayエンジンがタイルをリクエストするときに呼び出すメソッドです。 このメソッドの z , x , y パラメータはタイルの座標です。 callback パラメータは、データを取得したとき、 データの取得に失敗したときに、プロバイダが呼び出す必要がある関数です。 callback は即時に呼び出さずに非同期に呼び出さなければなりません。

cancelRequest() は mapray エンジンがタイルのリクエストを取り消すときに呼び出します。 このメソッドの id パラメータは requestTile() が返したオブジェクトで、プロバイダはそれに対応する リクエストを取り消す必要があります。ただし取り消す手段がない場合は、何もする必要はありません。

getResolutionPower() が返す整数を ρ とすると、DEM データの解像度が pow(2, ρ) であることを示します。 デフォルトの実装では 8 を返すので、DEM データの解像度が 256 のときはこのメソッドをオーバライドする必要は ありません。

以下は単純な DEM データプロバイダ MyDemProvider の実装例です。

class MyDemProvider extends mapray.DemProvider {
    constructor()
    {
        super();
        // 初期化
        ...
    }

    requestTile( z, x, y, callback )  // override
    {
        var req = new XMLHttpRequest();
        req.open( 'GET', this._makeURL( z, x, y ), true );
        req.responseType = 'arraybuffer';
        req.onloadend = function ( event ) {
            var status = req.status;
            if ( req.response && (status >= 200 && status < 300 || status == 304) ) {
                callback( req.response );  // データ取得に成功 (ArrayBuffer インスタンスを返す)
            }
            else {
                callback( null );  // データ取得に失敗、または取り消し
            }
        };
        req.send();
        return req;  // 要求 ID
    }

    cancelRequest( id )  // override
    {
        id.abort();  // XMLHttpRequest#abort() でリクエスト取り消し
    }

    _makeURL( z, x, y )  // タイル z/x/y の DEM データの URL を返す
    {
        return 'http://localhost/dem/' + z + '/' + x + '/' + y + '.bin';
    }
}

独自の地図画像プロバイダを定義するためには ImageProvider のサブクラスを実装します。

このときサブクラスでは次のメソッドをオーバライドします。

• requestTile(z, x, y, callback)
• cancelRequest(id)
• getImageSize()
• getZoomLevelRange()

getImageSize() はプロバイダが提供する地図タイル画像の水平方向または垂直方向の画素数を返します。地図タイル画像は正方形でなければなりません。

getZoomLevelRange() はプロバイダが提供する地図タイル画像のズームレベルの範囲を返します。

以下は単純な地図画像プロバイダ MyImageProvider の実装例です。

class MyImageProvider extends mapray.ImageProvider {
    constructor()
    {
        super();
        // 初期化
        ...
    }

    requestTile( z, x, y, callback )  // override
    {
        var image = new Image();
        image.onload  = function() { callback( image ); };
        image.onerror = function() { callback( null ); };
        image.src = this._makeURL( z, x, y );
        return image;  // 要求 ID
    }

    cancelRequest( id )  // override
    {
        // 取り消し方法はないので何もしない
    }

    getImageSize()  // override
    {
        return 256;  // 画像サイズは 256×256
    }

    getZoomLevelRange()  // override
    {
        return new mapray.ImageProvider.Range( 0, 10 );  // ズームレベルは 0 から 10
    }

    _makeURL( z, x, y )  // タイル z/x/y の地図画像データの URL を返す
    {
        return 'http://localhost/map/' + z + '/' + x + '/' + y + '.png';
    }
}

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

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

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