Lire et écrire des données spatiales

Article
11/22/2023

Le tableau suivant répertorie les formats de fichiers spatiaux pris en charge pour la lecture et l’écriture d’opérations avec le module d’E/S spatiales.

Format de données	Lire	Write
GeoJSON	✓	✓
GeoRSS	✓	✓
GML	✓	✓
GPX	✓	✓
KML	✓	✓
KMZ	✓	✓
Spatial CSV	✓	✓
Well-Known Text	✓	✓

Les sections suivantes décrivent tous les différents outils de lecture et d’écriture de données spatiales à l’aide du module d’E/S spatiales.

Lire des données spatiales

La fonction atlas.io.read est la fonction principale utilisée pour lire des formats courants de données spatiales tels que des fichiers KML, GPX, GeoRSS, GeoJSON et CSV avec des données spatiales. Cette fonction peut également lire les versions compressées de ces formats, sous la forme d’un fichier zip ou d’un fichier KMZ. Le format de fichier KMZ est une version compressée de KML qui peut également inclure des ressources telles que des images. La fonction de lecture peut également prendre une URL qui pointe vers un fichier dans l’un de ces formats. Les URL doivent être hébergées sur un point de terminaison CORS, sinon un service proxy doit être fourni dans les options de lecture. Le service proxy est utilisé pour charger des ressources sur des domaines qui ne sont pas compatibles avec CORS. La fonction de lecture retourne une promesse d’ajouter les icônes d’image à la carte et traite les données de façon asynchrone afin de réduire l’impact sur le thread d’interface utilisateur.

Lors de la lecture d'un fichier compressé, qu'il s'agisse d'un zip ou d'un KMZ, il recherche le premier fichier valide une fois qu'il a été décompressé. Par exemple, doc.kml ou un fichier avec une autre extension valide, telle que : .kml, .xml, .geojson, .json, .csv, .tsv ou .txt. Ensuite, les images référencées dans les fichiers KML et GeoRSS sont préchargées pour s’assurer qu’elles sont accessibles. Il est possible que des données d’image inaccessibles peuvent charger une autre image de secours ou soient supprimées des styles. Les images extraites de fichiers KMZ sont converties en URI de données.

Le résultat de la fonction de lecture est un objet SpatialDataSet. Cet objet étend la classe FeatureCollection GeoJSON. Il peut facilement être passé dans une DataSource tel quel pour afficher ses fonctionnalités sur une carte. Le SpatialDataSet contient non seulement des informations sur les fonctionnalités, mais il peut également inclure des superpositions de sol KML, des mesures de traitement et d’autres détails comme indiqué dans le tableau suivant.

Nom de la propriété	Type	Description
`bbox`	`BoundingBox`	Cadre englobant de toutes les données dans le jeu de données.
`features`	`Feature[]`	Fonctionnalités GeoJSON dans le jeu de données.
`groundOverlays`	`(atlas.layer.ImageLayer \| atlas.layers.OgcMapLayer)[]`	Tableau de superpositions de sol KML.
`icons`	Record<string, string>	Ensemble d’URL d’icône. Clé = nom de l’icône, valeur = URL.
properties	n'importe laquelle	Informations de propriété fournies au niveau du document d’un jeu de données spatiales.
`stats`	`SpatialDataSetStats`	Statistiques relatives au contenu et au temps de traitement d’un jeu de données spatiales.
`type`	`'FeatureCollection'`	Valeur de type GeoJSON en lecture seule.

Exemples de lecture des données spatiales

L’exemple Charger des données spatiales montre comment lire un jeu de données spatiales et le restituer sur la carte en utilisant la classe SimpleDataLayer. Le code utilise un fichier GPX pointé par une URL. Pour obtenir le code source de cet exemple, consultez Charger le code source des données spatiales.

La démonstration de code suivante montre comment lire et charger un fichier KML ou KMZ sur la carte. Un fichier KML peut contenir des superpositions de sol, qui prend la forme ImageLyaer ou OgcMapLayer. Ces superpositions doivent être ajoutées à la carte séparément des fonctionnalités. En outre, si le jeu de données a des icônes personnalisées, ces icônes doivent être chargées dans les ressources de cartes avant le chargement des fonctionnalités.

L’exemple Charger KML sur la carte montre comment charger des fichiers KML ou KMZ sur la carte. Pour obtenir le code source de cet exemple, consultez Charger le code source KML sur du mappage.

Vous pouvez éventuellement fournir un service proxy pour accéder aux ressources interdomaines pour lesquelles CORS n’est pas activé. La fonction de lecture essaie d’abord d’accéder aux fichiers d’un autre domaine en utilisant CORS. Une fois la tentative d’accès à une ressource d’un autre domaine échoue en utilisant CORS, elle ne demande d’autres fichiers que si un service proxy est fourni. La fonction de lecture ajoute l’URL du fichier à la fin de l’URL de proxy fournie. Cet extrait de code indique comment passer un service proxy à la fonction de lecture :

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

L’extrait de code suivant montre comment lire un fichier délimité et l’afficher sur la carte. Dans ce cas, le code utilise un fichier CSV qui contient des colonnes de données spatiales. Vous devez ajouter une référence au module d’E/S spatiales 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 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>

Écrire des données spatiales

Il existe deux fonctions d’écriture principales dans le module d’E/S spatiales. La fonction atlas.io.write génère une chaîne, tandis que la fonction atlas.io.writeCompressed génère un fichier zip compressé. Le fichier zip compressé contient un fichier texte contenant les données spatiales. Ces deux fonctions retournent une promesse d’ajouter les données au fichier. Elles peuvent aussi écrire les données suivantes : SpatialDataSet, DataSource, ImageLayer, OgcMapLayer, la collection de fonctionnalités, la fonctionnalité, la géométrie ou un tableau de n’importe quelle combinaison de ces types de données. Lors de l’écriture à l’aide de l’une de ces fonctions, vous pouvez spécifier le format de fichier souhaité. Si le format de fichier n’est pas spécifié, les données sont alors écrites au format KML.

L’exemple Options d’écriture de données spatiales est un outil qui illustre la plupart des options d’écriture qui peuvent être utilisées avec la fonction atlas.io.write. Pour obtenir le code source de cet exemple, consultez Code source des options d’écriture de données spatiales.

Exemple d’écriture de données spatiales

L’exemple Glisser-déplacer des fichiers spatiaux sur une carte vous permet de faire glisser-déplacer un ou plusieurs fichiers KML, KMZ, GeoRSS, GPX, GML, GeoJSON ou CSV sur la carte. Pour obtenir le code source de cet exemple, consultez Glisser-déplacer du code source des fichiers spatiaux sur la carte.

Vous pouvez éventuellement fournir un service proxy pour accéder aux ressources interdomaines pour lesquelles CORS n’est pas activé. Cet extrait de code montre que vous pouvez incorporer un service proxy :

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

Lire et écrire au format WKT (Well-Known Text)

WKT (Well-Known Text) est une norme de l’Open Geospatial Consortium (OGC) utilisée pour représenter les géométries spatiales sous forme de texte. De nombreux systèmes géospatiaux prennent en charge le format WKT, comme Azure SQL et Azure PostgreSQL à l’aide du plug-in PostGIS. Comme la plupart des normes OGC, les coordonnées sont formatées en « longitude latitude » pour s’aligner sur la convention « x y ». À titre d’exemple, un point de longitude -110 et de latitude 45 peut être écrit POINT(-110 45) à l’aide du format WKT.

Le format Well-known text peut être lu à l’aide de la fonction atlas.io.ogc.WKT.read et écrit à l’aide de la fonction atlas.io.ogc.WKT.write.

Exemples de lecture et d’écriture de Well-Known Text (WKT)

L’exempleRead Well Known Text montre comment lire la chaîne Well-known text POINT(-122.34009 47.60995) et l’afficher sur la carte à l’aide d’une couche de bulles. Pour obtenir le code source de cet exemple, consultez Lire le code source du Well-known text.

L’exemple Lire et écrire du Well Known Text montre comment lire et écrire des chaînes WKT (Well Known Text) en tant que GeoJSON. Pour obtenir le code source de cet exemple, consultez Lire et écrire du code source au format Well-known text.

Lire et écrire un fichier GML

GML est une spécification de fichier XML spatial qui est souvent utilisée comme extension d’autres spécifications XML. Les données GeoJSON peuvent être écrites au format XML avec des balises GML à l’aide de la fonction atlas.io.core.GmlWriter.write. Le fichier XML qui contient GML peut être lu à l’aide de la fonction atlas.io.core.GmlReader.read. La fonction de lecture a deux options :

L’option isAxisOrderLonLat : l’ordre des coordonnées « latitude, longitude » ou « longitude, latitude » peut varier selon les jeux de données et n’est pas toujours bien défini. Par défaut, le lecteur GML lit les données de coordonnées au format « latitude, longitude », mais si vous attribuez la valeur true à cette option, la valeur est « longitude, latitude ».
L’option propertyTypes : cette option est une table de choix de valeurs de clé où la clé correspond au nom d’une propriété dans le jeu de données. La valeur est le type d’objet vers lequel caster la valeur lors de l’analyse. Les valeurs de type prises en charge sont les suivantes : string, number, boolean et date. Si une propriété ne figure pas dans la table de choix ou si le type n’est pas défini, la propriété est analysée en tant que chaîne.

La fonction atlas.io.read utilise la fonction atlas.io.core.GmlReader.read par défaut lorsqu’elle détecte que les données d’entrée sont au format XML, mais que les données ne correspondent pas à l’un des autres formats XML spatiaux pris en charge.

Le fonction GmlReader analyse les coordonnées qui ont l’un des SRID suivants :

EPSG: 4326 (recommandé)
EPSG:4269, EPSG:4283, EPSG:4258, EPSG:4308, EPSG:4230, EPSG:4272, EPSG:4271, EPSG:4267, EPSG:4608, EPSG:4674 éventuellement avec une petite marge d’erreur.
EPSG:3857, EPSG:102100, EPSG:3785, EPSG:900913, EPSG:102113, EPSG:41001, EPSG:54004