Getting Started

クイックスタート

このページでは、Navara で 3D 地図を表示するために必要な最小限のコードを説明します。最後には、衛星画像とフォトリアルな空・大気を備えた動作する地球儀が完成します。

前提条件

Node.jsと、npm・yarn・pnpm などのパッケージマネージャーがインストールされている必要があります。

プロジェクトのセットアップ

Navara はどのバンドラー構成でも動作します。このガイドでは Vite TypeScript プロジェクトを使用します。vanilla-ts テンプレートでプロジェクトを作成してください（詳細は Scaffolding Your First Vite Project を参照）。

npm create vite@latest my-navara-app -- --template vanilla-ts

yarn create vite my-navara-app --template vanilla-ts

pnpm create vite my-navara-app --template vanilla-ts

Navara はデフォルトでビューポート全体を覆うキャンバスを作成します。地球儀をフル画面で表示するには、index.html の <body> にスタイルを指定してブラウザーデフォルトのページ余白を取り除きます。

<body style="margin: 0; width: 100%; height: 100%; overflow: hidden;">
  <!-- ... -->
</body>

パッケージのインストール

Navara は npm の @navaramap スコープで公開されています。プロジェクトに、Three.js レンダラーの @navaramap/three、デフォルトプラグインの @navaramap/three-default-plugin、および peer dependencies の three と postprocessing をインストールします。

npm install @navaramap/three @navaramap/three-default-plugin three postprocessing

yarn add @navaramap/three @navaramap/three-default-plugin three postprocessing

pnpm add @navaramap/three @navaramap/three-default-plugin three postprocessing

最小限の例

3D 地球儀を作成し、衛星画像を表示し、フォトリアルな空と大気を有効にするコアコードは以下の通りです（What is Navara? に掲載しているものと同じ例です）。プロジェクトのエントリーポイント（上で作成した Vite プロジェクトでは src/main.ts）の中身をこのコードに置き換え、開発サーバーを起動してください。

Hero

import ThreeView from "@navaramap/three";
import { DefaultPlugin } from "@navaramap/three-default-plugin";

const view = new ThreeView({ useNormal: true });

const defaultPlugin = new DefaultPlugin();
view.addPlugin(defaultPlugin);

// Initialization

await view.init();

// Setup scene
defaultPlugin.addDefaultPhotorealScene();
view.atmosphere.date = new Date("2026-07-16T01:00:00Z");
view.toneMappingExposure = 10;

// Layer declaration

const raster = view.addSource({
  type: "raster-tile",
  url: "https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/BlueMarble_NextGeneration/default/GoogleMapsCompatible_Level8/{z}/{y}/{x}.jpeg",
  maxZoom: 8,
});

view.addLayer({
  type: "raster",
  source: raster,
  raster: {},
});

// Attribution

view.attribution?.add([{ attributionHtml: `Imagery courtesy of <a href="https://earthdata.nasa.gov/gibs">NASA EOSDIS GIBS</a> · Blue Marble: Next Generation (public domain)` }]);

このコードの動作

ThreeView クラスは Navara のメインエントリーポイントです。インスタンスを作成すると、Three.js のレンダラー、シーングラフ、レンダリングパイプラインがセットアップされます。useNormal: true オプションはグローブ表面の法線を有効にし、後で追加する太陽光のライティング計算に使われます。地形や Hillshade などのレイヤーは自前で法線を持つため、この例のようにそれらがない場合に必要です。

init() を呼び出す前に、プラグインを登録します。DefaultPlugin は、空、大気、ライティング、地形、ポストプロセッシングエフェクトなど、ビルトインの Descriptor タイプをすべて登録するので、初期化後にすぐ使用できます。カスタム Descriptor 用の独自プラグインを作成・登録することもできます。

init() 呼び出しは WASM GIS エンジンを初期化し、バックグラウンド処理用の Web Worker をセットアップし、レンダリングパイプラインを準備します。これはレイヤーを追加する前に完了する必要がある非同期操作です。

初期化後、addDefaultPhotorealScene() を 1 回呼ぶだけで、空、星、太陽光、大気エフェクトが追加されます。view.atmosphere.date は太陽の位置を決めます。どのマシンでも同じ見た目になるよう、UTC 文字列（"...Z"）を使ってください。toneMappingExposure はトーンマッピング後の全体的な明るさを調整します。

addSource() はデータの取得元と取得方法を登録し、addLayer() がそれをグローブ上に描画します。この例では、ラスタータイル Source で NASA の Blue Marble 衛星画像を読み込んでいます。Navara の GIS エンジンがタイル管理、LOD、空間インデキシングを自動的に処理します。

最後の view.attribution はビルトインの Attribution UI です。add() で使用しているデータソースのクレジットを表示できます。

この例ではデフォルトのカメラのまま、地球全体が見える状態です。特定の場所に移動するには、即座に移動する setCamera() か、アニメーション付きで遷移する flyTo() を使用します。

AI コーディングエージェントとの開発

Claude Code などの AI コーディングエージェントで開発する場合は、Navara リポジトリで提供している navara-usage スキルを利用できます。セットアップの順序、間違えやすい API の使い方、動作するシーンの構成例など、@navaramap/three のベストプラクティスを簡潔にまとめたガイドです。プロジェクトの skills ディレクトリにコピーする（またはエージェントに参照させる）ことで、生成されるコードが正しい API の使い方に沿うようになります。

次のステップ

この例はほんの入り口です。地形の標高を追加したり、GeoJSON データを表示したり、複数のレイヤーを組み合わせる方法を学ぶには、Basic Visualization Tutorial に進んでください。