Lesen und Schreiben von räumlichen Daten

Artikel
09/26/2024

Die folgende Tabelle listet die räumlichen Dateiformate auf, die für Lese- und Schreibvorgänge mit dem Spatial IO-Modul unterstützt werden.

Datenformat	Lesen	Schreiben
GeoJSON	✓	✓
GeoRSS	✓	✓
GML	✓	✓
GPX	✓	✓
GML	✓	✓
KMZ	✓	✓
Spatial CSV	✓	✓
Well-Known Text	✓	✓

In den folgenden Abschnitten werden die verschiedenen Tools zum Lesen und Schreiben räumlicher Daten mit dem Modul Spatial IO vorgestellt.

Lesen räumlicher Daten

Die Funktion atlas.io.read ist die Hauptfunktion zum Lesen gängiger Formate für räumliche Daten wie KML, GPX, GeoRSS, GeoJSON und CSV-Dateien mit räumlichen Daten. Diese Funktion kann auch komprimierte Versionen dieser Formate in Form einer ZIP- oder KMZ-Datei lesen. Das Dateiformat KMZ ist eine komprimierte Version von KML, die auch Objekte wie Bilder enthalten kann. Alternativ kann die Lesefunktion eine URL verwenden, die auf eine Datei in einem dieser Formate verweist. URLs müssen auf einem CORS-fähigen Endpunkt gehostet werden, oder in den Leseoptionen muss ein Proxydienst bereitgestellt werden. Der Proxydienst wird verwendet, um Ressourcen in Domänen zu laden, die nicht CORS-fähig sind. Die Lesefunktion gibt eine Zusage zum Hinzufügen der Bildsymbole zur Karte zurück und verarbeitet Daten asynchron, um die Auswirkungen auf den Benutzeroberflächenthread zu minimieren.

Nachdem eine komprimierte Datei (zip oder kmz) entpackt wurde, sucht das Programm nach der ersten gültigen Datei. Beispielsweise „doc.kml“ oder eine Datei mit einer anderen gültigen Erweiterung wie .kml, .xml, geojson, .json, .csv, .tsv oder .txt. Anschließend werden in KML- und GeoRSS-Dateien referenzierte Bilder vorab geladen, um den Zugriff darauf sicherzustellen. Nicht zugängliche Bilddaten können durch ein alternatives Fallback-Bild ersetzt oder aus den Stilen entfernt werden. Aus KMZ-Dateien extrahierte Bilder werden in Daten-URIs konvertiert.

Das Ergebnis der Lesefunktion ist ein SpatialDataSet-Objekt. Dieses Objekt erweitert die GeoJSON-Klasse FeatureCollection. Sie kann problemlos an eine DataSource weitergegeben werden, um ihre Features auf einer Karte zu rendern. SpatialDataSet enthält nicht nur Informationen zu den Features, sondern kann auch kml-Bodenüberlagerungen, Metriken zur Verarbeitung und andere Details enthalten, wie in der folgenden Tabelle beschrieben.

Eigenschaftenname	Type	BESCHREIBUNG
`bbox`	`BoundingBox`	Begrenzungsfeld aller Daten im Dataset.
`features`	`Feature[]`	GeoJSON-Features innerhalb des Datasets.
`groundOverlays`	`(atlas.layer.ImageLayer \| atlas.layers.OgcMapLayer)[]`	Ein Array von KML GroundOverlays.
`icons`	Datensatz<Zeichenfolge, Zeichenfolge>	Eine Gruppe von Symbol-URLs. Schlüssel = Symbolname, Wert = URL.
properties	any	Eigenschaftsinformationen, die auf Dokumentebene eines räumlichen Datasets bereitgestellt werden.
`stats`	`SpatialDataSetStats`	Statistik zu Inhalt und Verarbeitungszeit eines räumlichen Datasets.
`type`	`'FeatureCollection'`	Schreibgeschützter GeoJSON-Typwert.

Beispiele für das Lesen räumlicher Daten

Das Beispiel zum Laden von räumlichen Daten zeigt, wie ein räumliches Dataset gelesen und mit der Klasse SimpleDataLayer auf der Karte gerendert werden kann. Der Code verwendet eine GPX-Datei, auf die eine URL zeigt. Den Quellcode dieses Beispiels finden Sie unter Quellcode zum Laden von räumlichen Daten.

Die nächste Codedemo zeigt, wie KML- oder KMZ-Daten gelesen und in die Karte geladen werden können. KML kann Bodenüberlagerungen enthalten, die in der Form ImageLayer oder OgcMapLayer vorliegen. Diese Überlagerungen müssen der Karte getrennt von den Features hinzugefügt werden. Wenn das Dataset außerdem benutzerdefinierte Symbole enthält, müssen diese Symbole in die Kartenressourcen geladen werden, bevor die Features geladen werden.

Im Beispiel zum Laden von KML auf einer Karte wird gezeigt, wie KML- oder KMZ-Dateien in die Karte geladen werden. Den Quellcode dieses Beispiels finden Sie unter Quellcode zum Laden von KML in einer Karte.

Sie können optional einen Proxy-Dienst für den Zugriff auf domänenübergreifende Ressourcen anbieten, für die CORS nicht aktiviert ist. Die Lesefunktion versucht, zuerst mithilfe von CORS auf Dateien in einer anderen Domäne zuzugreifen. Wenn der Zugriff auf eine Ressource in einer anderen Domäne über CORS zum ersten Mal fehlschlägt, werden nur dann weitere Dateien angefordert, wenn ein Proxy-Dienst bereitgestellt wird. Die Lesefunktion fügt die URL der Datei an das Ende der bereitgestellten Proxy-URL an. Dieser Codeausschnitt zeigt, wie der Lesefunktion ein Proxydienst übergeben wird:

//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 . . .
    }
});

Der folgende Codeschnipsel zeigt, wie eine Datei mit Trennzeichen gelesen und auf der Karte gerendert werden kann. In diesem Fall verwendet der Code eine CSV-Datei mit Spalten mit räumlichen Daten. Sie müssen einen Verweis auf das Azure Maps Spatial IO-Modul hinzufügen.

<!-- 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>

Schreiben räumlicher Daten

Im Modul Spatial IO gibt es zwei wesentliche Schreibfunktionen. Die Funktion atlas.io.write generiert eine Zeichenfolge, während die Funktion atlas.io.writeCompressed eine komprimierte ZIP-Datei erzeugt. Die komprimierte ZIP-Datei enthält eine textbasierte Datei mit den räumlichen Daten. Beide Funktionen geben die Zusage zurück, die Daten der Datei hinzuzufügen. Und beide können beliebige der folgenden Daten schreiben: SpatialDataSet, DataSource, ImageLayer, OgcMapLayer, Featuresammlung, Feature, Geometrie oder ein Array mit einer beliebigen Kombination dieser Datentypen. Beim Schreiben mit einer der beiden Funktionen können Sie das gewünschte Dateiformat angeben. Wenn das Dateiformat nicht angegeben wird, werden die Daten im KML-Format geschrieben.

Das Beispiel für Schreiboptionen für räumliche Daten ist ein Tool, das die meisten Schreiboptionen veranschaulicht, die mit der Funktion atlas.io.write verwendet werden können. Den Quellcode dieses Beispiels finden Sie unter Quellcode für Schreiboptionen für räumliche Daten.

Beispiel für das Schreiben räumlicher Daten

Mit dem Beispiel zum Ziehen und Ablegen von Dateien mit räumlichen Daten auf der Karte können Sie eine oder mehrere KML-, KMZ-, GeoRSS-, GPX-, GML-, GeoJSON- oder CSV-Dateien auf die Karte ziehen und dort ablegen. Den Quellcode dieses Beispiels finden Sie unter Quellcode zum Ziehen und Ablegen von Dateien mit räumlichen Daten auf der Karten.

Sie können optional einen Proxy-Dienst für den Zugriff auf domänenübergreifende Ressourcen anbieten, für die CORS nicht aktiviert ist. In diesem Codeausschnitt wird gezeigt, wie Sie einen Proxydienst einbinden können:

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

Lesen und Schreiben von Well-Known Text (WKT)

Well-Known Text (WKT) ist ein OGC-Standard (Open Geospatial Consortium) zum Darstellen räumlicher Geometrien als Text. Viele räumliche Systeme unterstützen WKT, z. B. Azure SQL und Azure PostgreSQL, mithilfe des PostGIS-Plug-Ins. Wie die meisten OGC-Standards sind die Koordinaten als „Längengrad Breitengrad“ formatiert, um sie an die „x y“-Konvention anzupassen. Als Beispiel kann ein Punkt auf Längengrad -110 und Breitengrad 45 im WKT-Format als POINT(-110 45) geschrieben werden.

Das WKT-Format kann mit der atlas.io.ogc.WKT.read-Funktion gelesen und mit der atlas.io.ogc.WKT.write-Funktion geschrieben werden.

Beispiele zum Lesen und Schreiben von Well-Known Text (WKT)

Das Beispiel zum Lesen von Well Known Text zeigt, wie die WKT-Zeichenfolge POINT(-122.34009 47.60995) gelesen und mithilfe einer Blasenebene auf der Karte gerendert werden kann. Den Quellcode dieses Beispiels finden Sie unter Quellcode zum Lesen von Well Known Text.

Im Beispiel zum Lesen und Schreiben von Well Known Text wird veranschaulicht, wie WKT-Zeichenfolgen als GeoJSON gelesen und geschrieben werden. Den Quellcode dieses Beispiels finden Sie unter Quellcode zum Lesen und Schreiben von Well Known Text.

Lesen und Schreiben von GML

gml ist eine räumliche xml-Dateispezifikation, die oft als Erweiterung anderer xml-Spezifikationen verwendet wird. GeoJSON-Daten können mithilfe der Funktion atlas.io.core.GmlWriter.write im XML-Format mit GML-Tags geschrieben werden. Der XML-Code, der GML enthält, kann mit der atlas.io.core.GmlReader.read-Funktion gelesen werden. Die Lesefunktion bietet zwei Optionen:

Die Option isAxisOrderLonLat: Die Achsenreihenfolge der Koordinaten „Breitengrad, Längengrad“ oder „Längengrad, Breitengrad“ kann zwischen Datasets variieren und ist nicht immer eindeutig definiert. Standardmäßig liest der GML-Reader die Koordinatendaten als „Breitengrad, Längengrad“. Aber wenn Sie diese Option auf true festlegen, werden sie als „Längengrad, Breitengrad“ gelesen.
Die Option propertyTypes: Bei dieser Option handelt es sich um eine Nachschlagetabelle für Schlüsselwerte, wobei der Schlüssel der Name einer Eigenschaft im Dataset ist. Der Wert ist der Objekttyp, in den der Wert bei der Analyse umgewandelt werden soll. Die unterstützten Typwerte sind: string, number, boolean und date. Wenn sich eine Eigenschaft nicht in der Nachschlagetabelle befindet oder der Typ nicht definiert ist, wird die Eigenschaft als Zeichenfolge geparst.

Die Funktion atlas.io.read wird standardmäßig auf die Funktion atlas.io.core.GmlReader.read festgelegt, wenn festgestellt wird, dass die Eingabedaten das XML-Format haben, die Daten aber nicht eines der anderen unterstützten XML-Formate für räumliche Daten aufweisen.

GmlReader parst Koordinaten, die eine der folgenden SRIDs aufweisen:

EPSG:4326 (bevorzugt)
EPSG:4269, EPSG:4283, EPSG:4258, EPSG:4308, EPSG:4230, EPSG:4272, EPSG:4271, EPSG:4267, EPSG:4608, EPSG:4674 möglicherweise mit einer geringen Fehlertoleranz.
EPSG:3857, EPSG:102100, EPSG:3785, EPSG:900913, EPSG:102113, EPSG:41001, EPSG:54004