UP | HOME
  • mapray JSのオープンソースを公開しているGithub.comへのリンク

UIライブラリ

ここでは、Mapray UIライブラリの概要と、利用手順を説明します。

1. Mapray UIライブラリとは

Mapray UIライブラリは、MaprayのUI操作を容易に行うことができる補助ライブラリです。

Mapray UIライブラリを導入すると、 StandardUIViewer を使用できます。これは、Maprayの Viewer を継承し、基本的なUI操作を行うことができるものです。マウスやキーボードの基本操作について処理の記述が不要になりますので、手軽にMaprayを利用することが可能です。

ライブラリの利用は、JavaScriptファイルを <script> で直接読み込む方式（以下CDN方式）と、npmパッケージでモジュールとして読み込む方式（以下モジュール方式）のどちらかで読み込みます。

モジュール方式 

import maprayui from "@mapray/ui";

CDN方式 

<script src="https://resource.mapray.com/ui/v0.9.4/maprayui.min.js"></script>

2. StandardUIViewer

Mapray UIライブラリには、 StandardUIViewer が含まれています。

StandardUIViewer は基本的なUI操作を処理できますので、定義するだけでビューワーとして動作します。

コンストラクタでは、3つの引数を指定します。

  1. コンテナ - Maprayを表示する要素
  2. アクセストークン - Maprayのアクセストークン
  3. Viewerのオプション - Mapray Viewerのオプション（省略可能）

モジュール方式 

import mapray from "@mapray/mapray-js";
import maprayui from "@mapray/ui";

const node = document.getElementById("id");      // HTMLElement要素を取得します
const ACCESS_TOKEN = "<your access token here>"; // 事前に取得した値を指定します。

const stdViewer = new maprayui.StandardUIViewer( node, ACCESS_TOKEN );

CDN方式 

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title>LongitudeAndLatitudeCameraPosSample</title>
        <script src="https://resource.mapray.com/mapray-js/v0.9.4/mapray.min.js"></script>
        <script src="https://resource.mapray.com/ui/v0.9.4/maprayui.min.js"></script>
        <link rel="stylesheet" href="https://resource.mapray.com/styles/v1/mapray.css">
        <style>
            html, body {
                height: 100%;
                margin: 0;
            }

            div#mapray-container {
                display: flex;
                position: relative;
                height: 100%;
            }
        </style>
    </head>

    <body>
        <div id="mapray-container"></div>
    </body>
</html>

<script>
    // Access Tokenを設定
    var accessToken = "<your access token here>";

    // Viewerを作成する
    viewer = new maprayui.StandardUIViewer(
        "mapray-container", 
        accessToken
    );
</script>

<your access token here> にMaprayのアクセストークンを記入します。アクセストークンはMapray Cloudから取得します。詳しくはドキュメントをご覧ください。

3. StandardUIViewer の操作

マウス操作

操作 動作
左クリック + ドラッグ 移動
中クリック + ドラッグ クリック点を中心に回転
右クリック + 前後ドラッグ ズーム
Crtlキー + 左クリック + ドラッグ カメラを中心に回転
Shiftキー + 左クリック + ドラッグ クリック点を中心に回転
Shiftキー + 右クリック + ドラッグ 高度移動、左右移動

キーボード操作

操作 動作
カーソルキー上下 前進、後退
カーソルキー左右 方向回転
cキー 画角の拡大
zキー 画角の縮小
xキー 画角の初期化（60度）

4. StandardUIViewerの応用的な使い方

StandardUIViewerの応用的な使い方について説明します。

4.1. URLHashの利用

URLHashを利用して表示位置を指定したり、現在の位置をアドレスバーに表示できます。

4.1.1. URLHashによる表示位置指定

URLで位置ハッシュを持つものを与えられると該当する位置を表示します。

例 

http://ip/#35.1907986956/138.8507189384/480.23312a/74.00000t/47242.87843r/33.72390h

4.1.2. アドレスバーの更新設定

  1. enableURLUpdate
enableURLUpdate( readUrlOnStart: boolean )

表示している位置をURLHashにしてアドレスバーのURLを更新します。 引数にtrueを指定すると、呼び出し時に指定されているURLHashの位置を表示します。

  1. disableURLUpdate
disableURLUpdate()

アドレスバーのURLの更新をしないようにします。

4.1.3. URLHashの内容

# の後に、 / で区切って表記されます。 

#35.1/135.6/2000a/45t/1000r/0.0h
記号 内容 省略時
無し latitude 省略不可※
無し longitude 省略不可※
末尾a altitude 8000m
末尾t tilt 0（真下を見る）
末尾r range 1000m
末尾h heading 0（真南から見る）

※ #記号の直後はlatitude/longitudeである必要があります

latitude, longitude, altitudeで示される地点から、range分離れた位置にカメラを設置します。カメラの姿勢はtilt, headingで指定できます。

ご注意
URLHashはカメラの位置姿勢から都度生成されます。地表DEMデータの精度は地表に近い状態のDEMデータが読み込まれていると高精度になりますが、地表から離れていたり、まだDEMデータが読み込まれていない場合には低精度となるため誤差が生じることがあります。

4.1.4. URLHash補助関数

URLHash補助関数を利用することで、ユーザが独自のパラメーターをURLHashに追加できます。（すでに定義されている記号と重複しないようにご注意ください） createCameraParameterHash で現在のURLHash文字列を生成し、独自パラメーターを追加してアドレスバーに反映する等で実現できます。

  1. createCameraParameterHash
    createCameraParameterHash(): string

    現在のカメラ位置から、URLHash文字列を生成して取得します。 URLHashが生成できないときは、length0の文字列が返ります。

  2. getCameraParameterFromHash
    getCameraParameterFromHash( hash: string ): StandardUIViewer.HashCameraParameter | undefined

    URLHash文字列を引数で与えると、カメラパラメーターが返ります。 カメラパラメーターは、位置、視点位置、ヨーの値です。

4.2. 2点間のカメラアニメーション

指定した位置間でカメラアニメーションを行います。 

async startFlyCamera( options: StandardUIViewer.FlyParam )

iscs_start で指定した位置、もしくは現在のカメラの位置から、 iscs_end で指定した位置から20km南側、上方向に+20kmの高度の位置から iscs_end を注視点とした位置と方向に time で指定された秒数でカメラアニメーションを行います。 途中、高度200kmまでカメラが上昇します。 アニメーション中はユーザによる視点の操作は受け付けられません。 アニメーション終了時に onEndFlyCamera が呼び出されます。

optionsの内容

パラメータ 型 内容 省略
time number 移動までにかかる時間（秒） 不可
iscs_start mapray.GeoPoint スタート位置。 省略時は現在のカメラ位置 可能
iscs_end mapray.GeoPoint 終了位置でのカメラの注視点。 target_clamp が true の場合は高度を自動計算 不可
target_clamp boolean 終了位置でカメラの注視点を iscs_end の緯度経度位置直下の標高にするなら true 省略時は true 可能
end_altitude number 最終カメラ位置の高さ(m) 省略時は20000m 可能
end_from_lookat number 最終カメラ位置を南方向に注視点からどの位置に配置するか(m) 省略時は20000m 可能

4.3. オーバーライドでのカスタマイズ

StandardUIViewerの関数をoverrideすることで、細かな動作をカスタマイズすることができます。

4.3.1. 開始と終了

  • onStart
  • onStop

4.3.2. 画面更新

  • onUpdateFrame
  • onBlur

4.3.3. キーのイベント

  • onKeyDown
  • onKeyUp

4.3.4. マウスのイベント

  • onMouseDown
  • onMouseMove
  • onMouseUp
  • onMouseWheel

4.4. その他詳細

詳細は リファレンスマニュアル を参照してください。