JavaScript
geo

Mapbox Style Specification の Expression(式)の解説

背景

Mapbox Style Specifications の昨年秋からの新要素として、Expression(式)がありますが、必ずしもその説明の内容がわかりやすくありません。どうも、説明の中で、まだ使用されていないシンボルが使われていて、説明が逆向きっぽくなっているのと、例がないことが分かりにくい原因ようです。そこで、チートシートのような解説を作ってみました。計算機の用語を使っているので、計算機の用語に詳しい人にだけ分かりやすい資料になっているかもしれません。

(0)基本的な世界観と型システム

Expression(式)は、JSON Array で書かれた S式 です。S式の世界なので、即値のほかは、全てが S式 です。

Expression(式)には型システムがあり、ライブラリは型安全(type safe)に式を解釈します。型は次の通りです。

  1. boolean
  2. string
  3. number
  4. color
  5. array

string から color へのみ暗黙の変換がされます。そのほかの変換は明示的に行います。

(1)型式

1. ['array', 値]

値が array 型であると表明(assert)する。

2. ['boolean', 値]

値が boolean 型であると表明する。

3. ['collator', {'case-sensitive': boolean, 'diacritic-sensitive': boolean, 'locale': string}]

ロケール依存の比較に使う collator を返す。locale の値は IETF 言語タグ。

4. ['literal', 値]

リテラル array かオブジェクト値を返す。

5. ['number', 値]

値が number であると表明する。

6. ['object', 値]

値が object 型であると表明する。

7. ['string', 値]

値が string 型であると表明する。

8. ['to-boolean', 値]

値を boolean 型に変換する。値がから文字列、0、false、null、NaN の場合には false を返し、その他の場合には true を返す。

9. ['to-color', 値]

値を color 型に変換する。値が color 型に変換できなかった時に備え、フォールバックの値を第二、第三、...の値に入れることができる。

10. ['to-number', 値]

値を number 型に変換する。値が null か false の時は 0 を返す。値が true の時は 1 を返す。値が string 型の時は、ECMASCript の仕様どおりに変換する。to-color と同様、フォールバックの値を続けて書くことができる。

11. ['to-string', 値]

値を string 型に変換する。値が null の時は '' を返す。値が boolean 型の時は、'true' か 'false' を返す。値が number 型のときは、ECMAScript の仕様どおりに変換する。値が color 型のときは、'rgba(r, g, b, a)' の形に変換する。その他の場合は ECMAScript の JSON.stringify の仕様どおりに変換する。

12. ['typeof', 値]

値の型を示す文字列を返す。

(2)データ式

13. ['feature-state', プロパティ名]

地物の状態からプロパティの値を得る。地物の状態とは、GeoJSON やベクトルタイルの一部ではなく、地物ごとにプログラマティカルに設定されなければならない。data-driven style に対応した paint プロパティにのみ feature-state は有効である。なお、指定したプロパティが存在しなければ、null を返す。

14. ['geometry-type']

地物のジオメトリ型(Point, MultiPoint, LineString, MultiLineString, Polygon, または MultiPolygon)を文字列で返す。

15. ['id']

id があれば id を返す。

16. ['properties']

地物の properties オブジェクトを返す。['get', プロパティ名] (本稿の 18 番)を直接使った方が効率的な場合もある。

(3)取り出し式

17. ['at', インデクス, 配列]

配列から要素を取り出す。

18. ['get', プロパティ名 {, オブジェクト}]

地物(第二の引数があるときはそのオブジェクト)のプロパティ値を返す。

19. ['has', プロパティ名, {, オブジェクト}]

プロパティ値の有無を boolean 型で返す。

20. ['length', 値]

配列または文字列の長さを返す。

(4)判定式

case が基本的な if/then/else 論理に、match が入力の特定の値をそれぞれ出力式にマップすることに対応しています。基本的な判定式については、説明を省略します。

21. ['!', 真偽式]

22. ['!=', 値1, 値2]

23. ['<', 値1, 値2]

24. ['<=', 値1, 値2]

25. ['==', 値1, 値2]

26. ['>', 値1, 値2]

27. ['>=', 値1, 値2]

28. ['all', 真偽式1, 真偽式2, ...]

すべての真偽式が true の場合、true を返し、それ以外の場合は false を返す。真偽式は前から順番に評価され、最初に false が出た時点で false を返す(short-circuiting)。

29. ['any', 真偽式1, 真偽式2, ...]

いずれかの真偽式が true の場合、true を返し、それ以外の場合は false を返す。この判定式も short-circuiting する。

30. ['case', 条件式1, 返却値1, 条件式2, 返却値2, ..., デフォルト値]

対応する条件式が真になる最初の返却値を返す。デフォルト値は必須なので気をつけましょう。

31. ['coalesce', 式1, 式2, ...]

coalesce とは、結合するという意味です。式を順番に評価し、最初の非 null 値を返す。

32. ['match', 入力, ラベル1, 出力1, ラベル2, 出力2, ..., デフォルト出力]

入力とマッチするラベルに対応する出力、またはマッチしない場合にはデフォルト出力を返す。ラベルは単一のリテラル値またはリテラル値の配列でなければならない。また、値はすべて文字列、またはすべて数値でなければならない。同じマッチ式の中で数値と文字列を使うことはできない。

(5)ランプ式、スケール式、カーブ式

33. ['interpolate', 補間式, 入力, ストップ入力1, ストップ出力1, ストップ入力2, ストップ出力2, ...]

ストップ入力とストップ出力のペア(「ストップ」という)の間の連続的で滑らかな補間結果を与える。補間式については、次の通りです。

補間式

  1. ['linear']: ストップのペア間を線形補間する。
  2. ['exponential', 底]: ストップのペア間を指数関数で補間する。底が大きければストップの上界に向かって増大する。底が 1 に近ければ線形的に増大する。
  3. ['cubic-bezier', x1, y1, x2, y2]: 与えられた制御点を用いたベジェ曲線で補間する。

34. ['step', 入力, ストップ出力0, ストップ入力1, ストップ出力1, ストップ入力2, ストップ出力2, ...]

ストップ群で定義される区分的な定数関数の、離散的でステップ型の値を返す。入力は数値式であればよい。ストップ入力は厳密に昇順でなければならない。

入力の値がストップ入力1の値よりも小さければストップ出力0を返し、そうでなければ、入力よりも小さくなる最後のストップ入力に対応するストップ出力を返す。

(6)変数束縛式

35. ['let', 変数名1, 変数値1, 変数名2, 変数値2, ...]

式を名前付き変数に束縛する。

36. ['var', 変数名]

let を使って束縛した変数の値を返す。

(7)文字列式

37. ['concat', 文字列1, 文字列2, ...]

結合した文字列を返す。

38. ['downcase', 文字列]

文字列を小文字化する。

39. ['is-supported-script', 文字列]

読めるようにレンダできそうであれば true を、そうでなければ false を返す。

40. ['resolved-locale', collator]

与えられた collator で使われているロケールの IETF 言語タグを返す。デフォルトのシステムロケールを決定したり、要求されたロケールのロードが成功しているか決定したりするために使う。

41. ['upcase', 文字列]

文字列を大文字化する。

(8)色式

42. ['rgb', red, green, blue]

red, green, blue(いずれも 0 から 255)の値を用いた color 型の値を返す。

43. ['rgba', red, green, blue, alpha]

0 から 255 までの red, green, blue および 0 から 1 までの alpha コンポーネントを用いた color 型の値を返す。

44. ['to-rgba', 色]

色の 4 要素の配列を返す。

(9)数学式

45. ['-', 数値1, 数値2]

46. ['*', 数値1, 数値2]

47. ['/', 数値1, 数値2]

48. ['%', 数値1, 数値2]

49. ['^', 数値1, 数値2]

50. ['+', 数値1, 数値2]

51. ['abs', 数値]

52. ['acos', 数値]

53. ['asin', 数値]

54. ['atan', 数値]

55. ['ceil', 数値]

56. ['cos', 数値]

57. ['e']

数学的定数である e (自然対数の底か。)を返す。

58. ['floor', 数値]

59. ['ln', 数値]

数値の自然対数を返す。

60. ['ln2']

数学的定数である ln(2) (2の自然対数) を返す。パフォーマンスへの考慮なのだろう。

61. ['log10', 数値]

数値の、10を底とする対数を返す。

62. ['log2', 数値]

数値の、2を底とする対数を返す。

63. ['max', 数値1, 数値2, ...]

64. ['min', 数値1, 数値2, ...]

65. ['pi']

66. ['round', 数値]

最も近い整数に丸める。中間の値はゼロから遠い方に丸められる。たとえば ['round', -1.5] は -2 と評価される。

67. ['sin', 数値]

68. ['sqrt', 数値]

69. ['tan', 数値]

(10)ズーム式

70. ['zoom']

現在のズームレベルを返す。

(11)ヒートマップ式

71. ['heatmap-density']

heatmap-color プロパティでのみ使える式。ヒートマップレイヤでの1ピクセルについて、その画素の周りにどのくらいのデータポイントが混み合っているかを相対的に示す指標である、カーネル密度推定を返す。