マップにシンボルレイヤーを追加する

[アーティクル]
06/28/2023

データソースにシンボルを接続し、それを使用して特定のポイントにアイコンやテキストをレンダリングします。

シンボルレイヤーは WebGL を使用してレンダリングされます。シンボルレイヤーを使用して、マップ上の多数のポイントをレンダリングします。 HTML マーカーに比べて、シンボルレイヤーでは、多数のポイントデータが優れたパフォーマンスでマップ上にレンダリングされます。ただし、シンボルレイヤーはスタイル設定用の従来の CSS および HTML 要素をサポートしていません。

ヒント

シンボルレイヤーでは、既定ではデータソース内のすべてのジオメトリの座標がレンダリングされます。ポイントジオメトリフィーチャーのみがレンダリングされるようにレイヤーを制限するには、レイヤーの filter プロパティを ['==', ['geometry-type'], 'Point'] に設定します。MultiPoint フィーチャーも含める場合は、['any', ['==', ['geometry-type'], 'Point'], ['==', ['geometry-type'], 'MultiPoint']] に設定します。

シンボルレイヤーで使用されるカスタムイメージは、マップイメージスプライトマネージャーによって読み込まれます。次のイメージ形式がサポートされます。

JPEG
PNG
SVG
BMP
GIF (アニメーションなし)

シンボルレイヤーを追加する

マップにシンボルレイヤーを追加する前に、いくつかの手順を行う必要があります。まず、データソースを作成してマップに追加します。シンボルレイヤーを追加します。次に、データソースからデータを取得するために、データソースをシンボルレイヤーに渡します。最後に、データをデータソースに追加して、レンダリングするものが存在するようにします。

次のコードは、マップが読み込まれた後に、そこに追加する必要がある内容を示しています。このサンプルでは、シンボルレイヤーを使用してマップ上に 1 つのポイントがレンダリングされます。

//Create a data source and add it to the map.
var dataSource = new atlas.source.DataSource();
map.sources.add(dataSource);

//Create a symbol layer to render icons and/or text at points on the map.
var layer = new atlas.layer.SymbolLayer(dataSource);

//Add the layer to the map.
map.layers.add(layer);

//Create a point and add it to the data source.
dataSource.add(new atlas.data.Point([0, 0]));

マップに追加できるポイントデータには、次の 4 種類があります。

GeoJSON Point ジオメトリ - このオブジェクトには、ポイントの座標だけが含まれ、それ以外は含まれません。 atlas.data.Point ヘルパークラスを使用すると、これらのオブジェクトを簡単に作成できます。
GeoJSON MultiPoint ジオメトリ - このオブジェクトには、複数のポイントの座標が含まれ、それ以外は含まれません。 atlas.data.MultiPoint ヘルパークラスを使用すると、これらのオブジェクトを簡単に作成できます。
GeoJSON 機能 - このオブジェクトは、すべての GeoJSON ジオメトリと、ジオメトリに関連するメタデータを含むプロパティのセットで構成されます。 atlas.data.Feature ヘルパークラスを使用すると、これらのオブジェクトを簡単に作成できます。
atlas.Shape クラスは GeoJSON 機能に似ています。どちらも、GeoJSON ジオメトリとそのジオメトリに関連するメタデータが含まれる一連のプロパティで構成されます。 GeoJSON オブジェクトがデータソースに追加されると、レイヤーで簡単にレンダリングできます。ただし、その GeoJSON オブジェクトの座標プロパティが更新された場合でも、データソースとマップは変更されません。これは、JSON オブジェクトには更新をトリガーするためのメカニズムがないためです。 Shape クラスには、含まれているデータを更新するための関数が用意されています。変更が行われると、データソースとマップに自動的に通知され、更新が実行されます。

次のコードサンプルは、GeoJSON Point ジオメトリを作成し、atlas.Shape クラスに渡すことで、更新を容易にしています。シンボルをレンダリングするのに、最初はマップの中心が使用されます。マップにクリックイベントが追加され、そのイベントが発生したときに、マウスの座標が setCoordinates 関数で使用されます。クリックイベント時にマウスの座標が記録されます。次に、setCoordinates によって、マップ上のシンボルの場所が更新されます。

function InitMap()
{
    var map = new atlas.Map('myMap', {
        center: [-122.33, 47.64],
        zoom: 13,
        view: "Auto",

        //Add authentication details for connecting to Azure Maps.
        authOptions: {
            authType: 'subscriptionKey',
            subscriptionKey: '{Your-Azure-Maps-Subscription-key}'
        }
    });

    //Wait until the map resources are ready.
    map.events.add('ready', function () {

      /*Create a data source and add it to the map*/
      var dataSource = new atlas.source.DataSource();
      map.sources.add(dataSource);
      var point = new atlas.Shape(new atlas.data.Point([-122.33, 47.64]));
      //Add the symbol to the data source.
      dataSource.add([point]);

      /* Gets co-ordinates of clicked location*/
      map.events.add('click', function(e){
        /* Update the position of the point feature to where the user clicked on the map. */
        point.setCoordinates(e.position);
      });

      //Create a symbol layer using the data source and add it to the map
      map.layers.add(new atlas.layer.SymbolLayer(dataSource, null));
    });
}

シンボルレイヤーを使用してピンを追加したマップを示すスクリーンショット。

ヒント

既定では、重なっているシンボルがシンボルレイヤーによって非表示になることで、シンボルのレンダリングが最適化されます。拡大すると、非表示のシンボルが表示されるようになります。この機能を無効にして、すべてのシンボルを常にレンダリングするには、iconOptions オプションの allowOverlap プロパティを true に設定します。

シンボルレイヤーにカスタムアイコンを追加する

シンボルレイヤーは WebGL を使用してレンダリングされます。このため、アイコンの画像などのすべてのリソースを WebGL コンテキストに読み込む必要があります。このサンプルでは、マップリソースにカスタムアイコンを追加する方法を示します。このアイコンを使用して、ポイントデータをカスタムシンボルでマップ上にレンダリングします。シンボルレイヤーの textField プロパティに式を指定する必要があります。ここでは、気温プロパティをレンダリングします。気温は数値であるため、文字列に変換する必要があります。加えて、そこに "°F" を追加したいと思います。 ['concat', ['to-string', ['get', 'temperature']], '°F'] という式を使えば、この連結を実行できます。

function InitMap()
{
    var map = new atlas.Map('myMap', {
        center: [-73.985708, 40.75773],
        zoom: 12,
        view: "Auto",

        //Add authentication details for connecting to Azure Maps.
        authOptions: {
            authType: 'subscriptionKey',
            subscriptionKey: '{Your-Azure-Maps-Subscription-key}'
        }
    });

    map.events.add('ready', function () {

      //Load the custom image icon into the map resources.
      map.imageSprite.add('my-custom-icon', 'https://s3-us-west-2.amazonaws.com/s.cdpn.io/1717245/showers.png').then(function () {

        //Create a data source and add it to the map.
        var datasource = new atlas.source.DataSource();
        map.sources.add(datasource);

        //Create a point feature and add it to the data source.
        datasource.add(new atlas.data.Feature(new atlas.data.Point([-73.985708, 40.75773]), {
          temperature: 64
        }));

        //Add a layer for rendering point data as symbols.
        map.layers.add(new atlas.layer.SymbolLayer(datasource, null, {
          iconOptions: {
            //Pass in the id of the custom icon that was loaded into the map resources.
            image: 'my-custom-icon',

            //Optionally scale the size of the icon.
            size: 0.5
          },
          textOptions: {
            //Convert the temperature property of each feature into a string and concatenate "°F".
            textField: ['concat', ['to-string', ['get', 'temperature']], '°F'],

            //Offset the text so that it appears on top of the icon.
            offset: [0, -2]
          }
        }));
      });
    });
}