maplibre-cartography

MapLibre のカートグラフィ

MapLibre は、スタイルで指定した内容をそのまま描画します。このスキルでは、どのように指定すればよいかを説明します。あらゆるベースマップで読みやすいラベルの色の選び方、一貫性のある視覚的階層の構築方法、スタイルレイヤーを正しい順序で並べる方法を扱います。フォント／グリフの設定については maplibre-fonts-glyphs を、スプライト、アイコンの入手方法、ルートシールドについては maplibre-sprites-icons を参照してください。

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

• リリース前に、スタイルが地図製作のベストプラクティスに沿っているかを確認するとき
• 新規または移行後のスタイルで、ラベルの text-color や text-halo-color、またはポイントシンボル／アイコンの色を選ぶとき。フラットなベクターベースマップでは問題なく読めても、ベースマップが画像になると見えなくなったり背景に紛れたりするケースも含みます
• sprite、アイコン、ルートシールドを設定またはデバッグするときは maplibre-sprites-icons を参照してください。glyphs については maplibre-fonts-glyphs を参照してください
• ラベルを覆い隠さずに、既存のベースマップへ独自のデータレイヤーを挿入するとき
• 明るいベースマップ向けのベクターパレットで道路のスタイルを変更し、画像の上に重ねるのではなく、画像になじませるとき
• スタイルのコントラストアクセシビリティを監査するとき

ベースマップの種類によってラベルの色が決まります

MapLibre はラベルを動的に配置するため、静的な地図のように各ラベルの背後にある背景をマスクすることはできません。その代わり、ラベルが配置される可能性のあるあらゆる背景からラベルを際立たせる text-halo-color と、ハローに対して読みやすい text-color を選びます。単一で均一な色調のベースマップ（フラットな明色または暗色のベクターマップ）では、コントラストを付ける代わりに、ハローをその色調に合わせられます。テキスト自体がベースマップとのコントラストを作るためです。画像には合わせられる単一の色調がないため、どのような背景に対してもコントラストを付けるハローが必要です。

ベースマップの種類	背景	推奨するテキスト色	推奨するハロー
明るいベクター（streets、OpenFreeMap positron）	淡色／白色	暗色（#333 など）	明るい半透明（rgba(255,255,255,0.8)）
暗いベクター（dark-matter、navigation night）	暗色	白またはそれに近い色（#ffffff）	暗い半透明（rgba(0,0,0,0.75)）
衛星画像または航空画像（NAIP、Sentinel-2）	予測不能 — 明るい農地、暗い森林、都市の屋根	白（#ffffff）	暗い半透明（rgba(0,0,0,0.75)）

最もよくある間違いは、透明度のない白いハローです。背景が純白でない限り、ラベルとラベルが示す地物との空間的なつながりが損なわれるため、透明度を加えてください。次によくあるのは、明るいベクター向けのパレットを画像の上で再利用することです。暗い地形、森林、水域ではうまく機能しません。画像では、必ず白いテキストと暗い半透明のハローを使用してください（"text-color": "#ffffff"、"text-halo-color": "rgba(0,0,0,0.75)"、"text-halo-width": 1.2）。

色付きのラベル（公園、水域、POI）には、彩度の高い暗色ではなく、意味を表す色の明るい色合い（公園なら #c8f5cc、水域なら #a8d8ff）を使ってください。明るい色合いなら暗いハローの上でも読みやすく、意味も伝わります。一方、彩度の高い色は小さいサイズではコントラストが弱くなります。

ハロー幅

ハローを太くすると視認性は上がりますが、視覚的な重みも増します。一般的な値は次のとおりです。

用途	text-halo-width
本文ラベル（都市、町、村）	0.8–1.5
国／大陸（大きなテキスト）	1.5–2.0
小さな POI または山頂のラベル	0.8–1.2
色付きテキストの水域／公園ラベル	1.0–1.5

text-halo-width の単位は、テキストに対するピクセルです。ハローが隣接するラベルににじまないようにしてください。小さなテキストでは細く保ち、透明度を加えます。

画像上のポイントシンボルとアイコン

マーカーもラベルと同じ図と地の問題に直面しますが、使う手法は異なります。航空写真上の色付きアイコンは、予測しにくく情報量の多い、彩度の低い 写真背景と競合します。

• 色相を背景に支配されているシンボルは、背景から分離できません。 緑の公園に緑のアイコン、むき出しの土に茶色のアイコンを置くと、どちらも背景に溶け込みます。航空写真のほとんどは彩度が低いため、背景が最も弱い軸は彩度です。彩度の高い塗り（アンバー、テラコッタ）なら、自然で大地を思わせる色合いを保ちながら分離できます。色相だけを別のアースカラーに変えても、その色相が画像内にあれば効果はありません。
• icon-halo-color／icon-halo-width でシンボルをくり抜くように際立たせます。 ラベルにハローを付ける場合と同じです。ただし、これは SDF スプライト画像（addImage(..., { sdf: true }) を使う場合、または SDF として作成されたスプライト）にのみ適用されます。フルカラーのラスターアイコンにはハローのペイントプロパティがないため、エッジ処理は画像自体にあらかじめ組み込む必要があります。薄い明るいハローは暗い樹冠や水面に対して見やすく、暗い縁取りは明るい土や屋根に対して効果的です。ステッカーのように見えるため、太い輪郭は避けてください。ただし、地図上で目立たせることを目的としたシンボル（緊急マーカー、または最重要の主題フィーチャー）では、太い輪郭がその役割を果たします。
• 単色の塗りは、写真上でステッカーのように見えます。 地形や 3D シンボルには、立体感の手がかりを加えてください。グラデーション（光が当たる斜面を明るく、陰になる斜面を暗くする）で形状を表現できます。底面の下に広がる、ぼかした平たい楕円形の 接地影 は、ずらしたドロップシャドウよりもはるかに効果的にシンボルを地面に定着させます。後者はシンボルが浮いているように見せてしまいます。シンボルが地形と同じ光の中にあるように見せるため、シンボルの光と影の向きをベースマップの hillshade-illumination-direction（一般的には北西、315°）に合わせてください。

addImage を使った SVG アイコン： 実行時に SVG をスプライト画像として読み込む場合（SVG を取得し、Image としてデコードしてから map.addImage を実行）、SVG はデコード時にラスタライズされるため、linearGradient と feDropShadow フィルターは正しく焼き込まれます。[1] 注意点は 2 つあります。ハローや影がアイコンの端で切れないように viewBox に余白を設けること、またグリフが歪まないように width／height を viewBox の縦横比に合わせることです。ポイントデータが密集している場合は、"icon-allow-overlap": true を使用してください。

視覚的な階層

適切な階層とは、ラベルと線／ポリゴンのデータレイヤーの両方について、各ズームレベルで最も重要なフィーチャーが適切に目立つことです。ラベルの階層は、テキストサイズ、フォントの太さ、字間、コントラスト、ズーム範囲に応じた表示によって MapLibre が制御します。線とポリゴンにも同じ手法が適用されます。line-width と塗りの彩度がテキストサイズに相当し、ベースマップとのコントラスト（落ち着いた背景に彩度の高い線、情報量の多い背景に落ち着いた塗り）は、サイズと同じくらい階層を表現するのに役立ちます。線／ポリゴンの事例の詳細は、下記の 画像上のベクター道路のスタイリング を参照してください。

フィーチャークラス別のテキストサイズ

フィーチャーの重要度が低くなるにつれて、テキストサイズも小さくします。次の値は出発点です。タイルスキーマとズーム範囲に合わせて調整してください。

ラベルの種類	基準ズーム	最大ズーム	サイズ範囲（px）
大陸	1	4	14–20
国	2	7	11–17
都市	7	11	14–24
町	10	14	11–16
村／集落	11	16	10–14
空港／POI	10	16	12–14
山頂／頂上	8	13	10–11

POI ラベルは、同じズームレベルの居住地ラベルより視覚的に控えめ（小さく、細いウェイト）にします。なだらかな丘陵などの穏やかな地形を示す衛星画像地図では、山頂ラベルを空港ラベルより小さくします。これらは標高の目印であり、主要なランドマークではありません。

フォントウェイト

text-font（例：["Noto Sans Bold"]）を使って、フォントウェイトで階層を強調します。国と首都には 太字、町、都市、大半のラベルには レギュラー、水域、公園、地域には イタリック を使います（地図製作の慣習ですが、現在は必ずしも守られていません）。

複数行ラベル

コンパクトな2行ラベル（例：記号の上に名前を表示する場合）では、間隔が空きすぎないように text-line-height を1.0未満にします。

{
  "text-field": "△\n{name:latin}",
  "text-line-height": 0.9,
  "text-max-width": 8
}

0.9前後の値にすると、小さなサイズでも行間が詰まり、読みやすい2行ラベルになります。標準的なフォントサイズで行が重なるため、約0.8未満にはしないでください。

テキストの変換と間隔

• 国と大陸のラベルには、地図製作の慣習に従って "text-transform": "uppercase" を使います
• 地域ラベルには "text-letter-spacing": 0.05–0.1 を使い、領域全体に文字を広げます

衛星画像上のベクター道路のスタイル設定

明るいベースマップスタイル（OSM Bright、OSM Liberty）のベクター道路パレットは、彩度の高い暖色系の色相と不透明度を使い、淡い紙面上で目立つように調整されています。ベースマップが衛星画像になると、同じ特性が画像と競合します。衛星画像を主役、道路をその上に重ねる参照用オーバーレイとして扱い、その逆にはしないでください。

• 彩度を大きく下げます。 塗りつぶしとケーシングを、ニュートラルなグレーや落ち着いた色調に近づけます。鮮やかなオレンジ／黄色の道路階層（#f90、#fd4、#b06010）が最もよくある問題です。塗りつぶしは明るいグレーに、ケーシングは濃いグレーか、色相を保った深い色に置き換えます。
• 色相ではなく、幅と明度で階層を示します。 幅の段階ですでに高速道路 ＞ 住宅道路という区別が表現されているため、目立つ色で示す必要はありません。
• 透明ではなく、不透明にします。 半透明の道路では衛星画像のテクスチャが透けて見え、地図全体が平坦になります。道路をくっきりと重ねるには、明度を抑えたケーシングと不透明な塗りつぶしを使います。
• ケーシングで道路を縁取ります。 塗りつぶしより暗いケーシングを使うと、中央線が引かれ、上下線が一つの塊に見えるのを防げます。 ノックアウトケーシング には、無関係な黒ではなく、塗りつぶしと同じ色相のより深い色合いを使います。こうすると、強い漫画風の輪郭線を付けずに縁を明確にできます。
• ズームレベルに応じて明るさを調整します。 高ズーム向けに調整した道路は、表示開始時の低ズームでは重く見えがちです。この段階では細い主要道路だけが表示され、ケーシングが目立ちます。ズームに応じて色を補間します。低ズームではケーシングを暗くし、ズームインするにつれて明るくします。ネットワークが表示されるにつれて、塗りつぶしは最も明るい要素になるように明るくします。

{
  "line-color": ["interpolate", ["linear"], ["zoom"], 10, "#454545", 12, "#5a5a5a", 14, "#6e6e6e"]
}

スプライトとアイコン

スプライトの設定、複数のスプライトシートの読み込み、スプライトアセットのセルフホスト、SVG からのスプライトの作成、ルートシールドの診断については、maplibre-sprites-icons を参照してください。

スタイルレイヤーの順序

MapLibre は、スタイルの layers 配列に記述された順序でスタイルレイヤーを描画します。最初の項目が最初（下）に、最後の項目が最後（上）に描画されます。この順序を誤ると、データレイヤーがベースマップのラベルを覆い隠すことが最もよくあります。

挿入パターン

実行時に既存のベースマップスタイルへ独自のデータを追加する場合は、データレイヤーを最初のシンボルレイヤーの前に挿入します（map.getStyle().layers.find((l) => l.type === 'symbol')?.id で取得し、addLayer の第2引数として渡します）。こうすると、ジオメトリがラベルの下に描画されます。この引数を指定しないと、データレイヤーはラベルも含め、すべてのレイヤーの上に表示されます。

カスタムスタイルの標準的なレイヤー順序

スタイルを最初から作成する場合は、下から上へ次の順序にします。

1. background
2. ラスター画像（衛星画像／航空写真ソースを使用する場合）
3. 陰影起伏レイヤー（使用する場合は、設定についてmaplibre-terrain-renderingを参照してください）
4. 地形の塗りつぶし（水域、陸地、公園などのポリゴンレイヤー）
5. ラインレイヤー（道路、境界線、河川）
6. 独自のデータのポリゴンレイヤーとラインレイヤー
7. ベースマップ独自のシンボルレイヤー（地名ラベル、道路ラベル）
8. 独自のデータのシンボル／ラベルレイヤー（使用する場合）

陰影起伏はラスター画像のすぐ上、すべてのベクターレイヤーの下に配置し、画像が透けて見えるよう十分な透明度を設定します。画像に透明度を加えて陰影起伏の上に重ねると、画像が色あせたり白っぽく見えたりします。ベクターレイヤーの上に陰影起伏を適用すると、ラインや塗りつぶしの色がまだらになったり、ぼやけたり、くすんだりします。

アクセシビリティ

MapLibre のスタイルは、ブラウザー内で WebGL キャンバスとして描画されます。アクセシビリティに関する考慮事項は次のとおりです。

• テキストのコントラスト： WCAG 2.1 AA では、通常のテキストに 4.5:1、大きなテキストに 3:1 が求められます（SC 1.4.3）。rgba(0,0,0,0.75) のハロー上に白いテキストを配置すると、ほとんどの背景でこの基準を満たします。テキスト単体ではなく、WebAIM Contrast Checkerのようなツールでテキストとハローを組み合わせた色を確認してください。
• 色だけに頼らないでください： 色相に加えて、形状、サイズ、パターンを使用してください。
• ラベルの最小サイズ： ズームレベルが低くても、10px から始まるサイズの停止点を使用してください。
• スクリーンリーダーと WebGL キャンバス： MapLibre のキャンバスは、スクリーンリーダーで本質的に利用できるものではありません。アクセシブルな地図を提供するには、データテーブルや地図の内容を説明するテキストなど、アクセシブルな代替手段を用意してください。

関連スキル

• maplibre-sprites-icons — sprite のベース URL と {id, url} 配列形式、スプライトのセルフホストと作成、addImage を使った実行時の画像、およびルートシールドについて説明します。
• maplibre-fonts-glyphs — glyphs URL の設定、フォント PBF のセルフホストまたは生成、GL JS のローカルフォントフォールバック、MapLibre Native の font-faces、およびラテン文字以外の文字体系のサポートについて説明します。
• maplibre-tile-sources — データセットに GeoJSON とタイルのどちらを選ぶかについて説明します。
• maplibre-source-wiring — TileJSON、source-layer、レイヤー順序、CORS など、設定済みのソースを描画する方法について説明します。
• maplibre-pmtiles-patterns — PMTiles ファイルから画像（ラスター）および地形ソースを配信する方法について説明します。
• maplibre-terrain-rendering — 陰影起伏、カラーレリーフ、等高線、3D 地形の設定について説明します。

参考資料

1. Map.addImage()（MapLibre GL JS API）

---

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