Getting Started¶

Mapray JS を用いたアプリケーション開発の方法を説明します。

事前準備¶

Mapray JS は地形データをはじめとする基本リソースを Mapray Cloud から取得して動作します。このため、Mapray JS を動作させるには、あらかじめ API KeyかAccess Token(Organization token/User token)を取得しておく必要があります。特にMapray CloudのDatasetにアクセスするには、APIKey or Organization Tokenが必要になります。 Organization TokenやUserに関する操作が必要な場合は、User Tokenを活用してMapray JSと共にW3C標準WebAPI等を用いてMapray Cloudにアクセスして下さい。詳細は以下を参照してください。

Mapray JS がサポートしているWebブラウザについては動作環境ページをご参照ください。

Info

本ドキュメントで掲載しているサンプルコードやコードスニペットは、<YOUR_MAPRAY_API_KEY>と<YOUR_MAPRAY_ACCESS_TOKEN>を、それぞれ、あなたのAPI KeyまたはAccessTokenに置き換えるまで、期待通り動作しません。Mapray Cloudにアカウント登録をしていただき、これらを取得して置き換えて下さい。

アクセス方法	コード内の文字	置き換え方
API Key	`<YOUR_MAPRAY_API_KEY>`	Mapray Cloudで取得したAPI Key
Access Token	`<YOUR_MAPRAY_ACCESS_TOKEN>`	Mapray Cloudで取得したOrganization Token

Note

現在、Mapray JSはバージョンによってご提供方法が異なります（バージョンに関するする参考リンク)。プロジェクトでMapray JSを使用するには、0.9.6以下の場合は、Mapray JS CDNを使用してインポートするか、mapray-js npmパッケージをインストールする必要があります。0.10.0以上の場合は、ローカルで読み込むかnpm packageをインストールします。

Note

Latest Versionでは簡単にAccess Tokenを利用できるAPIを準備しています。0.9.6まではAPI Keyで実装するのがシンプルなため、以下のCDN版説明では

0.9.6のサンプルはAPI Key
0.10.0以上を利用しているサンプルはAccess Token

を用いています。CDNのサンプルにAPI Keyを使ったサンプルを掲載しています

以上をまとめると

バージョン	提供方法	アクセス方法	備考
0.9.6	CDN / npm packages	API Key	実装がシンプルなため、本ドキュメントでは主にこの形で説明
0.10.x以上	ローカル配布（利用は要問い合わせ） / Github packages	Access Token	APIにより簡単かつセキュアに利用可能。ローカル配布版で説明を行うが、package版でも利用可能

になります。

アプリケーションの作成¶

Local Latest Version CDN 0.9.6Module bundler (webpack)Module bundler (rollup)

Mapray Cloud で配信されるスクリプトファイル等を直接参照してご利用いただくことができます。下記のように、 HTML ファイルの <head> タグ配下に JavaScript と CSS ファイルを記載します。 CSS は Mapray のロゴやその他リソースを表示するために必要になります。

<script> タグに Mapray の Viewer を呼び出す処理を記載します。コード中の token には、Mapray Cloud で取得したAccess Tokenを入力します。 Access Tokenを適切に設定すれば、Read/Write権を細かく活用したトークン管理が可能になります。

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <script src="./v0.10.0/mapray.min.js"></script>
        <script src="./v0.10.0/maprayui.min.js"></script>
        <link rel="stylesheet" href="./mapray.css">
        <style>
            html, body, div#mapray-container { margin: 0; padding: 0; height: 100%; }
        </style>
    </head>
    <body>
        <div id="mapray-container"></div>
    </body>
</html>

<script>
    // Set up your access token, which can be created in Mapray Cloud.
    const cloudApi = new mapray.cloud.CloudApiV2({
        tokenType: mapray.cloud.CloudApi.TokenType.ACCESS_TOKEN,
        token: "<YOUR_MAPRAY_ACCESS_TOKEN>"
    });

    // The StandardUIView in the ui package includes mouse-based camera manipulation.
    var viewer = new maprayui.StandardUIViewer( "mapray-container", {
        dem_provider: new mapray.StandardDemProvider( cloudApi.getDefaultDemAsResource() )
    } );
</script>

Info

このサンプルコードは、<YOUR_MAPRAY_ACCESS_TOKEN>を、あなたのMapray CloudアカウントのOrganization Tokenに置き換えるまで、期待通りに動作しません。

Mapray Cloud で配信されるスクリプトファイル等を直接参照してご利用いただくことができます。下記のように、 HTML ファイルの <head> タグ配下に JavaScript と CSS ファイルを記載します。 CSS は Mapray のロゴやその他リソースを表示するために必要になります。

<script> タグに Mapray の Viewer を呼び出す処理を記載します。コード中の apikey には、Mapray Cloud で取得したAPI Keyを入力します。

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

<script>
    // Set up your apikey, which can be created in Mapray Cloud.
    const apikey = "<YOUR_MAPRAY_API_KEY>";

    // The StandardUIView in the ui package includes mouse-based camera manipulation.
    const uiViewer = new maprayui.StandardUIViewer( "mapray-container", apikey );
</script>

プロジェクト作成

本説明では、最終的に下記のようなディレクトリ構成となります。

.
├─ package.json        Node の設定ファイル
├─ node_modules/       Node の依存ライブラリが保存されるディレクトリ
├─ webpack.config.js   ビルド設定ファイル
├─ src/                ソースファイルのディレクトリ
└─ dist/               ビルド後の js が出力されるディレクトリ

空のディレクトリを作成し、ディレクトリ内で下記を実行します。

npm init -y
npm install webpack webpack-cli st --save-dev
npm install @mapray/mapray-js @mapray/ui

package.json が生成され、 node_modules ディレクトリ内に mapray 及びビルドツールなどがインストールされます。

続いて、 webpack.config.js を作成します。

const path = require('path');

module.exports = {
    entry: './src/index.js',
    output: {
        filename: 'bundle.js',
        path: path.resolve(__dirname, 'dist'),
    },
};

実装

src/index.js を作成します。コード中の apikey に、Mapray Cloud で取得したAPI Keyを入力します。

import maprayui from "@mapray/ui";

window.startApp = container => {
    // Set up your apikey, which can be created in Mapray Cloud.
    const apikey = "<YOUR_MAPRAY_API_KEY>";

    const viewer = new maprayui.StandardUIViewer( container, apikey );
};

package.json の scripts 要素内に下記のようにコマンドを追加します。

{
    :
    "scripts": {
        "build": "webpack --mode=production",
        "server": "st --no-cache -H 0.0.0.0 --port 7777 --index index.html -d dist"
    }
    :
}

ビルドします。

npm run build

dist/bundle.js が生成されます。

dist/index.html を作成します。ビルドした js ファイルを読み込み startApp() を呼び出します。

<html>
    <head>
        <meta charset="utf-8"/>
        <script type="text/javascript" src="./bundle.js"></script>
        <link rel="stylesheet" href="https://resource.mapray.com/styles/v1/mapray.css">
        <style>
            html, body, div#mapray-container { margin: 0; padding: 0; height: 100%; }
        </style>
    </head>
    <body onload="window.startApp('mapray-container')">
        <div id="mapray-container"></div>
    </body>
</html>

開発用サーバの起動

サーバを起動します。

npm run server

http://localhost:7777 へアクセスします。

プロジェクト作成

本説明では、最終的に下記のようなディレクトリ構成となります。

.
├─ package.json        Node の設定ファイル
├─ node_modules/       Node の依存ライブラリが保存されるディレクトリ
├─ rollup.config.mjs   ビルド設定ファイル
├─ src/                ソースファイルのディレクトリ
└─ dist/               ビルド後の js が出力されるディレクトリ

空のディレクトリを作成し、ディレクトリ内で下記を実行します。

npm init -y
npm install rollup @rollup/plugin-node-resolve rollup-plugin-postcss postcss st --save-dev
npm install @mapray/mapray-js @mapray/ui

package.json が生成され、 node_modules ディレクトリ内に mapray 及びビルドツールなどがインストールされます。

続いて、 rollup.config.mjs を作成します（ rollup の設定ファイル）。

import postcss from "rollup-plugin-postcss";
import pluginNodeResolve from "@rollup/plugin-node-resolve";

export default {
    input: "src/index.js",
    output: {
        file: "dist/bundle.js",
        format: "iife",
    },
    plugins: [
        postcss(),
        pluginNodeResolve(),
    ],
}

package.json の scripts 要素内に下記のようにコマンドを追加します。

{
    :
    "scripts": {
        "build": "rollup -c",
        "server": "st --no-cache -H 0.0.0.0 --port 7777 --index index.html --dir ./dist"
    }, 
    :
}

実装

src/index.js を作成します。コード中の apikey には、Mapray Cloud で取得したAPI Keyを入力します。

import maprayui from "@mapray/ui";
import "../node_modules/@mapray/ui/dist/mapray.css";

window.startApp = container => {
    // Set up your apikey, which can be created in Mapray Cloud.
    const apikey = "<YOUR_MAPRAY_API_KEY>";

    const viewer = new maprayui.StandardUIViewer( container, apikey );
};

ビルドします。

npm run build

dist/bundle.js が生成されます。

dist/index.html を作成します。ビルドした js ファイルを読み込み startApp() を呼び出します。

<html>
    <head>
        <meta charset="utf-8"/>
        <script type="text/javascript" src="./bundle.js"></script>
        <style>
            html, body, div#mapray-container { margin: 0; padding: 0; height: 100%; }
        </style>
    </head>
    <body onload="window.startApp('mapray-container')">
        <div id="mapray-container"></div>
    </body>
</html>

Nodeで開発用サーバを起動する

サーバを起動します。

npm run server

http://localhost:7777 へアクセスします。