はじめに / Introduction

現在取り組んでいるオープンソースプロジェクトの一環で、unvt/charitesを使ってArcGIS Proで作ったベクトルタイルスタイルを加工できるか試したことがあります。今回は、デモの目的で、一般に公開されているEsriさんのベクトルタイルスタイルをダウンロードしてきて、それをunvt/charitesでどのように取り扱うかを参考に紹介します。（注意：スタイルにもライセンスがありますので、今回の技術を使う場合にはそれぞれのソースデータのライセンスを確認しましょう。私の実際の作業で使っているスタイルファイルは外部に公開できないので、サンプルデータを使ったデモを行うものです。）

I just wanted to demonstrate how we can edit a style.json from ArcGIS Pro with the UNVT styling tool called unvt/charites. Therefore, with this article, I will show the procedure to use/edit the style from ESRI vector tile basemaps, which is seen by the public, with our tool unvt/charites. (Note: Style may have its license. This article is just for the demonstration purpose. I do not intend to use existing style from the website.)

目標 / Objectives

EsriのArcGIS用のArcGIS Vector Basemapsのスタイルを閲覧し、そのスタイルをunvt/charitesで加工することが技術的にできるかの確認を行う。

To open a style json from ArcGIS Pro with unvt/charites, and to edit style expression. We will try this with ArcGIS Vector Basemaps style, which is publicly available, for the demonstration purpose.

環境 / Working environment

OS Windows 10 (Enterprise)
Powershell version 5.1.19041.1237
Docker version 20.10.8
GitHub repository: https://github.com/ubukawa/arc-charites

作業 / Procedure

Step1: ソースの確認 / Confirmation of the source

Esri Vector Basemaps でベクトルタイルを確認します。この中で、OSM起源のベクトルタイルがあったので、その情報を確認しました。ベクトルタイルサーバーのデータの概要とスタイルは以下のURLになります。

Vector Tile server info: https://basemaps.arcgis.com/arcgis/rest/services/OpenStreetMap_v2/VectorTileServer
Style info: https://basemaps.arcgis.com/arcgis/rest/services/OpenStreetMap_v2/VectorTileServer/resources/styles

I have checked the vector tile informaiton at Esri Vector Basemaps. I found that there is a vector tile layer made from OpenStreetMap and its server info and style info is listed above.

Step2: レポジトリの作成、スタイルファイルの準備 / Creating a GitHub repository and pre-processing of the style file

作業用のGitHubレポジトリを作りました。Here is the GitHub repository for this work.
https://github.com/ubukawa/arc-charites
そして作業を進めます。Then, I proceeded.

2-1 スタイルファイルのダウンロード / Download the source style

まず、作業フォルダにsrcというフォルダをつくり、ソースとなるスタイルjsonを置くことにします。Powershellを開いて、対象となるスタイルファイルroot.jsonをダウンロードしてきます。
First, I made a directory "src" to store the style file. Then, I downloaded the targeted style file using powershell script as below.

cd src
curl.exe -O https://basemaps.arcgis.com/arcgis/rest/services/OpenStreetMap_v2/VectorTileServer/resources/styles/root.json

2-2 JSONファイル中のスラッシュの処理 / Replace the slash in the style file

Esriのスタイルファイルには往々にして、レイヤidにスラッシュが含まれるので、これを(slash)という文字列に置き換えます。現在のcharitesはレイヤidをファイル名として使っており、この関係でレイヤidにスラッシュがあるとうまく動きません。置換で一括でできますが、sprite、glyphs、soucesのスラッシュまで置換しないように気をつけます。1-slash.jsonという名前で保存しておきます（ここ）。

A style file made by ArcGIS Pro often includes slash(/) in its layer "id." This is not good because our tool unvt/charites uses the layer id as the name of converted YAML file. Therefore, I just replaced the "/" with a text "(slash)". The actual file can be seen here. Please make sure the slashes in sprite, glyphs and source are kept as they are.

（注意 / Attention）
今回のファイルにはなかったですが、テキストフォントなどでフォントの指定の時に二つのフォントを指定しているとcharitesでは読めません（maputnikなどでも読めないと思います）。そのような場合は、今回の作業では一つにしておきましょう。
If you specify two (or more) types of text fonts in a single "text-font" as string array, please keep only one of them for this work. unvt/charites cannot use string array for text-font as some of other tools cannot do either. This was not the case for this practice though.

2-3 Docker（unvt/nanban）でYAMLファイルにインポート / Starting Docker (unvt/nanban) and convert json into YAML files

パワーシェルで、上のフォルダに戻って、Dockerを始めます。あとでライブプレビューをするのでポート8080を開けておきます。
スタイル作業用のcharites-styleというフォルダを作ったあと、charites convertを使って、先ほどダウンロードして下処理したファイルをYAMLファイルに加工します。

On the powershell, I started Docker (unvt/nanban) with the following command. Please confirm that I opened the port 8080 so that I can use the port 8080 for the local hosting of the live preview at later stage. I created "charites-style" directory, and convert the edited style file (JSON) into a series of YAML files under the chrites-style directory.

cd ..
docker run -it --rm -v ${PWD}:/data -p 8080:8080 unvt/nanban
cd /data
mkdir charites-style
charites convert src/1-slash.json charites-style/style.yml

作成されたyamlファイルを見てみます。conversion の時に指定したcharites-styleファイルの中に、style.ymlとlayersフォルダができています。layersフォルダの中には、レイヤidと同じ名前のyamlファイルが複数（レイヤとおなじ数だけ）できているはずです。

After importing a json file into YAML files, we had a style.yml and a series of layer files (yml) in the layers directory. Each file in "layers" directory has information for each style layer.

作成されたcharites-style/style.ymlファイルをcharites-style/style-original.ymlとして残しておきますが、style.ymlファイルに少し手を入れます。
We made a copy of the original style.yml as style-original.yml, and further edited the style.yml (Go next step).

2-4 style.ymlの調整 / Adjusting style.yml

sprite, glyphs, and sources

style.ymlのsprite、glyphsの場所を編集します。charitesで使うので、ArcGIS用のスタイルからの相対パスから絶対パスに直します。今回の作業の場合、"../" は　https://basemaps.arcgis.com/arcgis/rest/services/OpenStreetMap_v2/VectorTileServer/resources になります。そのあと、sourceのurlも修正します。tilesとして指定するので、pbfタイルのパスをきちんと記入します。

First, we needed to work on the style.yml to adjust the locations of sprites and glyphs. The originial values used relative path from the style file in the ArcGIS server, so we changed it to an absolute path below so that we can use it in unvt/charites. In addition, we modify the source information. Instead of using "url" to specify the vector tile serve, we use "url" to directly specify the path to the vector tile (PBF).

list of layers

つづいて、同じstyle.ymlのlayersもチェックします。レイヤーの一覧がありますが、ここで不要な改行や >-が含まれることがあります（下図）。インプットファイルの書き方が悪いのか、charitesの不具合で起きているのかなと思います。作業を進めるために不要な改行を消します。レイヤ数が多い場合は置換するとすぐにできます。なおしたファイルはこちら。

Then, we needed to check the list of layers in the same style.yml. It was a little strange, but we saw unnecessary line changes and ">-" (see below figure). I suppose they were due to the bugf of unvt/charites. To proceed, I just modified the list. It was easy editing by using "replace" function of the text editor. You can confirm fixed file here.

こういう改行もあるので直します。置換を使って効率的にやりましょう。
I also experienced line changes like in the below figure. Using replace, and I fixed them efficinently.

Step 3 charitesを使ってlocalhostでサーブ / Serving style locally using charites

YAMLファイルの準備ができたらホスティングをします。charitesのserveコマンドを使って、YAMLファイルで記載しているスタイルをホストします。

Once the yaml files were ready, I started local server hosting using the "serve" function of unvt/charites as below. We can just host the style defined by the series of YAML files.

charites serve charites-style/style.yml

すると、http://localhost:8080 から現在のYAMLファイルで表現されているスタイルのLive Previewが見られます。F12を押せばPBFの参照先も確認できますね。（Dockerの起動時にポート8080を開けましたが、ほかのポートを使いたい場合はDockerの立ち上げ時に開けるポートをいじるのと、charitesの設定をいじりましょう。）

Vector tile map was displayed at http://localhost:8080. If you want to use another port, you can do so by changing the config setting. The series of YAML files were used to draw the map. I have confirmed the source of the vector tile (in pbf) by typing F12.

Step 4 YAMLファイルを編集してみる / Editing YAML file(s) to change the style

Live Previewを開いたままで、YAMLファイルを編集してみます。ためしにbackgroud.ymlの色を編集して保存してみました。Live Previewが自動的にアップデートされます。海の色が青になると思ったらバックグラウンドは陸地でしたね。

I kept the live preview open, and edited the yaml file to change the style. For trial, I edited backgroud.yml to make the background color blue. Charites automatically detected my edit and update the style. Oops, background was for land, not for the sea...

今度は、ocean関係のレイヤの色も編集してみました。自由に色を変えることができます。
Then, I changed the color of the ocean and adjusted the color of the background.

こんな感じでスタイルを変更することができます。スタイルレイヤの追加や削除も自分ですることが可能です。
（CharitesはMapLibre GL JSやMapbox GL JSで描画しています。ArcGISでは一部のスタイル表現（match等）に対応していないので、自分でスタイル情報を書いていく場合には注意しましょう。）

As such, by editing yaml files, you can easily edit the style. You can also add/delete any of style layers by your self. Please be informed that unvt/charites uses MapLibre GL JS / Mapbox GL JS libraries. ArcGIS does not fully adopt to some expression used in these libraries (e.g. match). It would be a good idea to use an easy style description for ArcGIS style.

Step 5　YAMLファイルからJSONファイルへの出力 / Building a json style from YAML files

自分のスタイルの編集が終われば、今度はスタイルをJSONファイルに出力します。ArcGISのスタイルとして戻す場合には、yamlファイルのうちに、2-5で加工したsprite, glyphs, sourcesの情報をもとに戻します。jsonになった後に、(slash)の文字列を/に戻すという作業を忘れないでやりましょう。

After completing the style editing with YAML files, now, we can convert the style back to the JSON file. If you want to use your json style in ArcGIS, we need to return some descriptions (see step 2-5) such as sprite, glyphs and sources. And, after we get the json, it is also important to replace "(slash)" back to the "/". The following sub-chapters will explain them.

5-1 sprite, glyphs, sourceをもとに戻す / Returning sprite, glyphs and source information.

style.ymlをstyle-out.ymlという名前でコピーして編集します。最初に読み込んだymlファイルも参考にして、ArcGIS用の設定に戻します。

I made a copy of style.yml and named it as style-pout.yml, which is yaml file for exporting. Then, I retruned the sprite, glyphs and sources description for ArcGIS consumption (see below figure).

5-2 jsonファイルの出力 / Exporting JSON file from yaml files

charites build コマンドで以下の通りjsonファイルに出力します。ここではstyle-out.jsonというファイルが出力されました。

I exported JSON style by running the following command. Remember, we used style-out.json for exporting work.

charites build charites-style/style-out.yml style-out.json

5-3 slashの置換 / Replacing "(slash)"

一番最初に置き換えておいた(slash)をもとに戻します。名前をstyle-out-final.jsonとして保存しておきました。
We already exited from unvt/charites, so we returned "(slash)" back to "/" as showed in the following figure.

以上で、またArcGISで使えるスタイルが出力されました。
All done. We now have a edited style for ArcGIS consumption.

まとめ / Wrap up

ArcGISのスタイルをunvt/charitesで編集するということを試して、きちんと作業ができることを確認しました。

I have demonstrated how we can use unvt/charites for styling work for ArcGIS.
One of the benefit of using style.yml is that you can keep all layer information in separate yaml files. Such yaml files are re-usable for your future project.
chariets also provide local live preview which will enhance the efficiency of the work.

References

unvt/charites: https://github.com/unvt/charites
Esri Vector Basemaps: https://www.arcgis.com/home/group.html?id=30de8da907d240a0bccd5ad3ff25ef4a#overview
GitHub repository: https://github.com/ubukawa/arc-charites
How to edit/modify a style.json of your vector tile map using UNVT/charites: https://qiita.com/T-ubu/items/e6794b81e45dea34548c