Leggere e scrivere dati spaziali

Nella tabella seguente sono elencati i formati di file spaziali supportati per le operazioni di lettura e scrittura con il modulo I/O spaziale.

Queste sezioni successive illustrano tutti i diversi strumenti per la lettura e la scrittura di dati spaziali usando il modulo I/O spaziale.

Leggere i dati spaziali

La funzione atlas.io.read è la funzione principale usata per leggere formati di dati spaziali comuni, ad esempio KML, GPX, GeoRSS, GeoJSON e file CSV con dati spaziali. Questa funzione può anche leggere le versioni compresse di questi formati, come file ZIP o un file KMZ. Il formato di file KMZ è una versione compressa di KML che può includere anche asset come immagini. In alternativa, la funzione read può accettare un URL che punta a un file in uno qualsiasi di questi formati. Gli URL devono essere ospitati in un endpoint abilitato per CORS oppure è necessario fornire un servizio proxy nelle opzioni di lettura. Il servizio proxy viene usato per caricare le risorse nei domini non abilitati per CORS. La funzione read restituisce una promessa di aggiungere le icone dell'immagine alla mappa ed elabora i dati in modo asincrono per ridurre al minimo l'impatto sul thread dell'interfaccia utente.

Quando si legge un file compresso, come zip o KMZ, una volta decompresso cerca il primo file valido. Ad esempio, doc.kml o un file con un'altra estensione valida, ad esempio: .kml, .xml, geojson, .json, .csv, .tsv o .txt. Le immagini a cui si fa riferimento nei file KML e GeoRSS vengono quindi precaricati per assicurarsi che siano accessibili. I dati delle immagini inaccessibili possono caricare un'immagine di fallback alternativa o rimuoverli dagli stili. Le immagini estratte dai file KMZ vengono convertite in URI di dati.

Il risultato della funzione read è un oggetto SpatialDataSet. Questo oggetto estende la classe FeatureCollection GeoJSON. Può essere facilmente passato a DataSource così come è per eseguire il rendering delle sue caratteristiche su una mappa. SpatialDataSet non solo contiene informazioni sulle funzionalità, ma può includere anche sovrapposizioni del terreno KML, metriche di elaborazione e altri dettagli, come descritto nella tabella seguente.

Esempi di lettura dei dati spaziali

L'esempio Caricare dati spaziali mostra come leggere un set di dati spaziali ed eseguirne il rendering sulla mappa usando la classe SimpleDataLayer. Il codice usa un file GPX a cui punta un URL. Per il codice sorgente di questo esempio, vedere Carica il codice sorgente dei dati spaziali.

La demo di codice successiva illustra come leggere e caricare KML o KMZ nella mappa. KML può contenere sovrapposizioni di terreno, che è sotto forma di ImageLayer o OgcMapLayer. Queste sovrimpressioni devono essere aggiunte sulla mappa separatamente dalle funzionalità. Inoltre, se il set di dati include icone personalizzate, tali icone devono essere caricate nelle risorse di mappe prima del caricamento delle funzionalità.

L'esempio Caricare KML sulla mappa mostra come caricare file KML o KMZ sulla mappa. Per il codice sorgente di questo esempio, vedere Caricare KML nel codice sorgente della mappa.

Facoltativamente, è possibile fornire un servizio proxy per l'accesso ad asset tra domini che non hanno CORS abilitato. La funzione read tenta prima di tutto di accedere ai file in un altro dominio usando CORS. La prima volta che non riesce ad accedere a qualsiasi risorsa in un altro dominio usando CORS, richiede solo più file se viene fornito un servizio proxy. La funzione read aggiunge l'URL del file alla fine dell'URL proxy fornito. Questo frammento di codice mostra come passare un servizio proxy alla funzione 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 . . .
    }
});

Il frammento di codice seguente mostra come leggere un file delimitato ed eseguirne il rendering sulla mappa. In questo caso, il codice usa un file CSV con colonne di dati spaziali. È necessario aggiungere un riferimento al modulo I/O spaziale di Mappe di Azure.

<!-- 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>
    var datasource, delimitedFileUrl = "Chicago_Police_Stations.csv";
    // Download CSV file (delimitedFileUrl) from:
    // https://github.com/Azure-Samples/AzureMapsCodeSamples/blob/main/Static/data/SpatialCSV/Chicago_Police_Stations.csv

    function GetMap() {

        //Instantiate a map object
        var map = new atlas.Map("myMap", {
            center: [-87.628899, 41.874693],
            zoom: 9,
            view: "Auto",
            // Replace <Your Azure Maps Subscription Key> with your Azure Maps subscription key. https://aka.ms/am-primaryKey
            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.
        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>

Scrivere dati spaziali

Nel modulo di I/O spaziale sono disponibili due funzioni di scrittura principali. La funzione atlas.io.write genera una stringa, mentre la funzione atlas.io.writeCompressed genera un file ZIP compresso. Il file ZIP compresso conterrà un file basato su testo con i dati spaziali in esso contenuti. Entrambe queste funzioni restituiscono una promessa per aggiungere i dati al file. Inoltre, entrambi possono scrivere uno dei dati seguenti: SpatialDataSet, DataSource, ImageLayer, OgcMapLayerraccolta di funzionalità, funzionalità, geometria o una matrice di qualsiasi combinazione di questi tipi di dati. Quando si scrivono usando entrambe le funzioni, è possibile specificare il formato di file desiderato. Se il formato di file non viene specificato, i dati vengono scritti come KML.

L'esempio Opzioni di scrittura dati spaziali è uno strumento che illustra la maggior parte delle opzioni di scrittura che possono essere usate con la funzione atlas.io.write. Per il codice sorgente di questo esempio, vedere Codice sorgente delle opzioni di scrittura dei dati spaziali.

Esempio di scrittura di dati spaziali

L'esempio Trascinare la selezione dei file spaziali sulla mappa consente di trascinare la selezione di uno o più file KML, KMZ, GeoRSS, GPX, GML, GeoJSON o CSV sulla mappa. Per il codice sorgente di questo esempio, vedere Trascinare la selezione di file spaziali nel codice sorgente della mappa.

Facoltativamente, è possibile fornire un servizio proxy per l'accesso ad asset tra domini che non hanno CORS abilitato. Questo frammento di codice mostra che è possibile incorporare un servizio proxy:

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

Lettura e scrittura di Well-Known Text (WKT)

Well-Known Text (WKT) è uno standard OGC (Open Geospatial Consortium) usato per rappresentare geometrie spaziali come testo. Molti sistemi geospaziali supportano WKT, ad esempio Azure SQL e Azure PostgreSQL usando il plug-in PostGIS. Analogamente alla maggior parte degli standard OGC, le coordinate vengono formattate come "latitudine longitudine" per allinearsi alla convenzione "x y". Ad esempio, un punto alla longitudine -110 e latitudine 45 può essere scritto come POINT(-110 45) usando il formato WKT.

Well-Known Text può essere letto usando la funzione atlas.io.ogc.WKT.read e scritto usando la funzione atlas.io.ogc.WKT.write.

Esempi di lettura e scrittura di Well-Known Text (WKT)

L'esempio Leggere Well-Known Text mostra come leggere la stringa di Well-Known Text POINT(-122.34009 47.60995) ed eseguirne il rendering sulla mappa usando un livello bolla. Per il codice sorgente di questo esempio, vedere Leggere il codice sorgente di Well-Known Text.

L'esempio Leggere e scrivere Well-Known Text illustra come leggere e scrivere stringhe WKT come GeoJSON. Per il codice sorgente di questo esempio, vedere Leggere e scrivere codice sorgente di Well-Known Text.

Leggere e scrivere GML

GML è una specifica del file XML spaziale spesso usata come estensione per altre specifiche XML. I dati GeoJSON possono essere scritti come XML con tag GML usando la funzione atlas.io.core.GmlWriter.write. Il codice XML che contiene GML può essere letto usando la funzione atlas.io.core.GmlReader.read. La funzione read include due opzioni:

• Opzione isAxisOrderLonLat: l'ordine delle coordinate "latitudine, longitudine" o "longitudine, latitudine" può variare tra set di dati e non è sempre ben definito. Per impostazione predefinita, il lettore GML legge i dati delle coordinate come "latitudine, longitudine", ma impostando questa opzione su true le legge come "longitudine, latitudine".
• Opzione propertyTypes: questa opzione è una tabella di ricerca del valore chiave in cui la chiave è il nome di una proprietà nel set di dati. Il valore è il tipo di oggetto per cui eseguire il cast del valore durante l'analisi. I valori supportati sono: string, number, boolean e date. Se una proprietà non è presente nella tabella di ricerca o il tipo non è definito, la proprietà viene analizzata come stringa.

Per impostazione predefinita, la funzione atlas.io.read diventa la funzione atlas.io.core.GmlReader.read quando rileva che i dati di input sono XML, ma i dati non sono in uno degli altri formati XML spaziali.

GmlReader analizza le coordinate con uno dei seguenti identificatori SRID:

• EPSG:4326 (preferito)
• EPSG:4269, EPSG:4283, EPSG:4258, EPSG:4308, EPSG:4230, EPSG:4272, EPSG:4271, EPSG:4267, EPSG:4608, EPSG:4674 verosimilmente con un piccolo margine di errore.
• EPSG:3857, EPSG:102100, EPSG:3785, EPSG:900913, EPSG:102113, EPSG:41001, EPSG:54004

Altre risorse

Per altre informazioni sulle classi e sui metodi usati in questo articolo, vedere:

funzioni statiche atlas.io

SpatialDataSet

SpatialDataSetStats

GmlReader

GmlWriter

funzioni atlas.io.ogc.WKT

Connettersi a un servizio WFS

Sfruttare le operazioni principali

Dettagli sul formato dati supportato

Passaggi successivi

Per altri esempi di codice da aggiungere alle mappe, vedere gli articoli seguenti:

Aggiungere un livello mappa OGC