空間データの読み取りと書き込み

  • [アーティクル]

次の表は、空間 IO モジュールを使用した読み取り操作と書き込み操作でサポートされている空間ファイル形式を示しています。

データ形式 Read Write
GeoJSON ✓ ✓
GeoRSS ✓ ✓
GML ✓ ✓
GPX ✓ ✓
KML ✓ ✓
KMZ ✓ ✓
空間 CSV ✓ ✓
Well-Known Text ✓ ✓

以降のセクションでは、空間 IO モジュールを使用して、空間データの読み取りと書き込みを行うためのさまざまなツールの概要を説明します。

空間データの読み取り

atlas.io.read 関数は、空間データを使用して、KML、GPX、GeoRSS、GeoJSON、CSV ファイルなどの一般的な空間データ形式を読み取るために使用される主要な関数です。 この関数は、これらの形式の圧縮バージョン (ZIP ファイルや KMZ ファイル) も読み取ることができます。 KMZ ファイル形式は、画像などのアセットも含むことができる、KML の圧縮されたバージョンです。 また、read 関数は、ファイルを指す URL をこれらのいずれの形式でも受け取ることができます。 URL は CORS が有効になっているエンドポイントでホストされている必要があります。そうでない場合は、読み取りオプションでプロキシ サービスを提供する必要があります。 プロキシ サービスは、CORS が有効になっていないドメイン上のリソースを読み込むために使用されます。 read 関数は、マップに画像アイコンを追加する Promise を返し、データを非同期的に処理して UI スレッドへの影響を最小限に抑えます。

圧縮されたファイル (ZIP または KMZ) は、読み取り時に解凍されると、最初の有効なファイルを検索します。 たとえば、doc.kml やその他の有効な拡張子 (.kml、.xml、geojson、.json、.csv、.tsv、.txt など) を持つファイルです。 次に、KML および GeoRSS ファイルで参照されている画像は、確実にアクセス可能にするためにプリロードされます。 アクセスできない画像データは、代替となるフォールバック画像を読み込むか、スタイルから削除される可能性があります。 KMZ ファイルから抽出された画像は、データ URI に変換されます。

read 関数の結果は SpatialDataSet オブジェクトです。 このオブジェクトは、GeoJSON FeatureCollection クラスを拡張します。 これは、そのフィーチャーをマップにレンダリングするために、そのままで DataSource に簡単に渡されます。 SpatialDataSet は、次の表に示すように、フィーチャー情報を格納するだけでなく、KML グラウンド オーバーレイ、処理メトリック、およびその他の詳細を含む可能性もあります。

プロパティ名 種類​​ 説明
bbox BoundingBox データ セット内のすべてのデータの境界ボックス。
features Feature[] データ セット内の GeoJSON フィーチャー。
groundOverlays (atlas.layer.ImageLayer | atlas.layers.OgcMapLayer)[] KML GroundOverlays の配列。
icons Record<string, string> アイコン URL のセット。 キー = アイコン名、値 = URL。
properties any 空間データ セットのドキュメント レベルで提供されるプロパティ情報。
stats SpatialDataSetStats 空間データ セットのコンテンツと処理時間に関する統計情報。
type 'FeatureCollection' 読み取り専用の GeoJSON 型の値。

空間データの読み取りの例

空間データの読み込みサンプルでは、空間データ セットを読み取り、SimpleDataLayer クラスを使用してマップ上にそれをレンダリングする方法が示されています。 このコードでは、URL で指し示される GPX ファイルが使用されます。 このサンプルのソース コードについては、空間データの読み込みのソース コードを参照してください。

A screenshot that shows the snap grid on map.A screenshot that shows a detailed description of the snap grid on map sample.

次のコード デモでは、KML (KMZ) を読み取って、マップに読み込む方法を示します。 KML には、グラウンド オーバーレイを ImageLyaer または OgcMapLayer の形式で含めることができます。 これらのオーバーレイは、フィーチャーとは別にマップに追加する必要があります。 さらに、データ セットにカスタム アイコンが含まれている場合は、それらのアイコンをマップ リソースに読み込んでから、フィーチャーを読み込む必要があります。

マップへの KML の読み込みサンプルでは、KML または KMZ ファイルをマップに読み込む方法が示されています。 このサンプルのソース コードについては、マップへの KML の読み込みのソース コードを参照してください。

A screenshot that shows a map with a KML ground overlay.

必要に応じて、CORS が有効になっていないクロス ドメイン アセットにアクセスするためのプロキシ サービスを提供できます。 read 関数は、最初に CORS を使用して別のドメイン上のファイルにアクセスしようとします。 これは、別のドメイン上のいずれかのリソースへの CORS を使用したアクセスに最初に失敗すると、プロキシ サービスが提供されている場合に限り、追加のファイルを要求します。 read 関数は、提供されたプロキシ URL の末尾にファイル URL を追加します。 次のコード スニペットは、read 関数にプロキシ サービスを渡す方法を示しています。

//Read a file from a URL or pass in a raw data as a string.
atlas.io.read('https://nonCorsDomain.example.com/mySuperCoolData.xml', {
    //Provide a proxy service
    proxyService: window.location.origin + '/YourCorsEnabledProxyService.ashx?url='
}).then(async r => {
    if (r) {
        // Some code goes here . . .
    }
});

次のコード スニペットは、区切りファイルを読み取り、それをマップにレンダリングする方法を示しています。 このケースでは、コードで空間データ列を含む CSV ファイルが使用されています。 Azure Maps 空間 IO モジュールへの参照を追加する必要があります。


<!-- Add reference to the Azure Maps Spatial IO module. -->
<script src="https://atlas.microsoft.com/sdk/javascript/spatial/0/atlas-spatial.min.js"></script>

<script type="text/javascript">
var map, datasource, layer;

//a URL pointing to the CSV file
var delimitedFileUrl = "https://s3-us-west-2.amazonaws.com/s.cdpn.io/1717245/earthquakes_gt7_alltime.csv";

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

    //Add authentication details for connecting to Azure Maps.
    authOptions: {
      // Get an Azure Maps key at https://azuremaps.com/.
      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.
    datasource = new atlas.source.DataSource();
    map.sources.add(datasource);

    //Add a simple data layer for rendering the data.
    layer = new atlas.layer.SimpleDataLayer(datasource);
    map.layers.add(layer);

    //Read a CSV file from a URL or pass in a raw string.
    atlas.io.read(delimitedFileUrl).then(r => {
      if (r) {
      //Add the feature data to the data source.
      datasource.add(r);

      //If bounding box information is known for data, set the map view to it.
      if (r.bbox) {
        map.setCamera({
        bounds: r.bbox,
        padding: 50
        });
      }
      }
    });
  });
}
</script>

A screenshot that shows a map created from a CSV file.

空間データの書き込み

空間 IO モジュールには、主に 2 つの write 関数があります。 atlas.io.write 関数が文字列を生成するのに対し、atlas.io.writeCompressed 関数は圧縮された ZIP ファイルを生成します。 圧縮された ZIP ファイルには、空間データを含むテキストベースのファイルが含まれます。 これらの関数はどちらも、データをファイルに追加する Promise を返します。 また、これらはどちらも、SpatialDataSet、DataSource、ImageLayer、OgcMapLayer、フィーチャー コレクション、フィーチャー、ジオメトリのうちいずれか、またはこれらのデータ型の任意の組み合わせの配列を書き込むことができます。 いずれかの関数を使用して書き込むときに、必要なファイル形式を指定できます。 ファイル形式が指定されていない場合、データは KML として書き込まれます。

空間データ書き込みオプション サンプルは、atlas.io.write 関数で使用できる書き込みオプションの大部分を示すツールです。 このサンプルのソース コードについては、空間データ書き込みオプションのソース コードを参照してください。

A screenshot that shows The Spatial data write options sample that demonstrates most of the write options used with the atlas.io.write function.

空間データの書き込みの例

マップへの空間ファイルのドラッグ アンド ドロップ サンプルを使用すると、1 つ以上の KML、KMZ、GeoRSS、GPX、GML、GeoJSON、CSV ファイルをマップにドラッグ アンド ドロップできます。 このサンプルのソース コードについては、マップへの空間ファイルのドラッグ アンド ドロップのソース コードを参照してください。

A screenshot that shows a map with a panel to the left of the map that enables you to drag and drop one or more KML, KMZ, GeoRSS, GPX, GML, GeoJSON or CSV files onto the map.

必要に応じて、CORS が有効になっていないクロス ドメイン アセットにアクセスするためのプロキシ サービスを提供できます。 次のコード スニペットは、プロキシ サービスを組み込むことができることを示しています。

atlas.io.read(data, {
    //Provide a proxy service
    proxyService: window.location.origin + '/YourCorsEnabledProxyService.ashx?url='
}).then(
    //Success
    function(r) {
        //some code goes here ...
    }
);

Well-Known Text (WKT) の読み取りと書き込み

Well-Known Text (WKT) は、空間ジオメトリをテキストとして表現するための Open Geospatial Consortium (OGC) 標準です。 多くの地理空間システムでは、PostGIS プラグインを使用した Azure SQL や Azure PostgreSQL などの WKT がサポートされています。 ほとんどの OGC 標準と同様に、座標は "x y" 規則に合わせて "経度 緯度" として書式設定されます。 例として、WKT 形式を使用すると、経度 -110 と緯度 45 のポイントは、POINT(-110 45) として書き込むことができます。

Well Known Text は、atlas.io.ogc.WKT.read 関数を使用して読み取ることができ、atlas.io.ogc.WKT.write 関数を使用して書き込むことができます。

Well-Known Text (WKT) の読み取りと書き込みの例

Well Known Text 読み取りサンプルでは、Well Known Text 文字列 POINT(-122.34009 47.60995) を読み取り、それをバブル レイヤーを使用してマップ上にレンダリングする方法が示されています。 このサンプルのソース コードについては、Well Known Text の読み取りのソース コードを参照してください。

A screenshot that shows how to read Well Known Text (WKT) as GeoJSON and render it on a map using a bubble layer.

Well Known Text 読み書きサンプルでは、Well Known Text (WKT) 文字列を GeoJSON として読み書きする方法が示されています。 このサンプルのソース コードについては、Well Known Text の読み取りと書き込みのソース コードを参照してください。

A screenshot showing the sample that demonstrates how to read and write Well Known Text (WKT) strings as GeoJSON.

GML の読み取りと書き込み

GML は、他の XML 仕様の拡張としてよく使用される、空間 XML ファイルの仕様です。 GeoJSON データは、atlas.io.core.GmlWriter.write 関数を使用して、GML タグを持つ XML として書き込むことができます。 GML を含む XML は、atlas.io.core.GmlReader.read 関数を使用して読み取ることができます。 read 関数には、次の 2 つのオプションがあります。

  • isAxisOrderLonLat オプション - 座標軸の順序 ("緯度、経度" または "経度、緯度") は、データ セット間で異なる場合があり、常に明確に定義されているわけではありません。 既定では、GML リーダーは座標データを "緯度、経度" として読み取りますが、このオプションを true に設定すると、true は "経度、緯度" として読み取ります。
  • propertyTypes オプション - このオプションはキー値の参照テーブルで、ここではキーがデータ セット内のプロパティの名前です。 値は、解析時に値をキャストするオブジェクトの種類です。 サポートされる型の値は string、number、boolean、date です。 プロパティが参照テーブルにない場合、または型が定義されていない場合、プロパティは文字列として解析されます。

入力データが XML であるが、データが他のサポートされる空間 XML 形式の 1 つではないことが検出されると、atlas.io.read 関数が atlas.io.core.GmlReader.read 関数の既定になります。

GmlReader は、次のいずれかの SRID を持つ座標を解析します。

  • EPSG:4326 (推奨)
  • EPSG:4269、EPSG:4283、EPSG:4258、EPSG:4308、EPSG:4230、EPSG:4272、EPSG:4271、EPSG:4267、EPSG:4608、EPSG:4674 (場合によっては、わずかな許容誤差があります)
  • EPSG:3857、EPSG:102100、EPSG:3785、EPSG:900913、EPSG:102113、EPSG:41001、EPSG:54004

その他のリソース

この記事で使われているクラスとメソッドの詳細については、次を参照してください。

atlas.io 静的関数

SpatialDataSet

SpatialDataSetStats

GmlReader

GmlWriter

atlas.io.ogc.WKT 関数

WFS サービスへの接続

コア操作の活用

サポートされるデータ形式の詳細

次のステップ

マップに追加できる他のコード サンプルについては、次の記事をご覧ください。

OGC マップ レイヤーの追加