How Navara Works
ヘッドレスアーキテクチャ
Section titled “ヘッドレスアーキテクチャ”Navara はヘッドレス 3D マップエンジンです。GIS コアは Rust で書かれ WebAssembly にコンパイルされており、特定のレンダリング技術から意図的に分離されています。現在、Navara は Three.js ベースのレンダリングバックエンド（@navaramap/three）を提供していますが、将来的には他のレンダリングエンジンやネイティブプラットフォームもサポートできるよう設計されています。
Rust/WASM GIS エンジンはレンダラーとは独立してすべての地理空間計算を処理し、CPU 負荷の高いタスクは Web Worker に分散されるため、大規模データセットでもレスポンシブなパフォーマンスを維持します。
プラグインベースアーキテクチャ
Section titled “プラグインベースアーキテクチャ”Navara はプラグインシステムを使用してDescriptorを登録します。init() を呼び出す前に、ThreeView インスタンスにプラグインを追加します。各プラグインは、提供するメッシュ、ライト、エフェクトのDescriptorを登録します。初期化後、登録されたDescriptorを使ってオブジェクトを追加できます。
DefaultPlugin（@navaramap/three-default-plugin から提供）は、ビルトインのメッシュ、ライト、エフェクトのDescriptorを登録します。ほとんどのアプリケーションでは、DefaultPlugin を追加するだけで始められます。
独自のメッシュ、エフェクト、ライトをレンダリングエンジンのシーングラフへのフルアクセスを持って作成することもできます。これは Navara のビルトインオブジェクトを支えるのと同じ仕組みです。詳細は Custom Descriptor ドキュメントを参照してください。
これらに加えて、Navara は GeoJSON、MVT、3D Tiles などの地理データを読み込み・表示するためのレイヤーを提供しています。レイヤーは、パース、空間インデックス、FeatureEvaluator による属性ベースのスタイリングといった、地物とその属性の複雑さを扱います。一方、メッシュ Descriptor はジオメトリとレンダリングのみを扱うため、描画パフォーマンスに特化した最適化が可能で、大量のオブジェクトを効率的にレンダリングするのに適しています。この分離により、ユースケースに応じて適切なツールを選択できます。Descriptor タイプの詳細は レイヤーの種類 を参照してください。
階層型 API
Section titled “階層型 API”Navara は API を異なる安定性保証を持つ階層に整理しています。一般ユーザーにはシンプルで安定したインターフェースを、プラグイン開発者には必要に応じてより深い機能へのアクセスを提供します。
Tier 0: ThreeView はすべてのユーザーの主要なエントリーポイントです。カメラ位置設定、レイヤー管理、プラグイン登録、ライフサイクル制御のための高レベルメソッドを提供します。この API 面は意図的にコンパクトかつ安定に保たれており、破壊的変更にはメジャーバージョンの更新が必要です。詳細は ThreeView API リファレンスを参照してください。
Tier 1: Plugin + ViewContext はプラグインおよびDescriptor開発者が利用できます。プラグインが初期化されると、シーン、パス管理、レンダラー参照などのレンダリング内部への制御されたアクセスを提供する ViewContext を受け取ります。このレベルはより多くの機能を提供しますが、マイナーバージョン間で破壊的変更が発生する可能性があります。詳細は Plugin および Custom Descriptor ドキュメントを参照してください。
Tier 2: Advanced は、外部レンダラーの注入やレンダーループの置き換えなど、より深い統合が必要な将来のユースケースのために計画されています。これらの API は明示的に不安定としてマークされます。
ほとんどのアプリケーションでは、Tier 0 の ThreeView クラスとのみやり取りすることになります。
ライブラリ一覧
Section titled “ライブラリ一覧”Navara は複数の npm パッケージに分かれています。一見複雑に見えるかもしれませんが、この分離はヘッドレス設計に直接由来します。GIS エンジンはいかなるレンダラーからも独立しており、レンダリングバックエンドは別のレイヤーであり、Descriptor実装はコアから分離されているため、必要なものだけを選択できます。
実際には、ほとんどのアプリケーションで必要なのは 2 つのパッケージだけです。コアエンジンの @navaramap/three と、ビルトインDescriptorの @navaramap/three-default-plugin です。
| Package | Role | When you need it |
|---|---|---|
@navaramap/three | メインパッケージ: ThreeView クラス、Source & レイヤー API、カメラ制御 | 常に必要 |
@navaramap/three-default-plugin | ビルトインのメッシュ・ライト・エフェクト Descriptor を登録する DefaultPlugin | ほぼ常に必要 |
@navaramap/three-default-descs | 個別のDescriptorクラス実装 | DefaultPlugin を使わず手動でDescriptorを登録する場合 |
@navaramap/three-api | スタンドアロン GIS ユーティリティ（座標変換、測地線計算） | フルマップエンジンなしで GIS 計算が必要な場合 |
ドキュメントの見方
Section titled “ドキュメントの見方”このドキュメントは、システムの異なる部分に対応する複数のセクションで構成されています。
three セクションは、ThreeView API、カメラ制御、レイヤーの概念、ステップバイステップのチュートリアルなど、@navaramap/three に関するすべてをカバーします。Navara でアプリケーションを構築する場合、最も多くの時間を費やすセクションです。
three_default_descs セクションは、@navaramap/three-default-descs が提供するすべてのメッシュ、エフェクト、ライトのDescriptorリファレンスです。各Descriptorには、設定オプションと使用例を記載した専用ページがあります。
three_default_plugin セクションは、DefaultPlugin API のドキュメントで、一般的なセットアップのための便利なメソッドも含みます。
guides セクション（現在のセクション）には、このイントロダクション、コミュニティリソース、コントリビューター向けドキュメントが含まれています。
次のステップ
Section titled “次のステップ”まだ最初の地球儀を作っていない場合は、Getting Started に進んでください。Three.js レンダラーについてさらに深く知るには、What is navara_three? に進みましょう。