maplibre-terrain-patterns

MapLibre の地形表現パターン

MapLibre GL JS では、地形をいくつかの方法で描画できます。陰影起伏図（標高データから作成する 2D の照明効果）、3D 地形（標高値とカメラの傾きを使用する押し出しメッシュ）、標高別色分け（標高値に基づく直接的な色付け）、動的等高線（実行時に生成されるベクター等高線）です。[1]、[7] これらの方法は、豊かな地形表現を作成するため、同じ地図上で組み合わせて使われることがよくあります。

これらの方法はすべて、俗に「地形タイル」と呼ばれる raster-dem ソースを使用します。このソースは標高値を PNG/WebP のピクセル値にエンコードします。[1]、[3]

DEM から従来生成される、傾斜、方位、曲率などの追加の地球観測解析レイヤーもあります。[11]、[14] これらが必要な場合は、通常 GIS ワークフローで事前に計算され、MapLibre のクライアント側で計算されるのではなく、ラスター レイヤーとして配信されます。

このスキルを使用する場面

• MapLibre の地図に陰影起伏図、標高別色分け、等高線、または 3D 地形を追加する
• raster-dem ソースを選択し、エンコード形式を理解する
• Mapbox の地形タイルからオープンな代替手段に移行する
• 地形データから動的等高線を追加する
• raster-dem 形式の地形タイルをセルフホストする
• 地形が平坦、反転、または不自然に見える場合の問題を解決する

DEM、raster-dem、陰影起伏図の違い

数値標高モデル（DEM）、raster-dem、陰影起伏図は、それぞれ異なる概念ですが、混同されることがよくあります。

DEM は、各セルに数値の標高値（たとえば、メートル単位の GeoTIFF）を格納するラスターです。[15]、[17]

MapLibre は GeoTIFF を直接読み込みません。標高はまず RGB タイル（Terrain‑RGB または Terrarium）にエンコードされ、その後、raster-dem ソースとして MapLibre に渡されます。[5]、[6] raster-dem ソースは常にピクセルごとの標高を表し、サポートされているエンコード方式（"mapbox" または "terrarium"）のいずれかを使用してデコードされます。[1]、[3]

MapLibre で陰影起伏図（または標高別色分け、等高線、3D 地形）を作成する際に最初に必要となるのは、適切な raster-dem ソースを選択して設定することです。DEM タイルの生成は計算負荷が高く、難しいうえ、高品質な地形サービスを無料または商用で利用できるため、通常は自分で生成する必要はありません。[4]、[8]

事前計算済みラスターを使用する場合（raster-dem の代わりに）

多くの場合、外部ワークフローですでに計算され、タイルとしてエクスポートされた地形表現を使用するほうが簡単です。この場合は、タイルのソースタイプを raster-dem ではなく raster に設定します。

OpenTopography や Blender などのサービス、および標準的な GIS ワークフロー（GDAL、QGIS、ArcGIS）を使うと、照明、テクスチャ、カラ―ランプを細かく調整した陰影起伏図や標高別色分けのラスターを生成できます。[14]、[21] 傾斜ラスターや、色付けと陰影を組み合わせた「色付き陰影起伏図」製品は、これらのツールで DEM から直接作成する必要があります。[11]、[20]

その利点は、レイヤーとソースの設定を最小限に抑えながら、豊かな地形表現を得られることです。また、クライアントが事前レンダリング済みのタイルを描画するだけなので、パフォーマンスも向上します。[14]、[22]

制限として、これらのラスターにはエンコードされた標高値（Terrain-RGB/Terrarium）が含まれないため、MapLibre のクライアント側での陰影起伏図や標高別色分け、3D 地形、実行時の等高線には利用できません。[3]、[23]

次のような場合は、事前計算済みラスターが適しています。

• 地形を静的な背景（地形ベースマップ、陰影起伏の背景）としてのみ使用する場合。
• プラットフォーム間で一貫した地図表現を求め、MapLibre のクライアント側で陰影起伏図や標高別色分けを再計算する必要がない場合。
• DEM のエンコードや raster-dem の設定の複雑さを避けたい場合。

setTerrain() による 3D 地形、クライアント側の陰影起伏図や標高別色分け、動的等高線など、標高に依存する MapLibre の機能が必要な場合は、Terrain‑RGB または Terrarium タイルを基盤とする raster-dem ソースをそれらのレイヤーに指定してください。たとえば、AWS Terrain Tiles、Mapterhorn、Stadia Terrarium、MapTiler Terrain RGB があります。[1]、[4]

raster-dem ソースとエンコーディング

raster-dem ソースは、PNG／WebP のピクセル値にエンコードされた標高データを提供します。MapLibre はピクセルの色を読み取り、エンコーディング形式に固有の数式を使って、標高をメートル単位に変換します。[1]、[3]

地形設定で AI が最も失敗しやすいポイントです。 MapLibre のデフォルトのエンコーディングは "mapbox"（Mapbox Terrain‑RGB の数式）ですが、主要なオープンかつ無料の DEM ソースの多く（AWS Terrain Tiles、Mapterhorn など）は Terrarium 形式を使用します。[5]、[6] 誤ったエンコーディングを指定すると、エラーがコンソールに表示されないまま、標高が誤って解釈されます。地形が平坦に見えたり、上下が反転したり、極端に誇張されたりすることがあります。

エンコーディング	数式	主なソース
"terrarium"	(R * 256 + G + B / 256) - 32768	AWS Terrain Tiles、Mapterhorn、ほとんどのオープンソース
"mapbox"	(R * 256 * 256 + G * 256 + B) * 0.1 - 10000	MapTiler terrain-rgb、Mapbox Terrain

Terrarium と Mapbox の数式は、Tilezen／Mapzen の地形処理パイプラインと Mapbox Terrain‑RGB 仕様で定義されています。[5]、[6]

スタイルを設定する前に、DEM ソースのエンコーディングを必ず確認してください。 エンコーディングはデータの特性であり、好みで選ぶものではありません。

{
  "terrain": {
    "type": "raster-dem",
    "url": "pmtiles://terrain.pmtiles",
    "tileSize": 512,
    "encoding": "terrarium"
  }
}

オープンな地形タイルソース

ソース	エンコーディング	キーの要否	備考
AWS Terrain Tiles	Terrarium	不要	オリジナルの Mapzen データセット。s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png。全世界をカバー。256px PNG。CDN を使わない場合、ブラウザーからの読み込みが遅くなることがあります
Mapterhorn	Terrarium	不要	WebP PMTiles。512px。z12 まで全世界をカバー。NLnet が資金提供するオープンソース。単一ファイルからセルフホスト可能
Stadia Maps Terrarium	Terrarium	必要（無料プランあり）	ホスト型。高速な CDN
MapTiler terrain-rgb	Mapbox	必要	ホスト型。高速な CDN
demotiles.maplibre.org	Terrarium	不要	MapLibre の公式例で使用。本番環境では使用しないでください

キーなしで本番利用する場合は、オープンな選択肢として Mapterhorn を推奨します。[4]、[8] 利用可能なホスト型エンドポイントについては、Mapterhorn を参照してください。抽出およびセルフホストについては、maplibre-pmtiles-patterns を参照してください。

陰影起伏図レイヤー

hillshade レイヤーは、raster-dem ソースを参照するように、マップスタイルのレイヤー配列で定義する必要があります。map.setTerrain() は必要ありません。陰影起伏図と3D地形は独立しています。

{
  "id": "hillshade",
  "type": "hillshade",
  "source": "terrain",
  "paint": {
    "hillshade-illumination-direction": 315,
    "hillshade-illumination-anchor": "map",
    "hillshade-exaggeration": 0.5,
    "hillshade-shadow-color": "rgba(30,40,80,0.45)",
    "hillshade-highlight-color": "rgba(255,240,200,0.4)",
    "hillshade-accent-color": "rgba(10,15,50,0.5)"
  }
}

hillshade-method は陰影アルゴリズム（standard、basic、combined、igor、multidirectional）を制御します。多方向陰影起伏図では、複数のレイヤーを重ねることなく、複数方向からの光をシミュレートして影を柔らかくできます。[9] 一部の地図製作者は、hillshade-illumination-direction の値を変えた複数の陰影起伏図レイヤーを使って、多方向の陰影を微調整しています。[10]、[11] この方法はパフォーマンスに影響する場合があります。

raster-dem ソースを使った基本的な陰影起伏図の設定については、陰影起伏図レイヤーの追加をご覧ください。

画像ベースマップ向けの配色： 暖かみのある金色のハイライト（rgba(255,240,200,0.4)）と、涼しげな青紫色の影（rgba(30,40,80,0.45)）を使うと、濁った灰色のオーバーレイを作らずに画像のコントラストを高められます。これは、John Nelson のマルチパスの美学を単一レイヤー向けに応用したものです。[10] よりすっきりとした見た目にしたいベクターベースマップでは、中立的な灰色または白のハイライトと濃い影を使います。

動的な等高線

maplibre-contour は、raster-dem ソースから実行時にベクター等高線タイルを生成します。事前生成された等高線タイルは不要です。[7]

import mlcontour from 'maplibre-contour';

const demSource = new mlcontour.DemSource({
  url: 'https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png',
  encoding: 'terrarium',
  maxzoom: 13,
  worker: true
});

demSource.setupMaplibre(maplibregl);

map.on('load', () => {
  map.addSource(
    'contour-source',
    demSource.contourSource({
      thresholds: { 11: [200, 1000], 12: [100, 500], 14: [50, 200] },
      elevationKey: 'ele',
      levelKey: 'level',
      contourLayer: 'contours'
    })
  );

  map.addLayer({
    id: 'contours',
    type: 'line',
    source: 'contour-source',
    'source-layer': 'contours',
    paint: {
      'line-color': ['interpolate', ['linear'], ['get', 'level'], 0, '#8b6914', 1, '#5c4a00'],
      'line-width': ['interpolate', ['linear'], ['get', 'level'], 0, 0.8, 1, 1.5]
    }
  });
});

maplibre-contour は、setupMaplibre を介して登録するカスタムプロトコルハンドラーを使用します。thresholds オブジェクトは、ズームレベルと、メートル単位の [minor, major] 等高線間隔を対応付けます。[7]

maplibre-contour と raster-dem タイルを使った等高線の例については、等高線の追加をご覧ください。

標高別カラー表示の地形

陰影起伏図とは異なり、標高別カラー表示では標高値の範囲に応じて色が割り当てられるため、複雑な地形のビジュアライゼーションで標高のパターンを控えめに示す場合や、標高差を一目で判別できる必要があるアプリケーションに適しています。[14]、[15]

MapLibre の color-relief レイヤータイプは、地形タイル（ソースとして raster-dem を指定）上でクライアント側にこの処理を行います。[9]、[16]

{
  "id": "color-relief",
  "type": "color-relief",
  "source": "terrain",
  "paint": {
    "color-relief-color": [
      "interpolate",
      ["elevation"],
      0,
      "#00429d",
      1000,
      "#73c1c6",
      2000,
      "#f4777f",
      3000,
      "#93003a"
    ]
  }
}

DEM に基づく標高別カラー表示のスタイル設定を使った完全なデモについては、標高別カラー表示レイヤーの追加をご覧ください。

3D 地形

3D 地形では、標高データに基づいてマップの表面を押し出します。raster-dem ソースが必要で、map.setTerrain() で有効にします。[2]、[3]

map.on('load', () => {
  map.addSource('terrain', {
    type: 'raster-dem',
    url: 'pmtiles://terrain.pmtiles',
    tileSize: 512,
    encoding: 'terrarium'
  });

  map.setTerrain({ source: 'terrain', exaggeration: 1.5 });
});

3D 地形は、ユーザーがマップを傾けたり回転させたりして標高の相対的な高低を理解する場合や、実際の起伏に重ねたオーバーレイ（建物、ルート、危険箇所など）を確認する場合に適しています。[2]

動作する3D地形の完全な例については、3D 地形をご覧ください。

カメラのピッチ

3D 地形は、カメラにピッチを設定した場合にのみ表示されます。マップの初期化時に pitch を設定するか、プログラムから設定します。[2]

const map = new maplibregl.Map({
  container: 'map',
  style: myStyle,
  center: [lng, lat],
  zoom: 12,
  pitch: 60,
  bearing: -30
});

空レイヤー

3D 地形を有効にしてカメラにピッチを設定すると、地平線が表示されます。地形の上に空レイヤーを追加して、地平線の向こう側を塗りつぶします。[2]、[3]

{
  "id": "sky",
  "type": "sky",
  "paint": {
    "sky-type": "atmosphere",
    "sky-atmosphere-sun": [0, 90],
    "sky-atmosphere-sun-intensity": 15
  }
}

地形に空と霧を組み合わせる方法については、空、霧、地形をご覧ください。

raster-dem ソースのパフォーマンスに関する注意事項

低性能なデバイスや高いピッチ／ズームでは、陰影起伏図や3D地形を有効にするための追加処理（raster-dem タイルのデコード、地形メッシュの構築、そのメッシュにドレープするレイヤーの描画）により、低いズームレベルで追加のタイル読み込みが発生したり、画面内で詳細の見え方に差が生じたりすることがあります。[13], [26]

パフォーマンスはデバイス、ズーム／ピッチ、タイルサイズ、スタイルの複雑さによって異なります。目安として、地形は小規模で用途を絞ったスタック（DEM ソースと少数の可視化レイヤー）として扱い、より豊かなビジュアルをクライアント側の負荷を増やさずに実現したい場合は、負荷の高いカートグラフィーのワークフロー（複雑な複数パスの陰影起伏図、GIS や Blender による芸術的なブレンド）を事前計算済みのラスタに移してください。[22], [24]

地形のパフォーマンスを最適化する際は、次の点も考慮してください。

• raster-dem ソースごとに、地形に依存するレイヤーを制限してください。 陰影起伏図、色別標高図、3D 地形は、すべて同じ標高タイルを読み取ります。[1], [9] 地形にドレープするレイヤー（陰影起伏図、raster、fill、line）を追加するたびに、レンダリングの総コストが増加するため、地形スタックは最小限に抑えてください。背景レイヤーを少数（たとえば、陰影起伏図または色別標高図のいずれかと画像レイヤー）にし、必要なデータのオーバーレイを加える程度にします。[12]

• 陰影起伏図レイヤーを何層も重ねるより、hillshade-method を優先してください。 より柔らかい多方向の陰影が必要な場合は、異なる照明方向の hillshade レイヤーを複数重ねる前に、hillshade-method オプション（"multidirectional" など）を使用してください。[18], [25] 同じ raster-dem ソースに対して複数の陰影起伏図レイヤーを使うと、描画パスが増え、GPU の処理負荷が高まります。

• 理由なく raster-dem ソースを重複させないでください。 3D Terrain の例では、描画品質上の理由から terrainSource と hillshadeSource を分けていますが、どちらも同じタイルを参照しています。[12] ほとんどの場合、地形関連のレイヤー（地形、陰影起伏図、色別標高図）には、共有の raster-dem ソースを1つ使用し、余分なソース設定やタイル間の干渉の可能性を避けてください。[3], [19]

• 3D 地形を有効にする場合は、特に慎重にしてください。 3D 地形では、追加の DEM タイルを読み込み、メッシュを描画するため、特にズームやピッチが高い場合に、目立つ遅延が発生することがあります。[2], [26] 誇張値は控えめに設定し、低性能なデバイスでは極端なピッチを避け、地形にドレープするレイヤーの数を少なく保ってください。

地形ピラミッドにおけるタイルサイズとズーム

ピラミッド内ではタイルごとのバイト数が変化するため、ズームを問わずタイルあたりの KB 数が一定だと仮定したアーカイブサイズの見積もりには偏りがあり、注意して扱う必要があります。ラスタタイルとは異なり、地形タイルのサイズはズームレベルを通じて一定のキロバイト数にはなりません。タイルサイズはズームと地形の複雑さの両方によって変化します。非常に低いズームのタイルは単純化されたり、より強く圧縮されたりする一方、非常に高いズームのタイルは、小さく、多くの場合、起伏が均質な地形をカバーします。主要な山脈を含む中程度のズームのタイルは、最も詳細な起伏を含むことが多く、サイズも大きくなる傾向があります。[23]

独自の DEM タイルの生成

標高データを元にカスタム DEM タイルセットを作成するには、Tilezen/Mapzen やコミュニティの地形チュートリアルで使われている標準的な DEM 処理ワークフローに従ってください。[5], [8] MapLibre は DEM タイル生成ツールを提供しておらず、raster-dem タイルを利用するだけであることに注意してください。

関連スキル

• maplibre-tile-sources — ソースタイプの選択、raster-dem ソースタイプのリファレンス。
• maplibre-source-wiring — TileJSON、レイヤーの順序、CORS、空白の地図のデバッグ。
• maplibre-pmtiles-patterns — 1つの PMTiles ファイルから DEM タイルと画像タイルをセルフホストする方法。
• maplibre-cartography — 陰影起伏図を含むスタイルの標準的なレイヤー順序。

参考資料

1. MapLibre Style Spec：raster-dem ソース — encoding プロパティ、tileSize — https://maplibre.org/maplibre-style-spec/sources/#raster-dem
2. MapLibre 3D 地形の例 — https://maplibre.org/maplibre-gl-js/docs/examples/3d-terrain/
3. RasterDEMTileSource API（MapLibre GL JS） — https://maplibre.org/maplibre-gl-js/docs/API/classes/RasterDEMTileSource/
4. AWS Terrain Tiles（オープンデータ） — https://registry.opendata.aws/terrain-tiles/
5. Tilezen/joerd のエンコーディング形式（Terrarium） — https://github.com/tilezen/joerd/blob/master/docs/formats.md
6. Mapbox Terrain‑RGB v1 タイルセット — https://docs.mapbox.com/data/tilesets/reference/mapbox-terrain-rgb-v1/
7. maplibre-contour — 実行時の等高線生成 — https://github.com/onthegomap/maplibre-contour
8. Mapterhorn 地形 PMTiles（Protomaps） — https://protomaps.com/blog/mapterhorn-terrain/
9. MapLibre Style Spec：レイヤー（hillshade、color-relief） — https://maplibre.org/maplibre-style-spec/layers/
10. John Nelson の陰影起伏表現の手法 — https://adventuresinmapping.com/2014/10/31/a-world-of-hillshading/
11. gdaldem を使ったカラーリリーフと傾斜陰影の作成（MasterMaps） — https://blog.mastermaps.com/2012/06/creating-color-relief-and-slope-shading.html
12. PMTiles のクラウドストレージに関する考慮事項 — https://docs.protomaps.com/pmtiles/cloud-storage
13. カラーリリーフを使った地形のスタイリング（MapTiler ガイド） — https://docs.maptiler.com/guides/map-design/terrain/color-relief/
14. OpenTopography のラスター可視化ツール — https://opentopography.org/blog/new-raster-visualization-tools-opentopography
15. 地形図作成の概要 — https://en.wikipedia.org/wiki/Terrain_cartography
16. カラーリリーフレイヤーの追加（MapLibre の例） — https://www.maplibre.org/maplibre-gl-js/docs/examples/add-a-color-relief-layer/
17. 地形レイヤーの構築（GEOG 486、Penn State） — https://courses.ems.psu.edu/geog486/node/868
18. 追加の陰影起伏オプション（MapLibre GL JS Issue #5665） — hillshade-method（combined、multidirectional、igor）の起点。PR #5768 によりクローズ — https://github.com/maplibre/maplibre-gl-js/issues/5665
19. 3D 地形での陰影起伏の動作（MapLibre GL JS Discussion #4131） — 実際の品質上のトレードオフについて説明しています。陰影起伏の再照明は、テクスチャのキャッシュにより 3D 地形上で回転せず、解像度が劣化する場合があります — https://github.com/maplibre/maplibre-gl-js/discussions/4131
20. ラスター地形解析（QGIS ドキュメント） — DEM から傾斜、方位、曲率を導出 — https://docs.qgis.org/latest/en/docs/user_manual/processing_algs/qgis/rasterterrainanalysis.html
21. gdal_raster_hillshade（GDAL ドキュメント） — https://gdal.org/en/stable/programs/gdal_raster_hillshade.html
22. ラスタータイルとベクタータイル（MapTiler ガイド） — https://docs.maptiler.com/guides/how-maps-work/raster-vector-tiles/
23. Terrain-RGB タイルのホスティング（MapTiler ガイド） — https://docs.maptiler.com/guides/map-tiling-hosting/data-hosting/rgb-terrain-by-maptiler/
24. Blender での陰影起伏表現（TerraLab GIS） — https://www.terralabgis.com/blog/blender-hillshade
25. 多方向陰影起伏レイヤーの追加（MapLibre GL JS の例） — https://www.maplibre.org/maplibre-gl-js/docs/examples/add-a-multidirectional-hillshade-layer/
26. 地形有効時、高ズームで FPS が大幅に低下する問題（MapLibre GL JS Issue #7699） — 執筆時点で未解決。原因は近距離ズーム時の getDEMElevation と配置・衝突判定の負荷と特定されています — https://github.com/maplibre/maplibre-gl-js/issues/7699

参考資料（このスキルでは現在引用していません — 要確認）

• Hillshade function（Esri） — https://doc.esri.com/en/arcgis-pro/latest/help/analysis/raster-functions/hillshade-function.html
• TileMill の地形データとカラーリリーフのガイド — https://tilemill-project.github.io/tilemill/docs/guides/terrain-data/
• PMTiles CLI — https://docs.protomaps.com/pmtiles/cli
• PMTiles 入門（Cloud-Native Geo Guide） — https://guide.cloudnativegeo.org/pmtiles/intro.html
• カラーリリーフマップ — 歴史と用途（Golden Software） — https://www.goldensoftware.com/color-relief-maps-history-purpose/
• カスタムヒルシェード／陰影起伏（Learn ArcGIS） — https://learn.arcgis.com/en/projects/illuminate-terrain-with-a-custom-hillshade/
• マップ用地形データ（MapTiler） — https://www.maptiler.com/terrain/
• MapLibre GL JS のサンプル一覧 — https://www.maplibre.org/maplibre-gl-js/docs/examples/
• 3D 地形チュートリアル（MapLibre 動画） — https://www.youtube.com/watch?v=D5iwM32GOpY
• 傾斜の可視化チュートリアル（Michael Minn） — https://michaelminn.net/tutorials/arcgis-pro-terrain/
• GIS でヒルシェード画像を作成する方法（動画解説） — https://www.youtube.com/watch?v=tGbJnpySAJY
• OpenTopography で DEM とヒルシェードを生成する方法（動画解説） — https://www.youtube.com/watch?v=f1m-qa-6YXo

---

このスキルは現時点のスナップショットです。 一次情報（上記の参考資料、MapLibre の最新ドキュメント、または MapLibre の実行時の動作）と内容が矛盾する場合は、一次情報を優先してください。それに従ったうえで、MapLibre のバージョンを明記し、不一致を報告してください。インストール済みのコピーを編集しても、ほかの人の役には立たず、次回のアップデートで上書きされます。