README_ja.md

English / 日本語

Mapbox Collision Boxes

Mapboxマップ上の衝突ボックスを画面座標系で計算する、Mapbox GL JS (mapbox-gl)用のユーティリティライブラリです。

はじめる

事前準備

このライブラリはmapbox-glバージョン2.xおよび3.xと一緒に使用する想定です。

インストール方法

このレポジトリを依存関係に追加してください。

npm install https://github.com/codemonger-io/mapbox-collision-boxes#v0.2.0

使い方

以下のスニペットはクリックしたシンボルに画面上で隠されているFeatureを集めてくる例です。

import mapboxgl from 'mapbox-gl';
import { boxesIntersect, collectCollisionBoxesAndFeatures } from 'mapbox-collision-boxes';

const map = new mapboxgl.Map(
    // ... マップの初期化
);
// ... その他の設定
const layerId = 'cats-and-dogs'; // カスタムレイヤーを追加した想定
const map.on('click', layerId, async event => {
    const clickedFeatureId = event.features[0].id;
    const collisionBoxes = await collectCollisionBoxesAndFeatures(map, layerId);
    const clickedBox = collisionBoxes.find(box => box.feature.id === clickedFeatureId);
    const hiddenBoxes = collisionBoxes.filter(box => box !== clickedBox && boxesIntersect(box.box, clickedBox.box));
    const hiddenFeatures = hiddenBoxes.map(box => box.feature);
    // ... Featureの処理
});

exampleフォルダに完成したプロジェクトがあります。

動機

私はマップ上にmapbox-glのSymbol Layerを使ってカスタムシンボルを表示するアプリを開発しています。 mapbox-glは画面上でシンボルが被ると最初のものだけ表示し、他の重なるものは隠してしまいます。 私の知る限り、mapbox-glには画面上で特定のシンボルによって隠されているシンボルを取得するAPIはありません。 開発中のアプリでは非表示のものも含めてクリックされたポイントにあるすべてのシンボルをリストしたいので、これでは不都合です。 mapbox-glに衝突検出をスキップさせてすべてのシンボルを画面に表示させるオプションはありますが、重なるシンボルがたくさんある場合は画面がごちゃごちゃし過ぎてしまいます。

ということでMapboxマップ上で特定のシンボルと重なるシンボルを集めることのできるライブラリを開発することにしました。

より詳しくは私のブログ投稿をご覧ください。

APIドキュメント

api-docs/markdown/index.mdをご覧ください。

Tips

ビューポートオフセット

collectCollisionBoxesAndFeaturesが集める衝突ボックスは固定のオフセットを含んでいます。 xとyの両軸について実際の画面位置 + 100¹になっています。 オフセットは衝突ボックス同士の衝突判定には影響しないため、このライブラリでは不必要な計算を避けるためにそのままにしてあります。 衝突ボックスを実際の画面に投影したい場合は、xとy軸の値から100を引かなければなりません。

開発

依存関係の解決

npm ci

タイプチェック

npm run type-check

ライブラリをビルドする

npm run build

Footnotes

1. この定数はviewportPaddingとして https://github.com/mapbox/mapbox-gl-js/blob/e29e113ff5e1f4c073f84b8cbe546006d2fb604f/src/symbol/collision_index.js#L50 に定義されていますが、mapbox-glはエクスポートしていません。 ↩