Ler e gravar dados espaciais

Artigo
11/20/2023

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

Formato de Dados	Ler	Gravar
GeoJSON	✓	✓
GeoRSS	✓	✓
GML	✓	✓
GPX	✓	✓
KML	✓	✓
KMZ	✓	✓
CSV espacial	✓	✓
Texto bem conhecido	✓	✓

As seções a seguir descrevem todas as diferentes ferramentas para leitura e gravação de dados espaciais usando o módulo de E/S espacial.

Ler dados espaciais

A função atlas.io.read é a função principal usada para ler formatos de dados espaciais comuns, como arquivos KML, GPX, GeoRSS, GeoJSON e CSV com os dados espaciais. Essa 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 assumir uma URL que aponta 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 para adicionar os ícones de imagem ao mapa e processa os dados de modo assíncrono para minimizar o impacto no thread da IU.

Ao ler um arquivo compactado, como um zip ou um 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. Dados de imagem inacessíveis podem carregar uma imagem de fallback alternativa ou removida dos estilos. Imagens extraídas de arquivos KMZ serão convertidas em URIs de dados.

O resultado da função de leitura é um objeto SpatialDataSet. Esse objeto estende a classe GeoJSON FeatureCollection. Ele pode ser facilmente passado para um DataSource no estado em que se encontra para renderizar seus recursos em um mapa. O SpatialDataSet não só contém informações de recurso, mas também pode incluir sobreposições terrestres KML, métricas de processamento e outros detalhes, conforme descrito na tabela a seguir.

Nome da propriedade	Type	Descrição
`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 GroundOverlays KML.
`icons`	Record<string, string>	Um conjunto de URLs de ícone. Chave = nome do ícone, valor = URL.
properties	any	Informações de propriedade fornecidas no nível de 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 espaciais.
`type`	`'FeatureCollection'`	Valor de tipo GeoJSON somente leitura.

Exemplos de leitura de dados espaciais

O exemplo Carregar dados espaciais mostra como ler um conjunto de dados espaciais e renderizá-lo no mapa usando a classe SimpleDataLayer. O código usa um arquivo GPX apontado por uma URL. Para obter o código-fonte desse exemplo, confira 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. Um KML pode conter sobreposições de solo, que estarão na forma de um ImageLyaer ou OgcMapLayer. Essas sobreposições devem ser adicionadas ao 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 de os recursos serem carregados.

O exemplo Carregar KML no mapa mostra como carregar arquivos KML ou KMZ no mapa. Para obter o código-fonte desse exemplo, confira Carregar o 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 têm o CORS habilitado. A função de leitura tentará acessar os arquivos em outro domínio usando o CORS primeiro. Na primeira vez em que ele não puder acessar qualquer recurso em outro domínio usando CORS, ele só solicitará mais arquivos se um serviço de proxy for fornecido. A função de leitura acrescenta a URL do arquivo ao final da URL do proxy fornecida. Este snippet 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 renderizá-lo no mapa. Nesse caso, o código usa um arquivo CSV que tem colunas de dados espaciais. Observe que você deve adicionar uma referência ao módulo de E/S espacial do Azure Mapas.


<!-- 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 type="text/javascript">
var map, datasource, layer;

//a URL pointing to the CSV file
var delimitedFileUrl = "https://s3-us-west-2.amazonaws.com/s.cdpn.io/1717245/earthquakes_gt7_alltime.csv";

function InitMap()
{
  map = new atlas.Map('myMap', {
    center: [-73.985708, 40.75773],
    zoom: 12,
    view: "Auto",

    //Add authentication details for connecting to Azure Maps.
    authOptions: {
      // Get an Azure Maps key at https://azuremaps.com/.
      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>

Gravar dados espaciais

Há duas funções de gravação principais no módulo de E/S espacial. A função atlas.io.write gera uma cadeia de caracteres, enquanto a função atlas.io.writeCompressed gera um arquivo ZIP compactado. O arquivo ZIP compactado conterá um arquivo baseado em texto com os dados espaciais nele. Essas duas funções retornam uma promessa para adicionar os dados ao arquivo. Ambos podem gravar qualquer um dos seguintes dados: SpatialDataSet, DataSource, ImageLayer, OgcMapLayer, coleção de recursos, recurso, 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 função atlas.io.write. Para obter o código-fonte desse exemplo, confira Código-fonte das opções de gravação de dados espaciais.

Exemplo de gravação 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 desse exemplo, confira 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 têm o CORS habilitado. Este snippet 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 WKT (texto bem conhecido)

WKT (texto bem conhecido) é um padrão do OGC (Open Geospatial Consortium) para representar geometrias espaciais como texto. Muitos sistemas geoespaciais dão suporte a WKT, como SQL do Azure e Azure PostgreSQL usando o plug-in PostGIS. Como a maioria dos padrões de OGC, as coordenadas são formatadas como "latitude de longitude" para alinhamento com a convenção "x y". Por exemplo, um ponto em longitude -110 e latitude 45 pode ser escrito como POINT(-110 45) usando o formato WKT.

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

Exemplos de leitura e gravação de WKT (texto bem conhecido)

O exemplo Ler Well Known Text (WKT) mostra como ler uma string WKT POINT(-122.34009 47.60995) e renderizá-la no mapa usando uma camada de bolha. Para obter o código-fonte desse exemplo, confira Leitura do código-fonte do Texto Bem Conhecido.

O exemplo Ler e gravar Well Known Text demonstra como ler e gravar strings WKT (Well Known Text) como GeoJSON. Para obter o código-fonte desse exemplo, confira Leitura e gravação do código-fonte do Texto Bem Conhecido.

Ler e gravar 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 gravados como XML com marcas GML usando a função atlas.io.core.GmlWriter.write. O XML que contém GML pode ser lido usando a função atlas.io.core.GmlReader.read. A função de leitura tem duas opções:

A opção isAxisOrderLonLat – a ordem do eixo das coordenadas "latitude, longitude" ou "longitude, latitude" pode variar entre os conjuntos de dados e nem sempre é bem definida. Por padrão, o leitor de GML lê os dados de coordenadas como "latitude, longitude", mas configurar essa opção como true os lerá como "longitude, latitude".
A opção propertyTypes – essa opção é uma tabela de pesquisa de valor de chave em que a chave é o nome de uma propriedade no conjunto de dados. O valor é o tipo de objeto para o qual converter o valor durante a análise. Os valores de tipo com suporte são: string, number, boolean e date. Se uma propriedade não estiver na tabela de pesquisa ou o tipo não estiver definido, a propriedade será analisada como uma cadeia de caracteres.

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

O GmlReader analisa as coordenadas 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