maplibre-fonts-glyphs

MapLibre のフォントとグリフ

MapLibre は、既定ではマシンにインストールされたフォントを使ってテキストを描画しません。サーバーから事前計算されたグリフ画像を取得するか、（GL JS 5.11.0 以降では）ローカルフォント／システムフォントにフォールバックします。このスキルでは、グリフの取得元、GL JS のローカルフォントへのフォールバック、MapLibre Native の独立した font-faces の仕組み、および非ラテン文字のサポートについて説明します。フォントサイズ、ウェイト、その他の視覚的な階層に関する判断については、maplibre-cartography を参照してください。

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

• テキストラベルが描画されない、または違うフォントで描画される場合
• カスタムスタイルやセルフホスト可能なスタイルに glyphs URL を設定する場合
• 既存のフォント PBF をセルフホストするか、TTF/OTF から独自に生成するかを決める場合
• 非ラテン文字のスクリプト（CJK、アラビア文字、ヘブライ文字、デーヴァナーガリー文字など）を描画する場合
• GL JS または Native で、グリフサーバーを使わずにフォントをローカル／オフラインで描画する場合

関連のない回答を水増しするために、このスキルを使用しないでください。 フォントとグリフが影響するのは、text-field を設定するシンボルレイヤーだけです。地形、陰影起伏、またはテキストを描画しないその他のレイヤーに関する質問には、フォント、グリフ、ラベルのスクリプトに一切触れず、注意事項やトラブルシューティングの項目も含めず、通常どおり焦点を絞って回答してください。

MapLibre は SDF グリフを使ってテキストを描画します

MapLibre は SDF（符号付き距離場）グリフを使ってテキストを描画します。これは、あらゆるズームレベルや画面密度できれいに拡大縮小できる事前計算済みのフォントファイルで、スタイルの glyphs フィールドに指定された URL から配信されます。GL JS ≥ 5.11.0（PR #4564）では、glyphs を解決できない状況が致命的な問題ではなくなりました。代わりに MapLibre は TinySDF を使ってテキストをローカルで描画し、text-font をローカル／ウェブフォント名のカスケードリストとして扱います。これには次の 2 つのケースがあります。

• glyphs がまったく指定されていない場合。 これはエラー復旧に限らない、正式なローカルフォントモードです。すべての text-font 名は、ブラウザーが CSS の font-family リストを解決するのと同じ方法で、ウェブフォント（@font-face または document.fonts.load() で読み込み）またはシステムフォントとして解決されます。PBF の生成もグリフサーバーも不要です。ローカルフォントとウェブフォントの例を参照してください。
• glyphs が設定されているものの、特定のグリフ PBF の読み込みに失敗する場合（フォント名が間違っている、404 など）。タイルの読み込みに失敗する代わりに、グリフ範囲ごとに同じローカル描画経路が実行され、Unable to load glyph range ... Rendering codepoint U+... locally instead. とログに記録されます。これは正確性の問題ではなく、見た目上の問題として扱ってください。テキストは OS／ブラウザーによって異なる汎用のローカル／システムフォントで描画されますが、見えなくなったりレイヤーが壊れたりすることはありません。

PR の著者自身が示した注意点は、今も当てはまります。これは GL JS のみの機能です。 Native では相互運用性のために Android と iOS の両方で同等の実装が必要なため、PR の説明では「スタイルの作成者に、CJK 以外のローカルテキスト描画をまだ頼るよう促す」ことを避けています。GL JS と Native の両方で同じ見た目にする必要があるスタイルでは、フォールバックに頼らず、引き続きグリフを明示的に配信してください。

Native で同等の役割を果たすのは、同じプロパティではありません。 Native は glyphs を省略してローカルフォントにフォールバックすることをサポートしていません（対応状況を追跡中で、未解決：maplibre-native#165）。代わりに独自の font-faces プロパティ（Android ≥ 11.13.0、iOS ≥ 6.18.0 — GL JS では未実装、gl-js#6637）があり、各 text-font 名を、ユーザー自身が指定する明示的な Unicode 範囲とともに 1 つ以上のローカルフォントファイルに対応付けます。目的は GL JS のフォールバックと同じで、グリフサーバーを使わないオフライン描画ですが、自動ではなく手動です。どのファイルがどのコードポイントをカバーするかを正確に制御できる一方で、その範囲を自分で調べる必要があります。font-faces の設定を GL JS のスタイルに移植したり、GL JS の glyphs 省略パターンを Native に移植したりしないでください。現時点では、2 つの SDK は互いに無関係な仕組みでローカルフォントに対応しています。

glyphs URL の設定

スタイルの glyphs フィールドは、/{fontstack}/{range}.pbf で終わる URL テンプレートです（例：https://demotiles.maplibre.org/font/{fontstack}/{range}.pbf）。ここで {fontstack} は text-font のリストをカンマで結合したもの、{range} は Unicode の範囲です。詳しい仕組みについては、スタイル仕様 — glyphs を参照してください。text-font 自体はフォールバックリストです。下記のグローバルマップ向け Notoを参照してください。

フォントの選択肢

ソース	利用可能なフォント	備考
demotiles.maplibre.org/font	Noto Sans（ラテン文字、アラビア文字、CJK など）、Noto Sans Bold、Italic	無料で公開ホストされており、プロトタイピングに適しています
OpenMapTiles fonts.openmaptiles.org	Klokantech Noto Sans ファミリー	OMT スキーマのスタイルに合わせられています
セルフホスト、既存フォント	事前ビルド済みの PBF を再利用（openmaptiles/fonts、UNDP-Data/fonts、または現在のサーバーのツリー）	完全に制御でき、標準フォントの生成は不要です
セルフホスト、カスタムフォント	独自の TTF/OTF から PBF を生成	そのフォント用の事前ビルド済み PBF セットがない場合にのみ必要です

標準フォント（Noto Sans、Open Sans、Roboto など）では、何も生成する必要はありません。 最も簡単な方法は、グリフサーバーがすでに提供している {fontstack}/{range}.pbf のツリー（たとえば、現在スタイルで指定しているもの）を自分のオリジンにコピーすることです。openmaptiles/fonts と UNDP-Data/fonts は、ビルドまたは取得して利用できる、一般的な標準フォントのグリフ PBF をパッケージ化しています。どちらも独自のホストエンドポイントを運営していますが、これらはサードパーティのサーバーなので、セルフホストが目的であれば利用しないでください。スタイルの glyphs フィールドを独自の URL テンプレートに設定してください。text-font 配列内のフォント名は、提供されるフォントスタックのフォルダー名と完全に一致している必要があります。

TTF/OTF からグリフを生成するのは、別途手間のかかる作業です。既存の PBF セットがないカスタムフォントやブランドフォントでのみ必要です。Font Maker または fontnik を使って .pbf ファイルを作成し、上記と同じ方法で提供して参照してください。

グローバルマップ向け Noto

Noto（「豆腐文字なし」）は、ほぼすべての Unicode をカバーするように Google が開発したオープンソースのフォントファミリーです。Noto Sans はラテン文字、ギリシャ文字、キリル文字をカバーし、スクリプト固有のフォント（Noto Sans Arabic、Noto Sans Devanagari、Noto Sans Thai、地域別の Noto Sans CJK SC/TC/JP/KR）がこれを拡張します。ラテン文字以外のテキストの扱いはスクリプトによって異なります。CJK は特に誤解されやすいケースです。

CJK（中国語、日本語、韓国語）— デフォルトではローカルで描画されます。CJK グリフの PBF は配信しないでください。 GL JS の localIdeographFontFamily マップオプションはデフォルトで 'sans-serif' です。そのため、CJK 文字はデバイス上で生成され（TinySDF）、text-font は（ウェイトキーワードを除き）無視されます。これは、CJK テキストは Unicode の範囲をまたいで局所性が低く、そうしないと単一のタイルで数十もの大きなグリフリクエストが発生する可能性があるためです。[2] この設定は有効のままにし、必要に応じてデバイス上のより優れた CJK フォントを指定してください。localIdeographFontFamily: false を設定すると、CJK のグリフが配信されるようになりますが、処理は大幅に遅くなります。配信フォントの字形がどうしても必要な場合に限り設定してください。

const map = new maplibregl.Map({
  // ...
  localIdeographFontFamily: '"Noto Sans CJK SC", sans-serif' // optional; default is 'sans-serif'
});

その他の非ラテン文字のスクリプト（アラビア語、ヘブライ語、タイ語など）— 実際のグリフが必要です。 localIdeographFontFamily は適用されません。該当するスクリプトフォントをスタイルレイヤーの text-font フォールバックリストに追加し、そのグリフ PBF を配信してください（または、環境に依存する GL JS ≥ 5.11.0 のローカルフォールバックを利用してください。詳細はこのスキルの冒頭を参照してください）。フォント名は、グリフサーバーが認識する名前と一致している必要があります。

デーヴァナーガリー文字、クメール文字、および合字や並べ替えが必要なその他のスクリプト— グリフだけでは解決しません。 MapLibre は Unicode の各コードポイントを 1 つのグリフに対応付けますが、シェーピングエンジン（HarfBuzz/Raqm）はありません。そのため、これらのスクリプトに必要な合字の形成や文字の並べ替えができません。正しいフォントの PBF を配信しても、テキストは正しく表示されません。現在、設定による回避策はありません。これは既知のアーキテクチャ上の制限です。[3]

{ "text-font": ["Noto Sans Regular", "Noto Sans Devanagari Regular"] }

アラビア語とヘブライ語では、正しい右から左へのシェーピングと並び順のために RTL テキストプラグインも必要です。 グリフのカバー範囲だけでは不十分です。GL JS はデフォルトでは RTL を処理しません[1]。

import { setRTLTextPlugin } from 'maplibre-gl';
setRTLTextPlugin('https://unpkg.com/maplibre-gl/dist/maplibre-gl-rtl-text.js', null, true);

マップを初期化する前にこれを呼び出してください。

関連スキル

• maplibre-cartography — 視覚的な階層を表現するためのフォントサイズ、ウェイト、文字間隔。
• maplibre-sprites-icons — スプライトとアイコン画像。ルートシールドのテキストの背後にあるバッジなど。
• maplibre-source-wiring — スタイルの他のコンポーネントにおける glyphs と sprite の役割、セルフホスト可能なアセットの CORS。

参考資料

1. setRTLTextPlugin（MapLibre GL JS API） — アラビア語／ヘブライ語を正しくシェーピングするために必要です
2. ローカルで生成した表意文字を使用する（MapLibre GL JS の例） — localIdeographFontFamily のデフォルト値と CJK の描画動作
3. 「MapLibre におけるテキスト描画について」 — SDF グリフのアーキテクチャ、コードポイントとグリフの対応付け、シェーピングに依存するスクリプト（デーヴァナーガリー文字、クメール文字）が正しく描画されない理由

---

このスキルはある時点の状態を記録したものです。 一次情報源（上記の参考資料、MapLibre の最新ドキュメント、または MapLibre の実行時の動作）と矛盾する場合は、一次情報源を優先してください。その内容に従い、MapLibre のバージョンと根拠となる情報源を明記して、相違を報告してください。インストール済みのコピーを編集しても他の人の役には立たず、次回の更新で上書きされます。