Lectura y escritura de datos espaciales

Artículo
07/26/2023

La siguiente tabla enumera los formatos de archivos espaciales que son compatibles con las operaciones de lectura y escritura con el módulo Spatial IO.

Formato de datos	Lectura	Escritura
GeoJSON	✓	✓
GeoRSS	✓	✓
GML	✓	✓
GPX	✓	✓
KML	✓	✓
KMZ	✓	✓
CSV espacial	✓	✓
Well-Known Text (texto conocido)	✓	✓

En estas secciones se describen todas las distintas herramientas para leer y escribir datos espaciales mediante el módulo de E/S espacial.

Lectura de datos espaciales

atlas.io.read es la función principal que se usa para leer formatos de datos espaciales comunes, como KML, GPX, GeoRSS, GeoJSON y archivos CSV con datos espaciales. Esta función también puede leer versiones comprimidas de estos formatos, como un archivo ZIP o un archivo KMZ. El formato de archivo KMZ es una versión comprimida de KML que también puede incluir recursos como imágenes. Como alternativa, la función de lectura puede tomar una dirección URL que apunte a un archivo en cualquiera de estos formatos. Las direcciones URL deben estar hospedadas en un punto de conexión habilitado para CORS o se debe proporcionar un servicio de proxy en las opciones de lectura. El servicio de proxy se usa para cargar recursos en dominios que no están habilitados para CORS. La función de lectura devuelve una promesa para agregar los iconos de imagen al mapa y procesa los datos de forma asincrónica para minimizar el impacto en el subproceso de la interfaz de usuario.

Al leer un archivo comprimido, ya sea como un archivo ZIP o un KMZ, una vez descomprimido busca el primer archivo válido. Por ejemplo, doc.kml o un archivo con otra extensión válida, como .kml, .xml, geojson, .json, .csv, .tsv o .txt. A continuación, se cargan previamente las imágenes a las que se hace referencia en los archivos KML y GeoRSS para asegurarse de que están accesibles. Los datos de imagen inaccesibles pueden cargar una imagen alternativa o se quitarán de los estilos. Las imágenes extraídas de archivos KMZ se convertirán en URI de datos.

El resultado de la función de lectura es un objeto SpatialDataSet. Este objeto extiende la clase FeatureCollection de GeoJSON. Se puede pasar fácilmente a un DataSource tal cual para representar sus características en un mapa. El SpatialDataSet no solo contiene información de características, sino que también puede incluir superposiciones de suelo KML, métricas de procesamiento y otros detalles, como se describe en la tabla siguiente.

Nombre de propiedad	Type	Descripción
`bbox`	`BoundingBox`	Cuadro de límite de todos los datos del conjunto de datos.
`features`	`Feature[]`	Características de GeoJSON en el conjunto de datos.
`groundOverlays`	`(atlas.layer.ImageLayer \| atlas.layers.OgcMapLayer)[]`	Una matriz de KML GroundOverlays.
`icons`	Registro<cadena, cadena>	Un conjunto de direcciones URL de icono. Clave = nombre del icono, Valor = dirección URL.
properties	cualquiera	Información de propiedad proporcionada en el nivel de documento de un conjunto de datos espaciales.
`stats`	`SpatialDataSetStats`	Estadísticas sobre el contenido y el tiempo de procesamiento de un conjunto de datos espaciales.
`type`	`'FeatureCollection'`	Valor de tipo GeoJSON de solo lectura.

Ejemplos de lectura de datos espaciales

En el ejemplo Cargar datos espaciales, se muestra cómo leer un conjunto de datos espaciales y representarlo en el mapa mediante la claseSimpleDataLayer. El código usa un archivo GPX al que una dirección URL apunta. Para obtener el código fuente de este ejemplo, consulte el código fuente Carga de datos espaciales.

En la demostración de código siguiente se muestra cómo leer y cargar KML o KMZ en el mapa. KML puede contener superposiciones de suelo, que tendrán el formulario de ImageLayer o OgcMapLayer. Estas superposiciones deben agregarse en el mapa por separado de las características. Además, si el conjunto de datos tiene iconos personalizados, dichos iconos deben cargarse en los recursos de mapas antes de que se carguen las características.

En el ejemplo Cargar KML en el mapa, se muestra cómo cargar archivos KML o KMZ en el mapa. Para obtener el código fuente de este ejemplo, consulte el código fuente Carga de KML en el mapa.

Si quiere, puede proporcionar un servicio de proxy para acceder a los recursos entre dominios que pueden no tener CORS habilitado. La función de lectura intenta acceder a archivos en otro dominio usando CORS primero. Después de la primera vez que falla al acceder a cualquier recurso en otro dominio usando CORS, solo solicita más archivos si se proporciona un servicio proxy. La función read anexa la dirección URL del archivo al final de la dirección URL del proxy proporcionada. En este fragmento de código se muestra cómo pasar un servicio de proxy a la función de lectura:

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

En el siguiente fragmento de código, se muestra cómo leer un archivo delimitado y representarlo en el mapa. En este caso, el código usa un archivo CSV que tiene columnas de datos espaciales. Debe añadir una referencia al módulo Azure Maps Spatial IO.

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

Escritura de datos espaciales

Hay dos funciones de escritura principales en el módulo de E/S espacial. La función atlas.io.write genera una cadena, mientras que la función atlas.io.writeCompressed genera un archivo ZIP comprimido. El archivo ZIP comprimido contendría un archivo basado en texto con los datos espaciales. Ambas funciones devuelven una promesa para agregar los datos al archivo. Además, ambos pueden escribir cualquiera de los siguientes datos: SpatialDataSet, DataSource, ImageLayer, OgcMapLayer, colección de características, característica, geometría o una matriz de cualquier combinación de estos tipos de datos. Al escribir con cualquiera de las funciones, puede especificar el formato de archivo deseado. Si no se especifica el formato de archivo, los datos se escriben como KML.

El ejemplo de opciones de escritura de datos espaciales es una herramienta que demuestra la mayoría de las opciones de escritura que pueden utilizarse con la atlas.io.write función. Para obtener el código fuente de este ejemplo, consulte el código fuente Opciones de escritura de datos espaciales.

Ejemplo de escritura de datos espaciales

El ejemplo Arrastrar y colocar archivos espaciales en el mapa permite arrastrar y colocar uno o varios archivos KML, KMZ, GeoRSS, GPX, GML, GeoJSON o CSV en el mapa. Para obtener el código fuente de este ejemplo, consulte el código fuente Arrastrar y colocar archivos espaciales en un mapa.

Si quiere, puede proporcionar un servicio de proxy para acceder a los recursos entre dominios que pueden no tener CORS habilitado. Este fragmento de código muestra que puede incorporar un servicio 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 ...
    }
);

Lectura y escritura de Well-Known Text (WKT)

Well-Known Text (WKT) es un estándar de Open Geospatial Consortium (OGC) para representar geometrías espaciales en forma de texto. Muchos sistemas geoespaciales admiten WKT, como Azure SQL y Azure PostgreSQL con el complemento PostGIS. Como la mayoría de los estándares de OGC, las coordenadas tienen el formato de "longitud latitud" para alinearse con la convención "x y". Por ejemplo, un punto de longitud -110 y latitud 45 se puede escribir como POINT(-110 45) en el formato WKT.

El texto WKT se puede leer con la función atlas.io.ogc.WKT.read y escribir con la función atlas.io.ogc.WKT.write.

Ejemplos de lectura y escritura de Well-Known Text (WKT)

En el ejemplo Lectura de texto Well Known Text, se muestra cómo leer la cadena de texto WKT POINT(-122.34009 47.60995) y representarla en el mapa mediante una capa de burbujas. Para obtener el código fuente de este ejemplo, consulte el código fuente Lectura de texto Well Known Text.

En el ejemplo de lectura y escritura de texto Well Known Text, se muestra cómo leer y escribir cadenas de texto WKT como GeoJSON. Para obtener el código fuente de este ejemplo, consulte el código fuente Lectura y escritura de WKT.

Lectura y escritura de GML

GML es una especificación de archivo XML espacial que se suele usar como extensión de otras especificaciones XML. Los datos de GeoJSON se pueden escribir como XML con etiquetas GML mediante la función atlas.io.core.GmlWriter.write. El XML que contiene GML se puede leer mediante la función atlas.io.core.GmlReader.read. La función de lectura tiene dos opciones:

La opción isAxisOrderLonLat: el orden de los ejes de las coordenadas "latitud, longitud" o "longitud, latitud" puede variar entre los conjuntos de datos y no siempre está bien definido. De manera predeterminada, el lector GML lee los datos de coordenadas como "latitud, longitud" pero, si se establece esta opción para que lostrue lea como "longitud, latitud".
La opción propertyTypes: esta opción es una tabla de búsqueda de valores clave donde la clave es el nombre de una propiedad del conjunto de datos. El valor es el tipo de objeto al que se va a convertir el valor al analizar. Los valores de tipo admitidos son: string, number, boolean y date. Si una propiedad no está en la tabla de búsqueda o el tipo no está definido, la propiedad se analiza como una cadena.

La atlas.io.readfunción utiliza por defecto laatlas.io.core.GmlReader.read función cuando detecta que los datos de entrada son XML, pero los datos no son uno de los otros formatos XML espaciales admitidos.

GmlReaderAnaliza las coordenadas que tienen uno de los siguientes SRID:

EPSG:4326 (preferido)
EPSG:4269, EPSG:4283, EPSG:4258, EPSG:4308, EPSG:4230, EPSG:4272, EPSG:4271, EPSG:4267, EPSG:4608, EPSG:4674 posiblemente con un pequeño margen de error.
EPSG:3857, EPSG:102100, EPSG:3785, EPSG:900913, EPSG:102113, EPSG:41001, EPSG:54004