Odczytywanie i zapisywanie danych przestrzennych

Artykuł
11/08/2023

W poniższej tabeli wymieniono formaty plików przestrzennych, które są obsługiwane w przypadku operacji odczytu i zapisu za pomocą modułu We/Wy przestrzennego.

Format danych	Przeczytaj	Napisz
GeoJSON	✓	✓
GeoRSS	✓	✓
GML	✓	✓
GPX	✓	✓
KmL	✓	✓
KmZ	✓	✓
Wolumin CSV przestrzenny	✓	✓
Dobrze znany tekst	✓	✓

W następnych sekcjach opisano wszystkie różne narzędzia do odczytywania i zapisywania danych przestrzennych przy użyciu modułu We/Wy przestrzennego.

Odczytywanie danych przestrzennych

Funkcja atlas.io.read jest główną funkcją służącą do odczytywania typowych formatów danych przestrzennych, takich jak KML, GPX, GeoRSS, GeoJSON i pliki CSV z danymi przestrzennymi. Ta funkcja może również odczytywać skompresowane wersje tych formatów jako plik zip lub plik KMZ. Format pliku KMZ to skompresowana wersja kmL, która może również zawierać zasoby, takie jak obrazy. Alternatywnie funkcja read może przyjmować adres URL wskazujący plik w dowolnym z tych formatów. Adresy URL powinny być hostowane w punkcie końcowym z włączoną obsługą mechanizmu CORS lub w opcjach odczytu należy podać usługę proxy. Usługa serwera proxy służy do ładowania zasobów w domenach, które nie są włączone przez mechanizm CORS. Funkcja read zwraca obietnicę dodania ikon obrazu do mapy i przetwarza dane asynchronicznie w celu zminimalizowania wpływu na wątek interfejsu użytkownika.

Podczas odczytywania skompresowanego pliku jako pliku zip lub KMZ po rozpakowaniu szuka pierwszego prawidłowego pliku. Na przykład plik doc.kml lub plik z innym prawidłowym rozszerzeniem, np. .kml, .xml, geojson, .json, .csv, tsv lub .txt. Następnie obrazy przywoływane w plikach KML i GeoRSS są wstępnie ładowane, aby upewnić się, że są dostępne. Niedostępne dane obrazu mogą ładować alternatywny obraz rezerwowy lub usuwać je ze stylów. Obrazy wyodrębnione z plików KMZ są konwertowane na identyfikatory URI danych.

Wynik funkcji read jest obiektem SpatialDataSet . Ten obiekt rozszerza klasę GeoJSON FeatureCollection. Można go łatwo przekazać do DataSource elementu as-is w celu renderowania jego funkcji na mapie. Zawiera SpatialDataSet nie tylko informacje o funkcji, ale może również zawierać nakładki naziemne KML, metryki przetwarzania i inne szczegóły, jak opisano w poniższej tabeli.

Nazwa właściwości	Typ	Opis
`bbox`	`BoundingBox`	Pole ograniczenia wszystkich danych w zestawie danych.
`features`	`Feature[]`	Funkcje GeoJSON w zestawie danych.
`groundOverlays`	`(atlas.layer.ImageLayer \| atlas.layers.OgcMapLayer)[]`	Tablica podkładek kmL GroundOverlays.
`icons`	Ciąg rekordu<, ciąg>	Zestaw adresów URL ikon. Klucz = nazwa ikony, Wartość = adres URL.
właściwości	dowolny	Informacje o właściwościach udostępniane na poziomie dokumentu zestawu danych przestrzennych.
`stats`	`SpatialDataSetStats`	Statystyki dotyczące zawartości i czasu przetwarzania zestawu danych przestrzennych.
`type`	`'FeatureCollection'`	Wartość typu GeoJSON tylko do odczytu.

Przykłady odczytywania danych przestrzennych

W przykładzie Ładowanie danych przestrzennych pokazano, jak odczytać zestaw danych przestrzennych i renderować go na mapie przy użyciu SimpleDataLayer klasy . Kod używa pliku GPX wskazywanego przez adres URL. Aby uzyskać kod źródłowy tego przykładu, zobacz Ładowanie kodu źródła danych przestrzennych.

W następnym pokazie kodu pokazano, jak odczytywać i ładować klucz KML lub KMZ do mapy. Rozwiązanie KML może zawierać nakładki gruntowe, które są w postaci elementu ImageLayer lub OgcMapLayer. Te nakładki należy dodać na mapie niezależnie od funkcji. Ponadto jeśli zestaw danych ma niestandardowe ikony, te ikony muszą zostać załadowane do zasobów mapy przed załadowaniem funkcji.

Przykład ładowania kml na mapie pokazuje, jak załadować pliki KML lub KMZ na mapę. Aby uzyskać kod źródłowy tego przykładu, zobacz Ładowanie usługi KML do kodu źródłowego mapy.

Opcjonalnie możesz udostępnić usługę proxy na potrzeby uzyskiwania dostępu do zasobów między domenami, które nie mają włączonego mechanizmu CORS. Funkcja read próbuje uzyskać dostęp do plików w innej domenie przy użyciu mechanizmu CORS najpierw. Przy pierwszym niepodaniu dostępu do dowolnego zasobu w innej domenie przy użyciu mechanizmu CORS żąda więcej plików tylko w przypadku świadczenia usługi serwera proxy. Funkcja read dołącza adres URL pliku na końcu podanego adresu URL serwera proxy. Ten fragment kodu pokazuje, jak przekazać usługę proxy do funkcji 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 . . .
    }
});

Poniższy fragment kodu pokazuje, jak odczytać rozdzielany plik i renderować go na mapie. W tym przypadku kod używa pliku CSV zawierającego kolumny danych przestrzennych. Musisz dodać odwołanie do modułu We/Wy usługi Azure Maps Spatial.

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

Zapisywanie danych przestrzennych

W module we/wy przestrzennym istnieją dwie główne funkcje zapisu. Funkcja atlas.io.write generuje ciąg, podczas gdy atlas.io.writeCompressed funkcja generuje skompresowany plik zip. Skompresowany plik zip będzie zawierać plik tekstowy z danymi przestrzennymi. Obie te funkcje zwracają obietnicę dodania danych do pliku. Obie te elementy mogą zapisywać dowolne z następujących danych: SpatialDataSet, , DataSourceImageLayer, OgcMapLayer, kolekcja funkcji, funkcja, geometria lub tablica dowolnej kombinacji tych typów danych. Podczas pisania przy użyciu obu funkcji można określić żądany format pliku. Jeśli format pliku nie jest określony, dane są zapisywane jako KML.

Przykład opcji zapisu danych przestrzennych to narzędzie, które demonstruje większość opcji zapisu, które mogą być używane z funkcją atlas.io.write . Aby uzyskać kod źródłowy tego przykładu, zobacz Spatial data write options source code (Kod źródłowy opcji zapisu danych przestrzennych).

Przykład zapisywania danych przestrzennych

Przykład przeciągania i upuszczania plików przestrzennych na mapie umożliwia przeciąganie i upuszczanie jednego lub większej liczby plików KML, KMZ, GeoRSS, GPX, GML, GeoJSON lub CSV na mapie. Aby uzyskać kod źródłowy tego przykładu, zobacz Przeciąganie i upuszczanie plików przestrzennych na kod źródłowy mapy.

Opcjonalnie możesz udostępnić usługę proxy na potrzeby uzyskiwania dostępu do zasobów między domenami, które nie mają włączonego mechanizmu CORS. Ten fragment kodu pokazuje, że można dołączyć usługę serwera proxy:

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

Odczytywanie i zapisywanie dobrze znanego tekstu (WKT)

Dobrze znany tekst (WKT) to standard Open Geospatial Consortium (OGC) reprezentujący geometrie przestrzenne jako tekst. Wiele systemów geoprzestrzennych obsługuje oprogramowanie WKT, takie jak Azure SQL i Azure PostgreSQL przy użyciu wtyczki PostGIS. Podobnie jak większość standardów OGC, współrzędne są formatowane jako "szerokość geograficzna długości geograficznej", aby dopasować je do konwencji "x y". Na przykład punkt o długości geograficznej -110 i szerokości geograficznej 45 można zapisać jako POINT(-110 45) przy użyciu formatu WKT.

Dobrze znany tekst można odczytywać przy użyciu atlas.io.ogc.WKT.read funkcji i zapisywać przy atlas.io.ogc.WKT.write użyciu funkcji .

Przykłady odczytywania i pisania dobrze znanego tekstu (WKT)

W przykładzie Read Well Known Text pokazano, jak odczytać dobrze znany ciąg POINT(-122.34009 47.60995) tekstowy i renderować go na mapie przy użyciu warstwy bąbelkowej. Aby uzyskać kod źródłowy tego przykładu, zobacz Read Well Known Text source code (Odczytywanie dobrze znanego kodu źródłowego tekstu).

W przykładzie Odczyt i zapis dobrze znanego tekstu pokazano, jak odczytywać i zapisywać ciągi dobrze znanego tekstu (WKT) jako dane GeoJSON. Aby zapoznać się z kodem źródłowym tego przykładu, zobacz Odczytywanie i zapisywanie dobrze znanego kodu źródłowego tekstu.

Odczytywanie i zapisywanie kodu GML

GML to przestrzenna specyfikacja pliku XML często używana jako rozszerzenie do innych specyfikacji XML. Dane GeoJSON można zapisywać jako XML z tagami GML przy użyciu atlas.io.core.GmlWriter.write funkcji . Kod XML zawierający język GML można odczytać przy użyciu atlas.io.core.GmlReader.read funkcji . Funkcja read ma dwie opcje:

Opcja isAxisOrderLonLat — kolejność osi współrzędnych "szerokość geograficzna, długość geograficzna" lub "długość geograficzna, szerokość geograficzna" może się różnić między zestawami danych i nie zawsze jest dobrze zdefiniowana. Domyślnie czytnik GML odczytuje dane współrzędnych jako "szerokość geograficzna, długość geograficzna", ale ustawienie tej opcji w taki sposób, aby odczytywało je jako "długość geograficzna, szerokość true geograficzna".
Opcja propertyTypes — ta opcja jest tabelą odnośników wartości klucza, w której klucz jest nazwą właściwości w zestawie danych. Wartość jest typem obiektu, który rzutuje wartość na wartość podczas analizowania. Obsługiwane wartości typów to: string, , numberbooleani date. Jeśli właściwość nie znajduje się w tabeli odnośników lub typ nie jest zdefiniowany, właściwość jest analizowana jako ciąg.

Funkcja atlas.io.read jest domyślnie ustawiona na atlas.io.core.GmlReader.read funkcję, gdy wykryje, że dane wejściowe to XML, ale dane nie są jednym z innych formatów przestrzennych XML.

GmlReader Współrzędne analizy, które mają jeden z następujących identyfikatorów SRID:

EPSG:4326 (preferowane)
EPSG:4269, EPSG:4283, EPSG:4258, EPSG:4308, EPSG:4230, EPSG:4272, EPSG:4271, EPSG:4267, EPSG:4608, EPSG:4674 prawdopodobnie z niewielkim marginesem błędu.
EPSG:3857, EPSG:102100, EPSG:3785, EPSG:900913, EPSG:102113, EPSG:41001, EPSG:54004