Ler e escrever dados espaciais

Artigo
09/25/2024

A tabela a seguir lista os formatos de arquivo espacial suportados para operações de leitura e gravação com o módulo E/S espacial.

Formato de Dados	Lida	Escrita
GeoJSON	✓	✓
GeoRSS	✓	✓
GML	✓	✓
GPX	✓	✓
KML	✓	✓
KMZ	✓	✓
CSV espacial	✓	✓
Texto bem conhecido	✓	✓

Estas próximas seções descrevem todas as diferentes ferramentas para ler e gravar dados espaciais usando o módulo IO espacial.

Ler dados espaciais

A atlas.io.read função é a principal função usada para ler formatos comuns de dados espaciais, como KML, GPX, GeoRSS, GeoJSON e arquivos CSV com dados espaciais. Esta função também pode ler versões compactadas desses formatos, como um arquivo zip ou um arquivo KMZ. O formato de arquivo KMZ é uma versão compactada do KML que também pode incluir ativos como imagens. Como alternativa, a função de leitura pode receber um URL que aponte para um arquivo em qualquer um desses formatos. As URLs devem ser hospedadas em um ponto de extremidade habilitado para CORS ou um serviço de proxy deve ser fornecido nas opções de leitura. O serviço de proxy é usado para carregar recursos em domínios que não estão habilitados para CORS. A função de leitura retorna uma promessa de adicionar os ícones de imagem ao mapa e processa dados de forma assíncrona para minimizar o impacto no thread da interface do usuário.

Ao ler um arquivo compactado, seja como um zip ou KMZ, uma vez descompactado, ele procura o primeiro arquivo válido. Por exemplo, doc.kml ou um arquivo com outra extensão válida, como: .kml, .xml, geojson, .json, .csv, .tsv ou .txt. Em seguida, as imagens referenciadas nos arquivos KML e GeoRSS são pré-carregadas para garantir que estejam acessíveis. Os dados de imagem inacessíveis podem carregar uma imagem alternativa de fallback ou ser removidos dos estilos. As imagens extraídas de arquivos KMZ são convertidas em URIs de dados.

O resultado da função de leitura é um SpatialDataSet objeto. Este objeto estende a classe GeoJSON FeatureCollection. Ele pode ser facilmente passado para um DataSource como está para renderizar suas características em um mapa. O SpatialDataSet não contém apenas informações de recursos, mas também pode incluir sobreposições de solo KML, métricas de processamento e outros detalhes, conforme descrito na tabela a seguir.

Nome da propriedade	Tipo	Description
`bbox`	`BoundingBox`	Caixa delimitadora de todos os dados no conjunto de dados.
`features`	`Feature[]`	Recursos GeoJSON dentro do conjunto de dados.
`groundOverlays`	`(atlas.layer.ImageLayer \| atlas.layers.OgcMapLayer)[]`	Uma matriz de KML GroundOverlays.
`icons`	String de gravação<, string>	Um conjunto de URLs de ícones. Chave = nome do ícone, Valor = URL.
propriedades	qualquer	Informações de propriedade fornecidas no nível do documento de um conjunto de dados espaciais.
`stats`	`SpatialDataSetStats`	Estatísticas sobre o conteúdo e o tempo de processamento de um conjunto de dados geográficos.
`type`	`'FeatureCollection'`	Valor do tipo GeoJSON somente leitura.

Exemplos de leitura de dados espaciais

O exemplo Load spatial data mostra como ler um conjunto de dados espaciais e o renderiza no mapa usando a SimpleDataLayer classe. O código usa um arquivo GPX apontado por uma URL. Para obter o código-fonte deste exemplo, consulte Carregar código-fonte de dados espaciais.

A próxima demonstração de código mostra como ler e carregar KML, ou KMZ, no mapa. KML pode conter sobreposições de solo, que está na forma de um ImageLayer ou OgcMapLayer. Essas sobreposições devem ser adicionadas no mapa separadamente dos recursos. Além disso, se o conjunto de dados tiver ícones personalizados, esses ícones precisarão ser carregados nos recursos de mapas antes que os recursos sejam carregados.

O exemplo Carregar KML no mapa mostra como carregar arquivos KML ou KMZ no mapa. Para obter o código-fonte deste exemplo, consulte Carregar KML no código-fonte do mapa.

Opcionalmente, você pode fornecer um serviço de proxy para acessar ativos entre domínios que não tenham o CORS habilitado. A função de leitura tenta acessar arquivos em outro domínio usando CORS primeiro. A primeira vez que ele não consegue acessar qualquer recurso em outro domínio usando CORS, ele só solicita mais arquivos se um serviço de proxy for fornecido. A função de leitura acrescenta a URL do arquivo ao final da URL de proxy fornecida. Este trecho de código mostra como passar um serviço de proxy para a função de leitura:

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

O trecho de código a seguir mostra como ler um arquivo delimitado e processá-lo no mapa. Nesse caso, o código usa um arquivo CSV que tem colunas de dados espaciais. Você deve adicionar uma referência ao módulo de E/S Espacial do 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>

Escrever dados espaciais

Existem duas funções principais de escrita no módulo IO espacial. A atlas.io.write função gera uma cadeia de caracteres, enquanto a atlas.io.writeCompressed função gera um arquivo zip compactado. O arquivo zip compactado conteria um arquivo baseado em texto com os dados espaciais nele. Ambas as funções retornam uma promessa de adicionar os dados ao arquivo. E ambos podem gravar qualquer um dos seguintes dados: SpatialDataSet, DataSource, ImageLayer, OgcMapLayer, coleção de recursos, característica, geometria ou uma matriz de qualquer combinação desses tipos de dados. Ao escrever usando qualquer uma das funções, você pode especificar o formato de arquivo desejado. Se o formato de arquivo não for especificado, os dados serão gravados como KML.

O Exemplo de opções de gravação de dados espaciais é uma ferramenta que demonstra a maioria das opções de gravação que podem ser usadas com a atlas.io.write função. Para obter o código-fonte deste exemplo, consulte Código-fonte de opções de gravação de dados espaciais.

Exemplo de escrita de dados espaciais

O exemplo Arrastar e soltar arquivos espaciais no mapa permite arrastar e soltar um ou mais arquivos KML, KMZ, GeoRSS, GPX, GML, GeoJSON ou CSV no mapa. Para obter o código-fonte deste exemplo, consulte Arrastar e soltar arquivos espaciais no código-fonte do mapa.

Opcionalmente, você pode fornecer um serviço de proxy para acessar ativos entre domínios que não tenham o CORS habilitado. Este trecho de código mostra que você pode incorporar um serviço de proxy:

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

Ler e escrever texto conhecido (WKT)

Well-Known Text (WKT) é um padrão Open Geospatial Consortium (OGC) para representar geometrias espaciais como texto. Muitos sistemas geoespaciais suportam WKT, como o Azure SQL e o Azure PostgreSQL usando o plug-in PostGIS. Como a maioria dos padrões OGC, as coordenadas são formatadas como "latitude longitude" para alinhar com a convenção "x y". Como exemplo, um ponto na longitude -110 e latitude 45 pode ser escrito como POINT(-110 45) usando o formato WKT.

Texto bem conhecido pode ser lido usando a atlas.io.ogc.WKT.read função, e escrito usando a atlas.io.ogc.WKT.write função.

Exemplos de leitura e escrita de Texto Bem Conhecido (WKT)

O exemplo Read Well Known Text mostra como ler a cadeia de caracteres POINT(-122.34009 47.60995) de texto conhecida e renderizá-la no mapa usando uma camada de bolhas. Para obter o código-fonte deste exemplo, consulte Ler código-fonte de texto bem conhecido.

O exemplo Read and write Well Known Text demonstra como ler e escrever cadeias de caracteres WKT (Well Known Text) como GeoJSON. Para obter o código-fonte deste exemplo, consulte Ler e escrever código-fonte de texto conhecido.

Ler e escrever GML

GML é uma especificação de arquivo XML espacial frequentemente usada como uma extensão para outras especificações XML. Os dados GeoJSON podem ser escritos como XML com tags GML usando a atlas.io.core.GmlWriter.write função. O XML que contém GML pode ser lido usando a atlas.io.core.GmlReader.read função. A função de leitura tem duas opções:

A isAxisOrderLonLat opção - A ordem dos eixos das coordenadas "latitude, longitude" ou "longitude, latitude" pode variar entre conjuntos de dados, e nem sempre é bem definida. Por padrão, o leitor GML lê os dados de coordenadas como "latitude, longitude", mas definindo esta opção para true lê-los como "longitude, latitude".
A propertyTypes opção - Esta opção é uma tabela de pesquisa de valor de chave onde a chave é o nome de uma propriedade no conjunto de dados. O valor é o tipo de objeto para o qual o valor será convertido ao analisar. Os valores de tipo suportados são: string, number, booleane date. Se uma propriedade não estiver na tabela de pesquisa ou se o tipo não estiver definido, a propriedade será analisada como uma cadeia de caracteres.

A atlas.io.read função assume como padrão a atlas.io.core.GmlReader.read função quando deteta que os dados de entrada são XML, mas os dados não são um dos outros formatos XML espaciais de suporte.

As GmlReader coordenadas de análise que têm um dos seguintes SRIDs:

EPSG: 4326 (preferencial)
EPSG:4269, EPSG:4283, EPSG:4258, EPSG:4308, EPSG:4230, EPSG:4272, EPSG:4271, EPSG:4267, EPSG:4608, EPSG:4674 possivelmente com uma pequena margem de erro.
EPSG:3857, EPSG:102100, EPSG:3785, EPSG:900913, EPSG:102113, EPSG:41001, EPSG:54004