カスタム フォント

カスタムフォント

ArcGIS Maps SDK for JavaScript でラベルやテキストシンボルに独自のフォントを使用する場合は、ビューおよび使用する機能に応じた形式のフォントファイルを用意する必要があります。

2D の MapView でクライアントサイドで描画されるラベルや TextSymbol では、pbf 形式のフォントが使用されます。3D の SceneView および renderPreviewHTML() では、woff2 などの Web フォントが使用されます。

デフォルトでは、これらのフォントファイルは Esri が https://static.arcgis.com/fonts でホストしているものを使用できます。使用可能なフォントの一覧は、Esri のガイドで確認してください。デフォルトで提供されていないフォントを使用する場合は、必要な形式のフォントファイルを作成して Web サーバーから配信します。このガイドでは、独自のフォントを pbf および woff2 形式へ変換し、ArcGIS Maps SDK for JavaScript から参照する手順を紹介します。

本ガイドでご紹介する手順に関しては ESRIジャパンの技術サポートサービスの対象外となります。予めご了承ください。また、フォントの変換・配置を行う場合は、利用されるフォントの利用規約を予めご確認ください。

フォントファイルの作成

使用するファイル形式

ArcGIS Maps SDK for JavaScript で使用されるフォントファイルは pbf、woff2 の 2 種類ありますが、これはどのような状況でフォントを使用するかによって異なります。

2D の MapViewでは、MapImageLayer 以外のすべてのレイヤーおよび TextSymbol に pbf 形式のフォントファイルが使用され、renderPreviewHTML() には woff2 形式が使用されます。

3D の SceneView では、MapImageLayer 以外のすべてのレイヤーおよび TextSymbol3DLayer に ttf、otf、woff、または woff2 形式のフォントファイルが使用され、renderPreviewHTML() には woff2 形式が使用されます。また、3D の SceneView では、https://static.arcgis.com/fonts にあるフォントファイルは woff2 形式でのみ使用されます。

デフォルトで利用可能なフォントの一覧は、Esri のガイドで確認してください。これらのフォントファイルは Esri が https://static.arcgis.com/fonts でホストしているものを使用でき、アプリでラベルを描画するには、この URL へアクセスできる必要があります。この URL にアクセスできない場合、たとえばネットワークから切断されたオフライン環境の場合、またはこの URL でホストされていないフォントを使用したい場合は、config.fontsUrl プロパティを設定することで独自のフォントファイルを参照するように構成できます。フォントを表示するには、正しいファイル形式のフォントファイルを用意する必要があります。使用するフォント形式は、ビューと対象機能によって異なります。必要な形式と主な取得元については、次の表を参照してください。

ビュー	対象クラスまたは機能	使用する形式	主な取得元
2D および 3D	`MapImageLayer`	TTF、OTF、WOFF、WOFF2	ユーザー環境および Web ブラウザー
2D および 3D	`renderPreviewHTML()`	WOFF2	Esri または独自のフォントサーバー
2D	`MapImageLayer` 以外のレイヤー	PBF	Esri または独自のフォントサーバー
3D	`MapImageLayer` 以外のレイヤー	TTF、OTF、WOFF、WOFF2	ユーザー環境、Esri または独自のフォントサーバー

フォントの入手

今回は Google Fonts からフォントをダウンロードして pbf または woff2 形式に変換します。

pbf フォントの作成

ArcGIS Maps SDK for JavaScript の 2D 表示で独自のフォントを使用する場合は、pbf 形式で作成されたフォントファイルを用意します。pbf ファイルは符号付き距離フィールドのセットとして以下の URL で配信する必要があります。これは Mapbox GL JS のスタイル仕様と同じです。
https://<サーバー名>/fonts/<フォントスタック>/<ユニコード文字範囲>.pbf

本手順では Protobuf SDF Font Glyph Builder コマンドラインツールを使って pbf 形式のフォントファイルを作成します。

Protobuf SDF Font Glyph Builder (build_pbf_glyphs) は、Rust で作成されたコマンドラインツールです。本記事では、Ubuntuなどの apt パッケージマネージャーを使用できる Debian 系 Linux 環境を前提とし、ターミナル上で操作します。
Windows 上で直接インストールする場合は、Rust に加えて、Microsoft C++ Build Tools などのビルド環境が必要です。

ビルドに必要なパッケージのインストール
最初にパッケージ情報を更新します。
```
sudo apt update
```
続いて、コンパイラー、CMake、curl、zlib の開発用ファイルなどをインストールします。
```
sudo apt install -y \
  build-essential \
  cmake \
  pkg-config \
  curl \
  zlib1g-dev
```
Rust のインストール
Protobuf SDF Font Glyph Builder は Rust で作成されているため、Rust のビルド環境をインストールします。
```
curl --proto '=https' --tlsv1.2 -sSf \
  https://sh.rustup.rs | sh
```
インストール後、現在のターミナルに環境変数を反映します。
```
source "$HOME/.cargo/env"
```
Protobuf SDF Font Glyph Builder のインストール
Cargo を使用して Protobuf SDF Font Glyph Builder をインストールします。
```
cargo install build_pbf_glyphs
```
インストールされるバージョンによって、コマンドのオプションや動作が記事の記載と異なる場合があります。本記事の動作確認バージョンは 1.5.1 です。
作業フォルダーの作成
変換元フォント用のフォルダーと、変換結果の出力フォルダーを作成します。
```
mkdir -p ~/pbf-font-work/fonts
mkdir -p ~/pbf-font-work/glyphs
```
ttf ファイルの配置
事前にダウンロードしたフォントファイルを手順 4 で作成した fonts フォルダーにコピーします。
```
cp \
  <ダウンロード済みフォント ファイルのパス>/NotoSerifJP-Regular.ttf \
  ~/pbf-font-work/fonts/
```

pbf ファイルへ変換
次のコマンドを実行します。

build_pbf_glyphs \
  ~/pbf-font-work/fonts \
  ~/pbf-font-work/glyphs

基本的なコマンド形式は次のとおりです。

build_pbf_glyphs <入力フォルダー> <出力フォルダー>

変換が完了したら、出力結果を確認します。

find ~/pbf-font-work/glyphs -maxdepth 2 -type f | head -n 20

次のように、フォント名のサブフォルダー内へ Unicode の文字範囲ごとの pbf ファイルが生成されていれば成功です。

glyphs/
└── Noto Serif JP Regular/
    ├── 0-255.pbf
    ├── 256-511.pbf
    ├── 512-767.pbf
    └── ...

既存の pbf ファイルを再生成する場合は、--overwrite オプションを指定します。

build_pbf_glyphs \
  --overwrite \
  ~/pbf-font-work/fonts \
  ~/pbf-font-work/glyphs

Web サーバーにフォントを配置
ArcGIS Maps SDK for JavaScript から利用できるように、生成した pbf ファイルを Web サーバーに配置します。
たとえば次の構成にします。
```
fonts/
└── NotoSerifJP-regular/
    ├── 0-255.pbf
    ├── 256-511.pbf
    ├── 512-767.pbf
    └── ...
```
フォントを配置するフォルダー名は <フォントファミリー>-<ウェイト>-<スタイル> の形式 (例：arial-bold-italic) としてください。なお <スタイル> は省略可能です。
必要に応じて、Web サーバーの MIME タイプに .pbf (binary/octet-stream) を登録してください。

woff2 フォントの作成

ArcGIS Maps SDK for JavaScript の 3D 表示で独自のフォントを使用する場合は、Web フォントとして参照できる woff2 形式のフォントファイルを用意します。

本手順では、Python ライブラリーの FontTools を使用して、ttf 形式のフォントファイルを woff2 形式へ変換します。

本記事では、Windows 上で Python および FontTools を使用し、コマンドプロンプトからフォントを変換する手順を説明します。FontTools の現行パッケージは Python 3.11 以降のバージョンが必要です。また、woff2 の圧縮および展開には、Brotli の Python 拡張モジュールが必要です。

Python の確認
コマンドプロンプトを起動し、Python がインストールされていることを確認します。FontTools の現行パッケージは Python 3.11 以降のバージョンが必要です。
```
python --version
```
python コマンドが見つからない場合は、Python Launcherの py コマンドを確認します。py コマンドが実行できる場合は、以降の手順の python コマンドは py コマンドに読み替えて実行してください。
```
py --version
```
作業フォルダーの作成
次のコマンドから、作業フォルダーを作成します。本手順では、C:\work\font-convert を作業フォルダーとして使用します。
```
mkdir C:\work\font-convert
cd /d C:\work\font-convert
```
Python 仮想環境の作成・有効化
作業フォルダー内に Python の仮想環境を作成します。
```
python -m venv .venv
```
作成した仮想環境を有効化します。
```
.venv\Scripts\activate.bat
```
FontTools と Brotli のインストール
pip を更新します。
```
python -m pip install --upgrade pip
```
続いて、FontTools と woff2 の処理に必要な Brotli をインストールします。
```
python -m pip install fonttools brotli
```
変換用フォルダーの作成
変換元フォント用と変換結果用のフォルダーを作成します。
```
mkdir fonts
mkdir woff2
```
変換する ttf ファイルを fonts フォルダーへ配置します。本手順では以下のように配置します。
```
C:\work\font-convert\fonts\NotoSerifJP-Regular.ttf
```

ttf ファイルを woff2 へ変換
FontTools の fontTools.ttLib.woff2 モジュールを使用して変換します。

python -m fontTools.ttLib.woff2 compress "fonts\NotoSerifJP-Regular.ttf" -o "woff2\NotoSerifJP-Regular.woff2"

基本的なコマンド形式は次のとおりです。

python -m fontTools.ttLib.woff2 compress "<入力ファイル>" -o "<出力ファイル>"

Web サーバーにフォントを配置
ArcGIS Maps SDK for JavaScript から利用できるように、生成した woff2 ファイルを Web サーバーに配置します。
たとえば次の構成にします。
```
fonts/
└── woff2/
    └── NotoSerifJP-regular.woff2
```
woff2 ファイルは esri/config オブジェクトの fontsUrl プロパティに指定する URL 配下の woff2 フォルダーに配置してください。
必要に応じて、Web サーバーの MIME タイプに .woff2 (font/woff2) を登録してください。

ArcGIS Maps SDK for JavaScript アプリでのカスタムフォントの利用

参照するフォント URL を変更
esri/config オブジェクトの fontsUrl プロパティに Web サーバーに配置したフォントフォルダーの URL を設定します。
カスタムフォントを設定
TextSymbol クラスの font プロパティに設定する Font クラスを使ってフォントを指定できます。このクラスで指定した、family、weight、style の各プロパティの値をもとに esri/config オブジェクトで指定されたフォント URL へリクエストが行われます。フォントに複数スタイルが存在しない場合は style プロパティは省略できます。weight プロパティも省略できますが、コード上で指定しない場合は regular が自動で設定され、https://<サーバー名>/fonts/<フォント名>-regular にリクエストされます。

以下は、2D マップ用に作成した pbf フォントを使ったアプリ画面とサンプルコードです。

<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="UTF-8">
    <title>カスタム フォント - MapView</title>

    <!-- ArcGIS Maps SDK for JavaScript のロード -->
    <script type="module" src="https://js.arcgis.com/5.1/"></script>

    <style>
      html, body, arcgis-map {
        width: 100%;
        height: 100%;
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <!-- マップ コンポーネントを使用したマップの作成 -->
    <arcgis-map basemap="dark-gray" center="139.7525775,35.6850492" zoom="15">
      <arcgis-zoom slot="top-left"></arcgis-zoom>
    </arcgis-map>

    <script type="module">

      // モジュールのロード
      const config = await $arcgis.import("@arcgis/core/config.js");
      const Graphic = await $arcgis.import("@arcgis/core/Graphic.js");

      // カスタム フォントのパスを設定
      config.fontsUrl = "https://<サーバー名>/fonts";

      // arcgis-map 要素の取得
      const arcgisMap = document.querySelector("arcgis-map");
      await arcgisMap.viewOnReady();

      // グラフィックの作成
      const textGraphic = new Graphic({
        geometry: {
          type: "point",
          longitude: 139.7525775,
          latitude: 35.6850492
        },
        symbol: {
          type: "text",
          color: "black",
          haloColor: "white",
          haloSize: "2px",
          text: "カスタム フォント",
          font: {
            size: 24,
            // カスタム フォントの名前を設定
            family: "NotoSerifJP",
            weight: "normal"
          }
        }
      });
      // MapView にグラフィックを追加
      arcgisMap.view.graphics.add(textGraphic);
      
    </script>
  </body>
</html>

続いて、3D シーン用に作成した woff2 フォントを使ったアプリ画面とサンプルコードです。

<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="UTF-8">
    <title>カスタム フォント - SceneView</title>

    <!-- ArcGIS Maps SDK for JavaScript のロード -->
    <script type="module" src="https://js.arcgis.com/5.1/"></script>

    <style>
      html, body, arcgis-scene {
        width: 100%;
        height: 100%;
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <!-- マップ コンポーネントを使用したシーンの作成 -->
    <arcgis-scene basemap="dark-gray" center="139.7525775,35.6850492" zoom="15">
      <arcgis-zoom slot="top-left"></arcgis-zoom>
    </arcgis-scene>

    <script type="module">

      // モジュールのロード
      const config = await $arcgis.import("@arcgis/core/config.js");
      const Graphic = await $arcgis.import("@arcgis/core/Graphic.js");

      // カスタム フォントのパスを設定
      config.fontsUrl = "https://<サーバー名>/fonts";

      // arcgis-scene 要素の取得
      const arcgisScene = document.querySelector("arcgis-scene");
      await arcgisScene.viewOnReady();

      // グラフィックの作成
      const textGraphic = new Graphic({
        geometry: {
          type: "point",
          longitude: 139.7525775,
          latitude: 35.6850492
        },
        symbol: {
          type: "text",
          color: "black",
          haloColor: "white",
          haloSize: "2px",
          text: "カスタム フォント",
          font: {
            size: 24,
            // カスタム フォントの名前を設定
            family: "NotoSerifJP",
            weight: "normal"
          }
        }
      });
      // SceneView にグラフィックを追加
      arcgisScene.view.graphics.add(textGraphic);
      
    </script>
  </body>
</html>

コンポーネントアプリ開発