Skip to content

Draw many polylines as raster tiles (PolylineTiler) - #34

Merged
wf9a5m75 merged 8 commits into
developfrom
feat/polyline-tiling
Nov 10, 2026
Merged

wf9a5m75 merged 8 commits into
developfrom
feat/polyline-tiling

Conversation

@wf9a5m75

@wf9a5m75 wf9a5m75 commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

なぜ

ポリゴンと同じように、ポリラインも数万本を渡せるようにするためです。ボストン市内の道路(54,645 本・234,765 頂点)をネイティブの線で描くと、iOS の Google で全 onAdded まで 114 秒・1.5 GB、Android の Google は Java ヒープが尽きて落ちます。ポリゴンのタイル化(feat/polygon-tiling)と同じ仕組みで、多数のポリラインをラスタータイルとして描きます。

設計の要点(web・Android・iOS で同じ)

  • Polylines(states): Polygons と同じ形のまとめて渡す部品。そのインスタンスが足した id だけを足し引きするので、複数の Polylines / Polyline が同じ地図で共存できます(iOS は既存の Polylines(_:) のまま)。
  • PolylineTilingOptions / PolylineTileSet / PolylineTiler / PolylineController.tiler: 名前と既定値(2,000 本以上または頂点 50,000 以上)はポリゴンと 1 対 1。レイヤー id は mc-polyline-tiles。
  • ポリゴンのタイル化と内部を共通化: タイル集合(ルート・URL の版・16 ms のまとめ・削除)、振り分け、描画(格子索引・ズームごとの簡略化・LRU キャッシュ・無効化・スクラッチのプール・PNG・キャンセル)を内部の ShapeTileSet / ShapeTiler / ShapeTileRenderer に移し、Polygon* はその上の薄い層になりました。公開 API は追加のみです。
  • 描き方: 開いた経路として、ズームの画素格子に丸め → 重複を捨て → Douglas-Peucker 0.5 px(両端は残す)。round cap / round join。線幅は画面上の幅(dp / pt / CSS px)でズームに依らない。候補は線幅の半分だけタイルの外まで引き、はみ出す分もそのまま描くので、タイルの境目で線が切れません。1 px 未満に潰れた線は線幅の点で描きます。
  • タイルにできないもの: geodesic、2 点未満、経度幅 180° 以上。その場の変更でそうなった線はネイティブ描画へ移ります(onAdded は呼ばない)。破線・キャップの指定は API に無いので対象外です。
  • onAdded: ポリゴンと同じ規則(初めて地図に載ったときだけ。タイル⇔ネイティブの移動では呼ばない)。
  • 地図ごとの指定: web はプロバイダの props / config の polylineTilingOptions、Android は compose の PolylineTiling(options)、iOS は MapViewContent.polylineTilingOptions / PolylineTiling 要素。
  • 重なり順: ポリラインのタイルはポリラインの帯の最下段(サークルの上、ネイティブのポリラインとマーカーの下)。下から raster → GroundImage → polygon(+タイル) → circle → polyline(+タイル) → marker(+タイル)。

このリポジトリで変えたこと

  • PolylineTilingOptions(public、ポリゴンと同じ形と既定値)、PolylineTileSet / PolylineTiler(layerId mc-polyline-tiles)、PolylineController.tiler。PolygonController の tiler の経路をそのまま写し、タイルの線はタップ用に PolylineManager に残る(ネイティブの polyline は nil)。その場の変更は触れたタイルだけ描き直し、geodesic になった線などは onAdded なしでネイティブへ移る。
  • ポリゴンのタイル集合と描画を共通の内部部品 ShapeTileSet / ShapeTiler / ShapeTileRenderer に移した。
  • 開いた経路を画面上の線幅で、round cap/join、タイルの外まで描く。1 px 未満は点。
  • MapViewContent.polylineTilingOptions と PolylineTiling 要素(markerTilingOptions と同じ作り)。
  • OverlayStacking: ポリラインのタイルはポリラインの帯の最下段。
  • PolylineManager: 指の大きさ+線幅の半分であたる。各 entity の外接矩形と線幅を登録時に記録し、近い線の点だけ読む(5 万本で毎タップ 23 万点を読まない)。
  • 公開 API は追加のみ(+18 / -0)。試験 4 本を追加。

検証(iOS、追従後の 4ea1d59)

  • サンプルアプリ(Release、iPad)のビルド通過。develop の先頭へ進んだ 9 モジュール(template・geojson・heatmap・icons 系・kml・clustering)も、このブランチの core でビルドできます。
  • 単体テスト: core 457 件すべて通過。mapbox 10・maplibre 25・maptiler 12・openmobilemaps 16 通過。arcgis 24 件中 1 件・tomtom 9 件中 1 件が失敗しますが、どちらも base の時点から同じ失敗です。googlemaps はテストターゲットがビルドできません(GoogleMaps が iOS 17 を要求、既存)。here / longdo / mapkit / mappls はスキームにテストがありません。
  • 公開 API(scripts/api-surface.sh check): core と googlemaps 以外の 10 プロバイダ ok。core は +18 / -0(PolylineTiling・MapViewContent.polylineTilingOptions・PolylineTilingOptions ほか)、プロバイダは変化なし。
  • iPad 実機(Release、ボストンの道路、z16.5、重なり確認 ON):
    • MapLibre: 全 54,645 本の onAdded まで 1,090 ms、footprint 221 MB。Google: 921 ms、394 MB。
    • 重なり順: どちらもポリゴンのタイル → サークル → 道路のタイル → ネイティブの geodesic 線 → マーカーで正しい。
    • タップ(XCUITest): MapLibre・Google ともに InfoBubble(種別・長さ・頂点数)が出て passed。

挙動の変わる所

  • タップの判定に線幅の半分を足しました(3 プラットフォームの core の PolylineManager.find、タイルでもネイティブでも同じ)。許容距離 = 既存の指の大きさ(tapTolerance)+ 線幅 / 2。太い線は縁から指の大きさ以内であたります。複数あたれば最も近い線。外接矩形で先に候補を絞るので、5 万本でも毎タップ全点をなめません。返す位置(線上の最近点)は今までどおりです。
  • iOS TomTom: 合成スタイルで、SDK のタイル層(ポリゴン・ポリライン・マーカーのタイル)をスタイルの最上段に置きます。TomTom のスタイルは最初の symbol レイヤーより後ろに道路があり、「最初のラベルの前」では道路のタイルが覆われていたためです。そのためポリゴンのタイルも TomTom の道路・ラベルの上に来ます。annotation(ネイティブのサークル・線・マーカー)はこれまでどおりスタイル全体の上です。
  • web Google: overlayMapTypes の中でマーカーのタイルを最上位にしました(ポリゴン < ポリライン < マーカー)。3D 地図ではタイル化せず、すべてネイティブで描きます。
  • web MapLibre 系(maplibre / mapbox / maptiler / mappls / tomtom / longdo): GeoJSON で描くネイティブのポリラインを zIndex 順に並べるようにしました(これまでは渡した順)。タイルとネイティブで重なり方がそろいます。
  • iOS MapLibre / MapTiler / Mappls: raster レンダラが SDK タイル層の重なりのキーを id から取るようにしました(OverlayStacking.rasterKey(styleLayerId:))。追加の順に関係なく、ポリラインのタイルがネイティブのポリラインの下に入ります。

SDK の制約で重なり順を守れないもの

  • web Google(2D): overlayMapTypes は図形・GroundOverlay より必ず下に描かれるので、サークルとネイティブのポリゴンが道路のタイルの上に出ます(ポリゴンのタイル < 道路のタイル < マーカーは守れています)。
  • web Cesium: imagery レイヤーは ground primitive より必ず下。アプリのラスターより上に置くところまで。
  • Android HERE / ArcGIS / TomTom: ポリラインのタイルが SDK のオーバーレイ層(HERE は map item、ArcGIS は GraphicsOverlay)より下になるので、ネイティブのポリゴン・サークルがタイルの上に来ます。ポリゴンのタイルより上、マーカー(とそのタイル)より下は守れています。
  • iOS TomTom: annotation がスタイル全体の上に描かれるので、サークルがポリラインのタイルの上に来ます。ポリゴンのタイルも道路の上(上記)。
  • iOS Longdo / HERE / ArcGIS: z16 の画像を目で見た範囲では、サークルが道路のタイルの上に見えます(画素では測っていない)。iOS OMM: ポリゴンのタイルがほとんど見えません(要調査)。

確認できていないもの

  • Android Google のネイティブ比較: 54,645 本をネイティブで描かせると、main スレッドが OutOfMemoryError で落ちます(GoogleMap.addPolyline → PolylineOptions.writeToParcel、Java ヒープが上限 512 MB に到達)。1 本ずつ Parcel に詰めて GMS に渡すためで、タイル化ありなら落ちません。このため Google のタイル化あり/なしの時間は並べられていません。
  • Android の追従後の実機確認: develop を取り込んだ後の APK は、タブレットが adb に見えず実機で確かめていません(単体テストと apiCheck は通過)。追従前の build では MapLibre / Google で確認済みです。
  • web MapKit: トークンが 401 で地図が出ず、描画と重なり順は確かめていません(タップ判定は 43/43)。
  • web ArcGIS の初回タップ: カメラが一度動くまで当たりません(地図を一度動かすと 43/43)。
  • web Mappls: 右端でタップの位置がずれます(36/43)。
  • iOS の Mac 側照合のずれ: タップ試験の Mac 側の照合(初期カメラを仮定して最寄りの道路を計算)が、Google 16/30・TomTom 18/30・ArcGIS 13/30・ArcGIS2D 10/30・MapKit 11/30 しか合いません。アプリが返した最近点はどれも実在の道路の線から 0.05 pt 以内なので、判定の誤りではなく、Mac 側が仮定するカメラ(ズームの定義・safe area・2D の傾き補正)が SDK と合っていないと見ていますが、確かめてはいません。
  • 既存の失敗(このブランチ由来ではない): Android OMM の OpenMobileMapsDriverConformanceTest 1 件(develop の Log.isLoggable がモックされていない)、iOS ArcGIS・TomTom の単体テスト各 1 件、iOS Google のテストターゲットのビルド(GoogleMaps が iOS 17 を要求)。

base について

ポリラインの差分だけをレビューできるように、base は feat/overlay-on-added(feat/polygon-tiling + onAdded + ボストンのサンプル。そのリポジトリに無い場合は develop)にしています。feat/polygon-tiling は develop にマージ済みなので、feat/overlay-on-added が develop に入ったら、この PR の base を develop に付け替えてください。
追従は rebase せず merge commit で行いました(origin/feat/polygon-tiling → feat/overlay-on-added → feat/polyline-tiling)。

マージの順番

各リポジトリの feat/overlay-on-added →(base を develop に付け替えて)ios-sdk-core → 各プロバイダ → 親。プロバイダは ios-sdk-core の PolylineTiler / 重なり順を使うので core が先です。マージはレビューのうえで判断してください(この PR はまだマージしていません)。

親の PR: MapConductor/ios-sdk#18

MarkerState, CircleState, PolylineState, PolygonState, GroundImageState and
RasterLayerState get an optional onAdded, called with the state each time the
overlay goes from not being on the map to being on it: after the renderer's
onAdd returned for a native overlay, after the tile layer's URL template was
handed to the map for a tiled one (the tile images may still be loading).
It is not called for in-place changes, for a move between native drawing and
tiles, on clear or when the map goes away, and is called again after a remove
and a later add. Always on the main actor. Like onClick it is not part of the
id, the fingerprint, == or the hash, and replacing it redraws nothing.

The record of what is on the map lives in OverlayAddedTracker, one per core
controller, apart from the entity managers: providers clear those on a style
reload and re-create everything, which is not the app adding anything.
PolygonController admits tiled polygons after PolygonTiler.route, which
returns once the provider's raster upsert has. MarkerIngestionEngine gets an
SPI overload that takes the tracker, notifies the natively drawn markers and
returns the newly tiled ones for the provider to admit after its tile layer.

The Boston sample hid its loading overlay two frames after handing the list
over, then showed an empty map for about 4.7 s on an iPad while the SDK
unioned holes and tiled the parcels; this gives it something to wait for.
… on the map

Registering 100,000 tiled entities for taps (each computes its fingerprint)
takes about a second after PolygonTiler.route returns. On an iPad the tiles
were already showing under the loading overlay while onAdded waited for
that bookkeeping.
…ge makes it untileable

Whether a polygon is tiled was decided only on add. Setting geodesic on a
tiled polygon in place, or giving it points that span half the world or fewer
than three, kept it in the tiles, drawn with straight edges. update() now
checks canTile: a polygon that fails it leaves the tiles (its slot in the
renderer is emptied, so only the tiles it was in are drawn again) and is
handed to the renderer. It stays on the map, so this is not an add. The
reverse is left alone: a native polygon that could now be tiled already looks
right. Same as js-sdk-core.
# Conflicts:
#	Tests/MapConductorCoreTests/PolygonTilingInPlaceTests.swift
… lines by their box

The tolerance is the finger (tapTolerance) plus half the line's width, both
pt x screen scale as before, so a wide road is hit at its edge. Each entity
records its vertex box and width when registered; a tap first checks those
flat boxes and reads the points of nearby lines only (50,000 lines no longer
read 230,000 points per tap). The result is unchanged: the nearest line, at
the closest point on it.
PolylineTilingOptions (public, same shape and defaults as PolygonTilingOptions),
PolylineTileSet / PolylineTiler (layerId "mc-polyline-tiles") and
PolylineController.tiler, following PolygonController's tiler path: tiled lines
stay in PolylineManager for taps with a nil native polyline, an in-place change
redraws only the tiles it touches, and a line that becomes geodesic (or under
2 points, or half the world wide) moves to native drawing without onAdded.

The polygon tile set and renderer now sit on shared internals: ShapeTileSet
(route, URL version, 16 ms coalescing, removal slots, teardown), ShapeTiler
(routing) and ShapeTileRenderer (grid index, per-zoom simplification, tile
cache, dropTilesIn, PNG). An open path is snapped, deduplicated and thinned
with both ends kept; it is stroked with round caps and joins at its on-screen
width, overhanging the tile, and drawn as a dot when it collapses to a point.

MapViewContent.polylineTilingOptions and the PolylineTiling element set it per
map (tracked like markerTilingOptions). OverlayStacking puts the polyline tiles
at the bottom of the polyline band: over circles, under native polylines and
markers. The public API grows by additions only.
@wf9a5m75
wf9a5m75 changed the base branch from feat/overlay-on-added to develop November 10, 2026 01:55
@wf9a5m75

Copy link
Copy Markdown
Contributor Author

向け先を feat/overlay-on-added から develop に変えました。このため、この PR にはボストンのサンプル(feat/overlay-on-added:onAdded の数え方、MCPG v2 のデータ同梱など)の commit も含まれます。

@wf9a5m75
wf9a5m75 merged commit 1aba138 into develop Nov 10, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant