Si vous avez besoin de plus de flexibilité pour importer des images dans Google Earth Engine (EE) que celle fournie par l'interface utilisateur de l'éditeur de code ou la commande upload
de l'outil de ligne de commande "earthengine", vous pouvez décrire une importation d'image à l'aide d'un fichier JSON appelé "fichier manifeste" et à l'aide de la commande upload image --manifest
de l'outil de ligne de commande.
Pour voir un exemple complet, consultez ce notebook Colab, qui montre comment importer des tuiles d'image en tant qu'élément unique à l'aide d'un fichier manifeste.
Configuration unique
- Les importations de fichiers manifestes ne fonctionnent qu'avec les fichiers situés dans Google Cloud Storage. Pour commencer à utiliser Google Cloud Storage, créez un projet Google Cloud, si vous n'en avez pas déjà un. Notez que la configuration nécessite de spécifier une carte de crédit pour la facturation. EE ne facture rien à ce stade, mais le transfert de fichiers vers Google Cloud Storage avant de les importer sur EE entraîne de faibles frais. Pour les tailles de données d'importation typiques (dizaines ou centaines de gigaoctets), le coût est assez faible.
- Dans votre projet, activez l'API Cloud Storage et créez un bucket.
- Installez le client Python Earth Engine. Il inclut l'outil de ligne de commande
earthengine
, que nous utiliserons pour importer des données. - Pour les importations automatisées, vous pouvez utiliser un compte de service Google Cloud associé à votre projet. Vous n'avez pas besoin d'un compte de service pour les tests, mais lorsque vous avez le temps, veuillez commencer à vous familiariser avec leur utilisation.
L'importation de très grands fichiers sources (100 Go ou plus) peut être plus rapide s'ils sont divisés en plusieurs tuiles.
ID et noms des éléments
Pour les éléments appartenant à un projet Cloud, utilisez cette convention pour les noms d'éléments : projects/some-project-id/assets/some-asset-id
.
En savoir plus sur les noms d'éléments pour les anciens projets et les éléments appartenant à l'utilisateur
Pour les anciens projets, le nom de l'élément dans le fichier manifeste doit être légèrement différent de l'ID de l'élément visible ailleurs dans Earth Engine. Pour importer des composants dont les ID commencent par users/some_user
ou projects/some_project
, la chaîne projects/earthengine-legacy/assets/
doit être ajoutée au nom de l'élément dans le fichier manifeste. Par exemple, l'ID d'élément EE users/username/my_geotiff
doit être importé avec le nom projects/earthengine-legacy/assets/users/username/my_geotiff
.
Oui, cela signifie que les ID tels que projects/some_projects/some_asset
sont convertis en noms dans lesquels projects
est mentionné deux fois : projects/earthengine-legacy/assets/projects/some_projects/some_asset
.
Cette situation est déroutante, mais nécessaire pour se conformer aux normes de l'API Google Cloud.
Utiliser des fichiers manifestes
Un fichier manifeste de base est affiché dans le bloc de code suivant. Il importe un fichier nommé small.tif
à partir d'un bucket Google Cloud Storage nommé gs://earthengine-test
.
{ "name": "projects/some-project-id/assets/some-asset-id", "tilesets": [ { "sources": [ { "uris": [ "gs://earthengine-test/small.tif" ] } ] } ] }
Pour l'utiliser, enregistrez-le dans un fichier nommé manifest.json
, puis exécutez:
earthengine upload image --manifest /path/to/manifest.json
(Le fichier gs://earthengine-test/small.tif
existe et est lisible publiquement. Vous pouvez l'utiliser pour les tests.)
Ensembles de tuiles
La structure de fichier manifeste quelque peu complexe du format JSON est nécessaire pour offrir suffisamment de flexibilité pour résoudre un problème d'importation courant: comment décrire toutes les manières possibles de combiner les pixels de plusieurs fichiers sources en un seul élément. Plus précisément, il existe deux méthodes indépendantes pour regrouper des fichiers:
- Mosaïques. Parfois, plusieurs fichiers représentent plusieurs tuiles (par exemple, chaque tuile est un carré de 1 x 1 degré). Ces fichiers doivent être mosaïques (fusionnés) dans la même bande d'un élément EE.
- Bracelets séparés. Parfois, plusieurs fichiers représentent plusieurs bandes. Ces fichiers doivent être empilés en bandes dans un élément EE.
(Il est possible que vous deviez utiliser les deux méthodes en même temps, mais cela est rare.)
Pour décrire ces options, les fichiers manifestes introduisent la notion de mosaïque. Un seul ensemble de tuiles correspond à une seule source GDAL. Par conséquent, toutes les sources d'un même ensemble de tuiles doivent avoir la même structure GDAL (nombre et type de bandes, projection, transformation, valeur manquante). Étant donné qu'une source GDAL peut comporter plusieurs bandes, un ensemble de tuiles peut contenir des données pour plusieurs bandes EE.
Pour l'ingestion de mosaïque, le fichier manifeste se présente comme suit:
{ "name": "projects/some-project-id/assets/some-asset-id", "tilesets": [ { "sources": [ { "uris": [ "gs://bucket/N30W22.tif" ] }, { "uris": [ "gs://bucket/N31W22.tif" ] } ] } ] }
Pour les bandes distinctes, le fichier manifeste se présente comme suit (vous devez également ajouter une section bands
, comme expliqué ci-dessous):
{ "name": "projects/some-project-id/assets/some-asset-id", "bands": ..., "tilesets": [ { "id": "tileset_for_band1", "sources": [ { "uris": [ "gs://bucket/band1.tif" ] } ] }, { "id": "tileset_for_band2", "sources": [ { "uris": [ "gs://bucket/band2.tif" ] } ] } ] }
Notez que dans le cas de bandes distinctes, nous devons attribuer un ID de carte différent à chaque carte pour plus de clarté. L'ID de la carte de tuiles peut être une chaîne arbitraire. Ces chaînes ne sont pas conservées dans l'élément importé. Les ID de jeu de tuiles ne sont utilisés que lors de l'ingestion pour distinguer les jeux de tuiles empilés les uns des autres.
Bracelets
Le deuxième concept important consiste à faire correspondre les fichiers sources aux bandes d'éléments EE.
Pour ce faire, utilisez la section bands
du fichier manifeste.
La section bands
peut être omise, auquel cas les bandes sont créées d'abord à partir des fichiers du premier ensemble de tuiles, puis du deuxième ensemble de tuiles, et ainsi de suite.
Par défaut, les bandes sont nommées "b1", "b2", etc. Pour remplacer les noms de bandes par défaut, incluez une section "bands" à la fin, comme suit:
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "sources": [ { "uris": [ "gs://bucket/rgb.tif" ] } ] } ], "bands": [ { "id": "R", "tilesetBandIndex": 0 }, { "id": "G", "tilesetBandIndex": 1 }, { "id": "B", "tilesetBandIndex": 2 } ] }
Le nombre de bandes EE doit être identique au nombre total de bandes de tous les ensembles de tuiles.
Si vous ne souhaitez pas ingérer toutes les bandes d'un fichier, vous pouvez utiliser le champ tilesetBandIndex
pour indiquer celles qui doivent être ingérées.
La première bande a un tilesetBandIndex de 0.
Exemple :
Supposons que le fichier source comporte quatre bandes: "tmin", "tmin_error", "tmax" et "tmax_error". Nous ne souhaitons ingérer que "tmin" et "tmax". Les sections de fichier manifeste pertinentes se présentent comme suit:
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "id": "temperature", "sources": [ { "uris": [ "gs://bucket/temperature.tif" ] } ] } ], "bands": [ { "id": "tmin", "tilesetBandIndex": 0, "tilesetId": "temperature" }, { "id": "tmax", "tilesetBandIndex": 2, "tilesetId": "temperature" } ] }
Masquer les bandes
Le masquage de bande est contrôlé par le composant maskBands
du fichier manifeste.
Trois configurations de masque sont possibles (mais la bande de masque est toujours considérée comme la dernière bande d'un fichier donné).
- Masque pour toutes les bandes de données du même fichier.
- Masque pour toutes les bandes de données provenant de tous les autres fichiers.
- Masque pour certaines bandes de données.
1. Le cas le plus courant est celui d'un seul GeoTIFF dont la dernière bande est utilisée comme masque pour les autres bandes. Cette option n'est disponible que pour les fichiers GeoTIFF de type octet. Utilisez le fichier manifeste suivant:
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "id": "data_tileset", "sources": [ { "uris": [ "gs://bucket/data_file.tif" ] } ] } ], "bands": [ { "id": "data_band", "tilesetId": "data_tileset" }, { "id": "qa_band", "tilesetId": "data_tileset" } ], "maskBands": [ { "tilesetId": "data_tileset" } ] }
2. Pour utiliser un GeoTIFF de masque comme masque pour toutes les bandes d'un autre GeoTIFF, utilisez le fichier manifeste suivant:
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "id": "data_tileset", "sources": [ { "uris": [ "gs://bucket/data_file.tif" ] } ] }, { "id": "mask_tileset", "sources": [ { "uris": [ "gs://bucket/mask_file.tif" ] } ] } ], "bands": [ { "id": "data_band", "tilesetId": "data_tileset" }, { "id": "qa_band", "tilesetId": "data_tileset" } ], "maskBands": [ { "tilesetId": "mask_tileset" } ] }
3. Pour utiliser un GeoTIFF comme masque pour une bande spécifique dans un autre fichier, utilisez le fichier manifeste suivant (la différence avec le cas précédent est que le champ bandIds
dans maskBands
est défini):
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "id": "data_tileset", "sources": [ { "uris": [ "gs://bucket/data_file.tif" ] } ] }, { "id": "mask_tileset", "sources": [ { "uris": [ "gs://bucket/mask_file.tif" ] } ] } ], "bands": [ { "id": "data_band", "tilesetId": "data_tileset" }, { "id": "qa_band", "tilesetId": "data_tileset" } ], "maskBands": [ { "tilesetId": "mask_tileset", "bandIds": ["data_band"] } ] }
Dans le dernier exemple, nous utilisons deux bandes de la carte de tuiles data_tileset
, mais nous n'appliquons un masque qu'à l'une des bandes (data_band
), comme indiqué par le champ bandIds
du seul objet de liste maskBands
fourni.
Notez que seule la dernière bande du jeu de tuiles mentionné dans maskBands
est utilisée comme bande de masque.
Règlement sur la pyramide
Lorsque Earth Engine construit des pyramides d'images lors de l'ingestion, il doit réduire à plusieurs reprises des grilles de 2 x 2 pixels en un seul pixel, en transformant la valeur du pixel d'une certaine manière. Par défaut, les valeurs de pixel sont calculées en moyenne, ce qui est la bonne chose à faire dans la plupart des cas lorsque la bande raster représente des données plus ou moins continues. Toutefois, dans deux cas, s'appuyer sur la valeur par défaut produit des résultats incorrects. Dans ce cas, le champ pyramidingPolicy
de la définition de la bande doit être défini (s'il n'est pas défini, sa valeur est supposée être "MOYENNE" par défaut).
Pour la classification des images raster (par exemple, pour la classification de l'occupation des sols), la méthode la plus logique pour pyramider les pixels consiste à prendre la majorité des quatre valeurs pour produire la suivante. Pour ce faire, utilisez la règle de pyramidage "MODE" :
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "sources": [ { "uris": [ "gs://bucket/landcover.tif" ] } ] } ], "bands": [ { "id": "landcover", "pyramidingPolicy": "MODE" } ] }
Pour les bandes raster où ni "MOYENNE" ni "MODE" n'ont de sens (par exemple, les pixels empaquetés en bits), la règle de pyramidage "ÉCHANTILLON" doit être utilisée. "SAMPLE" prend toujours la valeur du pixel en haut à gauche de chaque grille de 2 x 2. L'exemple suivant attribue la règle de pyramidage"MOYENNE" à une bande représentant une variable continue ("NDVI ") et"ÉCHANTILLON" à la bande "QA" des données.
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "sources": [ { "uris": [ "gs://bucket/ndvi.tif" ] } ] } ], "bands": [ { "id": "NDVI", "tilesetBandIndex": 0, "pyramidingPolicy": "MEAN" }, { "id": "QA", "tilesetBandIndex": 1, "pyramidingPolicy": "SAMPLE" } ] }
Heures de début et de fin
Toutes les ressources doivent spécifier une heure de début et de fin pour donner plus de contexte aux données, en particulier si elles sont incluses dans des collections. Ces champs ne sont pas obligatoires, mais nous vous recommandons vivement de les utiliser dans la mesure du possible.
L'heure de début et de fin désigne généralement l'heure de l'observation, et non l'heure à laquelle le fichier source a été créé.
Pour simplifier, l'heure de fin est considérée comme une limite exclusive. Par exemple, pour les composants couvrant exactement une journée, utilisez minuit de deux jours consécutifs (par exemple, 1980-01-31T00:00:00 et 1980-02-01T00:00:00) pour les heures de début et de fin. Si l'élément n'a pas de durée, définissez l'heure de fin sur la même que l'heure de début. Représentez les heures dans les fichiers manifestes sous forme de chaînes ISO 8601. Nous vous recommandons de supposer que l'heure de fin est exclusive (par exemple, minuit du jour suivant pour les composants quotidiens) afin de simplifier les valeurs de date.
Exemple :
{ "name": "projects/some-project-id/assets/some-asset-id", "tilesets": [ { "sources": [ { "uris": [ "gs://bucket/img_20190612.tif" ] } ] } ], "startTime": "1980-01-31T00:00:00Z", "endTime": "1980-02-01T00:00:00Z" }
Référence de la structure du fichier manifeste
La structure JSON suivante inclut tous les champs de fichier manifeste d'importation d'images possibles. Vous trouverez les définitions des champs dans la section Définitions des champs du fichier manifeste suivante.
{ "name": <string>, "tilesets": [ { "dataType": <string>, "id": <string>, "crs": <string>, "sources": [ { "uris": [ <string> ], "affineTransform": { "scaleX": <double>, "shearX": <double>, "translateX": <double>, "shearY": <double>, "scaleY": <double>, "translateY": <double> } } ] } ], "bands": [ { "id": <string>, "tilesetId": <string>, "tilesetBandIndex": <int32>, "missingData": { "values": [<double>] }, "pyramindingPolicy": <string> } ], "maskBands": [ { "tilesetId": <string>, "bandIds": [ <string> ] } ], "footprint": { "points": [ { "x": <double>, "y": <double> } ], "bandId": <string> }, "missingData": { "values": [<double>] }, "pyramidingPolicy": <string>, "uriPrefix": <string>, "startTime": { "seconds": <integer> }, "endTime": { "seconds": <integer> }, "properties": { <unspecified> } }
Définitions des champs du fichier manifeste
nom
string
Nom de l'asset à créer.
name
est au format "projects/*/assets/**" (par exemple, "projects/earthengine-legacy/assets/users/USER/ASSET").
ensembles de tuiles
list
Liste de dictionnaires qui définissent des propriétés pour les ensembles de tuiles.
Pour en savoir plus, consultez les champs d'élément de dictionnaire tilesets
suivants.
tilesets[i].dataType
string
Spécifie le type de données numériques des données. La valeur par défaut est le type que GDAL signale. Dans ce cas, il n'est pas nécessaire de le définir.
Type de données | Valeur |
---|---|
Non spécifié | "DATA_TYPE_UNSPECIFIED" |
Entier signé 8 bits | "INT8" |
Entier non signé de 8 bits | "UINT8" |
Entier signé 16 bits | "INT16" |
Entier non signé 16 bits | "UINT16" |
Entier signé de 32 bits | "INT32" |
Entier non signé de 32 bits | "UINT32" |
Float 32 bits | "FLOAT32" |
Format à virgule flottante double précision (64 bits) | "FLOAT64" |
tilesets[i].id
string
ID de la carte de tuiles. Doit être unique parmi les ensembles de tuiles spécifiés dans le fichier manifeste d'éléments. Cet ID est supprimé lors de l'étape de traitement. Il n'est utilisé que pour associer un ensemble de tuiles à une bande. La chaîne vide est un ID valide.
tilesets[i].crs
string
Système de référence de coordonnées de la grille de pixels, spécifié sous la forme d'un code standard dans la mesure du possible (par exemple, code EPSG) et au format WKT dans le cas contraire.
tilesets[i].sources
list
Liste de dictionnaires définissant les propriétés d'un fichier image et de ses fichiers associés. Pour en savoir plus, consultez les champs d'élément de dictionnaire sources
suivants.
tilesets[i].sources[j].uris
list
Liste des URI des données à ingérer. Seuls les URI Google Cloud Storage sont acceptés. Chaque URI doit être spécifié au format suivant : gs://bucket-id/object-id
.
L'objet principal doit être le premier élément de la liste, et les sidecars doivent être listés ensuite. Chaque URI est précédé de ImageManifest.uriPrefix
, le cas échéant.
tilesets[i].sources[j].affineTransform
dictionary
Une transformation affine facultative. Ne doit être spécifié que si les données de uris
(y compris les sidecars) ne sont pas suffisantes pour placer les pixels.
Fourni sous forme de dictionnaire avec les clés suivantes : "scaleX", "shearX", "translateX", "shearY", "scaleY" et "translateY".
Pour en savoir plus, consultez
cette documentation de référence.
Exemples de clés et de valeurs:
{ "scaleX": 0.1, "shearX": 0.0, "translateX": -180.0, "shearY": 0.0, "scaleY": -0.1, "translateY": 90.0 }
bracelets
list
Liste de dictionnaires définissant les propriétés d'une seule bande provenant d'un ensemble de tuiles.
Notez que l'ordre des canaux de l'asset est le même que celui de bands
.
Pour en savoir plus, consultez les champs d'élément de dictionnaire bands
suivants.
bands[i].id
string
ID (nom) de la bande.
bands[i].tilesetId
string
ID de la carte de tuiles correspondant à la bande.
bands[i].tilesetBandIndex
int32
Index de bande basé sur zéro du jeu de tuiles correspondant à la bande.
bands[i].missingData.values
list
Liste de valeurs (type double) qui ne représentent aucune donnée dans la bande.
bands[i].pyramidingPolicy
string
Règlement sur la pyramide. Pour en savoir plus, cliquez ici. Plusieurs options sont disponibles :
- "MOYENNE" (par défaut)
- "MODE"
- "SAMPLE"
maskBands
list
Liste de dictionnaires définissant les propriétés d'une seule bande de masque provenant d'un ensemble de tuiles.
Vous ne pouvez fournir qu'une seule bande de masque.
Pour en savoir plus, consultez les champs d'élément de dictionnaire maskBands
suivants.
maskBands[i].tilesetId
string
ID de la carte de tuiles correspondant à la bande de masque. La dernière bande de la carte de tuiles est toujours utilisée comme bande de masque.
maskBands[i].bandIds
list of strings
Liste des ID des bandes auxquelles la bande de masquage s'applique. Si elle est vide, la bande de masque est appliquée à toutes les bandes du composant. Chaque bande ne peut avoir qu'une seule bande de masque correspondante.
empreinte
dictionary
Dictionnaire définissant les propriétés de l'empreinte de tous les pixels valides d'une image.
Si ce champ est vide, l'empreinte par défaut correspond à l'image entière. Pour en savoir plus, consultez les champs d'élément de dictionnaire footprint
suivants.
footprint.points
list
Liste de points définissant l'empreinte de tous les pixels valides d'une image. Un point est défini par un dictionnaire dont les clés "x" et "y" ont des valeurs flottantes. Une liste de points doit décrire un anneau qui forme l'extérieur d'un polygone simple qui doit contenir les centres de tous les pixels valides de l'image. Il doit s'agir d'un anneau linéaire: le dernier point doit être égal au premier. Les coordonnées sont dans la projection de la bande spécifiée par bandId
.
Remarque: Utilisez des coordonnées non entières telles que le centre de chaque pixel, car footprint
est considéré comme incluant un pixel si le pixel (un rectangle de 1 x 1) intersecte l'empreinte. Pour éviter de sélectionner accidentellement des pixels voisins, n'utilisez pas de coordonnées à valeurs entières, car ce sont les limites entre les pixels. Dessiner l'empreinte le long des centres de pixel empêche d'inclure des pixels non intentionnels, ce qui peut entraîner des erreurs lorsque les pixels prévus sont adjacents à une limite de carte, comme l'antiméridien ou un pôle.
Par exemple, pour une image de 2 x 2 avec les quatre pixels valides, voici un anneau possible:
[ { "x": 0.5, "y": 0.5 }, { "x": 0.5, "y": 1.5 }, { "x": 1.5, "y": 1.5 }, { "x": 1.5, "y": 0.5 }, { "x": 0.5, "y": 0.5 } ]
footprint.bandId
string
ID de la bande dont le système de coordonnées de référence définit les coordonnées de l'empreinte. Si ce champ est vide, la première bande est utilisée.
missingData.values
list
Liste de valeurs (type double) qui ne représentent aucune donnée dans toutes les bandes de l'image. S'applique à toutes les bandes qui ne spécifient pas leur propre missingData
.
pyramidingPolicy
string
Règlement sur la pyramide. Si ce paramètre n'est pas spécifié, la règle "MOYENNE" est appliquée par défaut. S'applique à toutes les bandes qui ne spécifient pas la leur. Pour en savoir plus, cliquez ici. Plusieurs options sont disponibles :
- "MOYENNE" (par défaut)
- "MODE"
- "SAMPLE"
uriPrefix
string
Préfixe facultatif ajouté au début de tous les uris
définis dans le fichier manifeste.
startTime
integer
Code temporel associé à l'élément, le cas échéant. Il s'agit généralement de l'heure à laquelle une image satellite a été prise. Pour les composants qui correspondent à un intervalle de temps, comme les valeurs moyennes sur un mois ou une année, ce code temporel correspond au début de cet intervalle. Spécifié en secondes et (facultatif) en nanosecondes depuis l'epoch (1970-01-01). Supposé être dans le fuseau horaire UTC.
endTime
integer
Pour les composants qui correspondent à un intervalle de temps, comme les valeurs moyennes sur un mois ou une année, cet horodatage correspond à la fin de cet intervalle (exclusif). Spécifié en secondes et (facultatif) en nanosecondes depuis l'epoch (1970-01-01). Supposé être dans le fuseau horaire UTC.
du bucket
dictionary
Dictionnaire plat arbitraire de paires clé-valeur. Les clés doivent être des chaînes, et les valeurs peuvent être des nombres ou des chaînes. Les valeurs de liste ne sont pas encore acceptées pour les composants importés par l'utilisateur.
Limites
Taille du fichier manifeste JSON
La taille maximale du fichier manifeste JSON est de 10 Mo. Si vous avez de nombreux fichiers à importer, envisagez de réduire le nombre de caractères nécessaires pour décrire l'ensemble de données. Par exemple, utilisez le champ uriPrefix
pour ne pas avoir à fournir le chemin d'accès au bucket Google Cloud pour chaque URI de la liste uris
. Si une réduction supplémentaire de la taille est nécessaire, essayez de raccourcir les noms de fichiers.
Format de fichier image
Chaque fichier image doit être au format TIFF. Si le système de coordonnées projeté n'est pas spécifié dans le fichier manifeste, le fichier doit être un GeoTIFF avec un système de coordonnées projeté intégré.
Les fichiers TIFF peuvent être compressés avec DEFLATE, JPEG-XL/JXL, LERC, LERC_DEFLATE, LERC_ZSTD, LZMA, LZW, WEBP ou ZSTD.
Recommandations pour une expérience d'importation optimale pour les fichiers volumineux:
- Meilleur choix:ZSTD offre un bon équilibre entre vitesse et compression.
- À éviter:LZMA peut être très lent malgré une bonne compression.
- Fichiers non compressés:les fichiers sont plus volumineux et les temps d'importation sont plus longs.
- Compression avec perte (par exemple, JPEG) : peut modifier les valeurs des pixels. Utilisez une compression sans perte (par exemple, DEFLATE, LZMA, LZW, ZSTD) sauf si vous comprenez l'impact potentiel sur vos données.