Skip to content

Files

Latest commit

90076f8 · Jan 14, 2022

History

History
254 lines (178 loc) · 10.5 KB

how-to-use-spatial-io-module.md

File metadata and controls

254 lines (178 loc) · 10.5 KB
title description author ms.author ms.date ms.topic ms.service services ms.custom
How to use the Azure Maps spatial IO module | Microsoft Azure Maps
Learn how to use the Spatial IO module provided by the Azure Maps Web SDK. This module provides robust features to make it easy for developers to integrate spatial data with the Azure Maps web sdk.
stevemunk
v-munksteve
02/28/2020
how-to
azure-maps
azure-maps
devx-track-js

How to use the Azure Maps Spatial IO module

The Azure Maps Web SDK provides the Spatial IO module, which integrates spatial data with the Azure Maps web SDK using JavaScript or TypeScript. The robust features in this module allow developers to:

In this guide, we'll learn how to integrate and use the Spatial IO module in a web application.

This video provides an overview of Spatial IO module in the Azure Maps Web SDK.


[!VIDEO https://docs.microsoft.com/Shows/Internet-of-Things-Show/Easily-integrate-spatial-data-into-the-Azure-Maps/player?format=ny]

Warning

Only use data and services that are from a source you trust, especially if referencing it from another domain. The spatial IO module does take steps to minimize risk, however the safest approach is too not allow any danagerous data into your application to begin with.

Prerequisites

Before you can use the Spatial IO module, you'll need to make an Azure Maps account and get the primary subscription key for your account.

Installing the Spatial IO module

You can load the Azure Maps spatial IO module using one of the two options:

  • The globally hosted Azure CDN for the Azure Maps spatial IO module. For this option, you add a reference to the JavaScript in the <head> element of the HTML file.

    <script src="https://atlas.microsoft.com/sdk/javascript/spatial/0/atlas-spatial.js"></script>
  • The source code for azure-maps-spatial-io can be loaded locally, and then hosted with your app. This package also includes TypeScript definitions. For this option, use the following command to install the package:

    npm install azure-maps-spatial-io

    Then, add a reference to the JavaScript in the <head> element of the HTML document:

    <script src="node_modules/azure-maps-spatial-io/dist/atlas-spatial.min.js"></script>

Using the Spatial IO module

  1. Create a new HTML file.

  2. Load the Azure Maps Web SDK and initialize the map control. See the Azure Maps map control guide for the details. Once you're done with this step, your HTML file should look like this:

    <!DOCTYPE html>
    <html>
    
    <head>
        <title></title>
    
        <meta charset="utf-8">
    
        <!-- Ensures that IE and Edge uses the latest version and doesn't emulate an older version -->
        <meta http-equiv="x-ua-compatible" content="IE=Edge">
    
        <!-- Ensures the web page looks good on all screen sizes. -->
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    
        <!-- Add references to the Azure Maps Map control JavaScript and CSS files. -->
        <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.css" type="text/css" />
        <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.js"></script>
    
        <script type='text/javascript'>
    
            var map;
    
            function GetMap() {
                //Initialize a map instance.
                map = new atlas.Map('myMap', {
                    view: 'Auto',
    
                    //Add your Azure Maps subscription key to the map SDK. Get an Azure Maps key at https://azure.com/maps
                    authOptions: {
                        authType: 'subscriptionKey',
                        subscriptionKey: '<Your Azure Maps Key>'
                    }
                });
    
                //Wait until the map resources are ready.
                map.events.add('ready', function() {
    
                    // Write your code here to make sure it runs once the map resources are ready
    
                });
            }
        </script>
    </head>
    
    <body onload="GetMap()">
        <div id="myMap"></div>
    </body>
    
    </html>
  3. Load the Azure Maps spatial IO module. For this exercise, use the CDN for the Azure Maps spatial IO module. Add the reference below to the <head> element of your HTML file:

    <script src="https://atlas.microsoft.com/sdk/javascript/spatial/0/atlas-spatial.js"></script>
  4. Initialize a datasource, and add the data source to the map. Initialize a layer, and add the data source to the map layer. Then, render both the data source and the layer. Before you scroll down to see the full code in the next step, think about the best places to put the data source and layer code snippets. Recall that, before we programmatically manipulate the map, we should wait until the map resource are ready.

    var datasource, layer;

    and

    //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);
  5. Putting it all together, your HTML code should look like the following code. This sample demonstrates how to read an XML file from a URL. Then, load and display the file's feature data on the map.

    <!DOCTYPE html>
    <html>
    
    <head>
        <title>Spatial IO Module Example</title>
    
        <meta charset="utf-8">
    
        <!-- Ensures that IE and Edge uses the latest version and doesn't emulate an older version -->
        <meta http-equiv="x-ua-compatible" content="IE=Edge">
    
        <!-- Ensures the web page looks good on all screen sizes. -->
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    
        <!-- Add references to the Azure Maps Map control JavaScript and CSS files. -->
        <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.css" type="text/css" />
        <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.js"></script>
    
        <!-- Add reference to the Azure Maps Spatial IO module. -->
        <script src="https://atlas.microsoft.com/sdk/javascript/spatial/0/atlas-spatial.js"></script>
    
        <script type='text/javascript'>
            var map, datasource, layer;
    
            function GetMap() {
                //Initialize a map instance.
                map = new atlas.Map('myMap', {
                    view: 'Auto',
    
                    //Add your Azure Maps subscription key to the map SDK. Get an Azure Maps key at https://azure.com/maps
                    authOptions: {
                        authType: 'subscriptionKey',
                        subscriptionKey: '<Your Azure Maps 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 an XML file from a URL or pass in a raw XML string.
                    atlas.io.read('superCoolKmlFile.xml').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>
    </head>
    
    <body onload="GetMap()">
        <div id="myMap"></div>
    </body>
    
    </html>
  6. Remember to replace <Your Azure Maps Key> with your primary key. Open your HTML file, and you'll see results similar to the following image:

    Spatial Data Example

Next steps

The feature we demonstrated here is only one of the many features available in the Spatial IO module. Read the guides below to learn how to use other functionalities in the Spatial IO module:

[!div class="nextstepaction"] Add a simple data layer

[!div class="nextstepaction"] Read and write spatial data

[!div class="nextstepaction"] Add an OGC map layer

[!div class="nextstepaction"] Connect to a WFS service

[!div class="nextstepaction"] Leverage core operations

[!div class="nextstepaction"] Supported data format details

Refer to the Azure Maps Spatial IO documentation:

[!div class="nextstepaction"] Azure Maps Spatial IO package