Чтение и запись пространственных данных

Статья
11/08/2023

В следующей таблице перечислены форматы пространственных файлов, поддерживаемые для операций чтения и записи с помощью модуля пространственного ввода-вывода.

Формат данных	Читать	Запись
GeoJSON	✓	✓
GeoRSS	✓	✓
GML	✓	✓
GPX	✓	✓
KML	✓	✓
KMZ	✓	✓
Пространственный CSV	✓	✓
Well-Known Text	✓	✓

В следующих разделах описаны различные средства чтения и записи пространственных данных с помощью модуля пространственного ввода-вывода.

Чтение пространственных данных

Функция atlas.io.read является основной функцией, используемой для чтения стандартных форматов пространственных данных, таких как KML, GPX, GeoRSS, GeoJSON и CSV-файлы с пространственными данными. Эта функция также может считывать сжатые версии этих форматов в виде ZIP-файла или файла KMZ. Формат файла KMZ — это сжатая версия KML, которая также может содержать ресурсы, например изображения. Кроме того, функция Read может принимать URL-адрес, указывающий на файл в любом из этих форматов. URL-адреса должны размещаться на конечной точке с поддержкой CORS, или в параметрах чтения должна быть указана прокси-служба. Прокси-служба используется для загрузки ресурсов в доменах, которые не включены в CORS. Функция Read возвращает обещание для добавления значков изображения на карту и асинхронно обрабатывает данные, чтобы снизить воздействие на поток пользовательского интерфейса.

При чтении сжатого файла в виде ZIP-файла или KMZ после распакачивания он ищет первый допустимый файл. Например, doc.kml или файл с другим допустимым расширением, например .kml, .xml, geojson, .json, .csv, .tsv или .txt. Затем образы, указанные в файлах KML и GeoRSS, предварительно загружаются, чтобы обеспечить их доступность. Недоступные данные изображения могут загружать альтернативный резервный образ или удаляться из стилей. Изображения, извлеченные из файлов KMZ, преобразуются в URI данных.

Результатом функции Read является объект SpatialDataSet. Этот объект расширяет класс GeoJSON FeatureCollection. Его можно легко передать в виде "DataSource как есть" для отрисовки его функций на карте. Не SpatialDataSet только содержит сведения о функциях, но и может включать наложения на землю KML, метрики обработки и другие сведения, как описано в следующей таблице.

Имя свойства	Type	Описание
`bbox`	`BoundingBox`	Ограничивающий прямоугольник всех данных в наборе данных.
`features`	`Feature[]`	Функции GeoJSON в наборе данных.
`groundOverlays`	`(atlas.layer.ImageLayer \| atlas.layers.OgcMapLayer)[]`	Массив KML GroundOverlays.
`icons`	Строка <записи, строка>	Набор URL-адресов значков. Key = имя значка, Value = URL-адрес.
свойства	любое	Сведения о свойствах, предоставляемые на уровне документа для пространственного набора данных.
`stats`	`SpatialDataSetStats`	Статистика по содержимому и времени обработки пространственных наборов данных.
`type`	`'FeatureCollection'`	Значение типа геотабличного формата JSON, доступное только для чтения.

Примеры чтения пространственных данных

В примере пространственных данных load показано, как считывать пространственный набор данных и отображать его на карте с помощью SimpleDataLayer класса. В коде используется файл GPX, на который указывает URL-адрес. Исходный код этого примера см. в разделе "Загрузка исходного кода пространственных данных".

В следующей демонстрации кода показано, как считывать и загружать KML или KMZ на карту. KML может содержать наложение земли, которое находится в виде ImageLayer или OgcMapLayer. Эти наложения должны быть добавлены на карту отдельно от функций. Кроме того, если в наборе данных есть настраиваемые значки, эти значки должны быть загружены в ресурсы карты до загрузки компонентов.

В примере load KML на карту показано, как загрузить файлы KML или KMZ на карту . Исходный код этого примера см. в разделе "Загрузка KML" в исходный код карты.

При необходимости можно предоставить прокси-службу для доступа к ресурсам между доменами, которые не включены CORS. Функция чтения сначала пытается получить доступ к файлам в другом домене с помощью 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.

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

Запись пространственных данных

В модуле пространственного ввода-вывода есть две основные функции записи. Функция atlas.io.write создает строку, а функция atlas.io.writeCompressed создает сжатый ZIP-файл. Сжатый ZIP-файл будет содержать текстовый файл с пространственными данными. Обе эти функции возвращают обещание для добавления данных в файл. И они могут записывать любые из следующих данных: SpatialDataSet, DataSource, ImageLayer, OgcMapLayer, коллекцию функций, функцию, геометрию или массив любого сочетания этих типов данных. При записи с помощью любой из этих функций можно указать требуемый формат файла. Если формат файла не указан, данные записываются как KML.

Пример параметров записи пространственных данных — это инструмент, демонстрирующий большинство вариантов записи, которые можно использовать с функцией atlas.io.write . Исходный код этого примера см. в разделе "Параметры записи пространственных данных".

Пример записи пространственных данных

Перетаскивание пространственных файлов на карту позволяет перетащить один или несколько KML, KMZ, GeoRSS, GPX, GML, GeoJSON или CSV-файлы на карту . Исходный код этого примера см. в разделе "Перетаскивание пространственных файлов" на исходный код карты.

При необходимости можно предоставить прокси-службу для доступа к ресурсам между доменами, которые не включены CORS. В этом фрагменте кода показано, как можно включить прокси-службу:

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

Чтение и запись хорошо известного текста (WKT)

Хорошо известный текст (WKT) — это стандартный открытый геопространственный консорциум (OGC), представляющий пространственные геометрические объекты в виде текста. Многие геопространственные системы поддерживают WKT, такие как Azure SQL и Azure PostgreSQL, с помощью подключаемого модуля PostGIS. Как и большинство стандартов OGC, координаты форматируются как "долгота, широта" для согласования с соглашением "x y". Например, точка с долготой –110 и широтой 45 может быть написана как POINT(-110 45) с использованием формата WKT.

Хорошо известный текст можно считывать с помощью функции atlas.io.ogc.WKT.read и записать с помощью функции atlas.io.ogc.WKT.write функции.

Примеры чтения и записи хорошо известного текста (WKT)

В примере "Чтение известного текста " показано, как считывать известную текстовую строку POINT(-122.34009 47.60995) и отображать ее на карте с помощью пузырькового слоя. Исходный код этого примера см. в разделе "Чтение хорошо известного исходного кода текста".

В примере "Чтение и запись хорошо известного текста " показано, как читать и записывать строки хорошо известного текста (WKT) в качестве GeoJSON. Исходный код этого примера см. в разделе "Чтение и запись хорошо известного исходного кода текста".

Чтение и запись GML

GML — это спецификация пространственного XML-файла, часто используемая в качестве расширения для других спецификаций XML. Данные GeoJSON можно записать в виде XML-кода с помощью тегов GML, используя функцию atlas.io.core.GmlWriter.write. XML-код, содержащий GML, можно считать с помощью функции atlas.io.core.GmlReader.read. Функция Read имеет два варианта:

Параметр isAxisOrderLonLat — порядок осей координат "широта, долгота" или "долгота, долгота" может различаться между наборами данных, и он не всегда определен правильно. По умолчанию средство чтения GML считывает данные координат в виде широты, долготы, но при задании этого параметра true оно считывается как "долгота, широта".
Параметр propertyTypes — это таблица уточняющих значений ключа, где ключ — это имя свойства в наборе данных. Значение — это тип объекта для приведения значения при синтаксическом анализе. Поддерживаемые значения: string, number, boolean и date. Если свойство не находится в таблице подстановки или тип не определен, свойство анализируется как строка.

Функция atlas.io.read по умолчанию atlas.io.core.GmlReader.read используется при обнаружении входных данных XML, но данные не являются одним из других форматов пространственных XML.

Координаты GmlReader синтаксического анализа, имеющие один из следующих идентификаторов ШРИД:

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