Si vous avez besoin de plus de flexibilité pour importer des images dans Google Earth Engine (EE) que 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é "manifeste" et 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'images 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 dans EE entraîne un faible coût. Pour les tailles de données d'importation types (dizaines ou centaines de gigaoctets), le coût sera 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 dès que vous aurez un moment, familiarisez-vous avec leur utilisation.
Les fichiers sources très volumineux (100 Go ou plus) peuvent être importés plus rapidement s'ils sont divisés en plusieurs tuiles.
ID et noms des éléments
Pour les éléments appartenant à un projet Cloud, utilisez la convention suivante pour les noms d'éléments : projects/some-project-id/assets/some-asset-id.
En savoir plus sur les noms des é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 d'élément visible ailleurs dans Earth Engine. Pour importer des éléments dont l'ID d'élément commence par users/some_user ou projects/some_project, le nom de l'élément dans le fichier manifeste doit être précédé de la chaîne projects/earthengine-legacy/assets/. Par exemple, l'ID d'élément EE users/username/my_geotiff doit être importé sous 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 où projects est mentionné deux fois : projects/earthengine-legacy/assets/projects/some_projects/some_asset.
Cela peut prêter à confusion, mais est nécessaire pour respecter les normes de l'API Google Cloud.
Utiliser des fichiers manifestes
Un fichier manifeste de base est présenté 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 et 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 effectuer des tests.)
Ensembles de tuiles
La structure de fichier manifeste JSON, quelque peu complexe, est nécessaire pour offrir une flexibilité suffisante afin de relever un défi d'importation courant : comment décrire toutes les manières possibles de combiner des pixels de plusieurs fichiers sources en un seul élément. Plus précisément, il existe deux façons indépendantes de regrouper des fichiers :
- Mosaïques. Parfois, plusieurs fichiers représentent plusieurs tuiles (par exemple, chaque tuile est un carré de 1x1 degré). Ces fichiers doivent être mosaïqués (fusionnés) dans la même bande d'un élément EE.
- Bandes séparées. Parfois, plusieurs fichiers représentent plusieurs bandes. Ces fichiers doivent être empilés sous forme de bandes dans un élément EE.
(Il peut arriver que les deux méthodes doivent être utilisées en même temps, mais cela est rare.)
Pour décrire ces options, les fichiers manifestes introduisent la notion de tileset. Un ensemble de tuiles correspond à une seule source GDAL. Pour cette raison, 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ïques, 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 séparées, 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 à chaque ensemble de tuiles un ID d'ensemble de tuiles différent pour plus de clarté. L'ID de l'ensemble de tuiles peut être une chaîne arbitraire. Ces chaînes ne sont pas conservées dans l'élément importé. Les ID d'ensemble de tuiles ne sont utilisés que lors de l'ingestion pour distinguer les ensembles de tuiles empilés les uns des autres.
Bandes
Le deuxième concept important est la mise en correspondance des fichiers sources avec les bandes d'éléments EE.
Pour ce faire, utilisez la section bands du fichier manifeste.
La section bands peut être omise. Dans ce cas, les bandes sont d'abord créées à partir des fichiers du premier ensemble de tuiles, puis du suivant, et ainsi de suite.
Par défaut, les bandes sont nommées "b1", "b2", etc. Pour remplacer les noms de bande 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 dans 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 les bandes GDAL à ingérer.
La première bande a un tilesetBandIndex de 0.
Exemple :
Supposons que le fichier source comporte quatre bandes : "tmin", "tmin_error", "tmax", "tmax_error". Nous ne voulons ingérer que "tmin" et "tmax". Les sections de fichier manifeste concernées 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"
}
]
}Bandes de masquage
Le masquage des bandes 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 dans le 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 un seul GeoTIFF dont la dernière bande est utilisée comme masque pour les autres bandes. Cela ne fonctionne que pour les GeoTIFF de type Byte. 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 travaillons avec deux bandes de l'ensemble 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 de l'ensemble de tuiles mentionné dans maskBands est utilisée comme bande de masque.
Règle de pyramide
Lorsque Earth Engine crée 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 manière ou d'une autre. Par défaut, les valeurs des pixels sont moyennées, ce qui est la bonne chose à faire dans la plupart des cas lorsque la bande matricielle représente des données plus ou moins continues. Toutefois, dans deux situations, l'utilisation de 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 "MEAN" par défaut).
Pour la classification des images matricielles (par exemple, pour la classification de l'occupation du sol), la méthode la plus logique pour créer une pyramide de pixels consiste à prendre la majorité des quatre valeurs pour produire la suivante. Pour ce faire, utilisez la règle de pyramide "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 matricielles où ni "MEAN" ni "MODE" n'ont de sens (par exemple, les pixels compressés), la règle de pyramide "SAMPLE" doit être utilisée. "SAMPLE" prend toujours la valeur du pixel supérieur gauche de chaque grille 2x2. L'exemple suivant attribue la règle de pyramide"MEAN" à une bande représentant une variable continue ("NDVI ") et"SAMPLE" à 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
Tous les éléments doivent spécifier une heure de début et de fin pour fournir plus de contexte aux données, en particulier s'ils sont inclus 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 l'heure de fin correspondent généralement à l'heure de l'observation, et non à l'heure de production du fichier source.
Par souci de simplicité, l'heure de fin est traitée comme une limite exclusive. Par exemple, pour les éléments couvrant exactement un jour, utilisez minuit de deux jours consécutifs (par exemple, 1980-01-31T00:00:00 et 1980-02-01T00:00:00) pour l'heure de début et de fin. Si l'asset n'a pas de durée, définissez l'heure de fin sur la même valeur 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 considérer que l'heure de fin est exclusive (par exemple, minuit le jour suivant pour les assets 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"
}Documentation de référence sur la structure du fichier manifeste
La structure JSON suivante inclut tous les champs possibles du fichier manifeste d'importation d'images. Vous trouverez les définitions des champs dans la section Définitions des champs du fichier manifeste ci-dessous.
{ "name": <string>, "tilesets": [ { "dataType": <string>, "id": <string>, "crs": <string>, "sources": [ { "uris": [ <stringn>> ], "affineTransform": { "scaleX": <double>, "shearX": <double>, "translateX": <double>, "shearY": <double>, "scaleY": <double>, "translateY": <double> } } ] } ], "bands": [ { "id": <string>, "tilesetId": <string>, "tilesetBandIndex": <int32>, "missingData": { "values": [<doublen>>] }, "pyramindingPolicy": <string> } ], "maskBands": [ { "tilesetId": <string>, "bandIds": [ <stringn>> ] } ], "footprint": { "points": [ { "x": <double>, "y": <doublen>> } ], "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").
tilesets
list
Liste de dictionnaires définissant les propriétés des 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 signalé par GDAL, auquel cas il n'est pas nécessaire de le définir.
| Type de données | Valeur |
|---|---|
| Non spécifié | "DATA_TYPE_UNSPECIFIED" |
| Entier signé de 8 bits | "INT8" |
| Entier non signé de 8 bits | "UINT8" |
| Entier signé de 16 bits | "INT16" |
| Entier non signé de 16 bits | "UINT16" |
| Entier signé 32 bits | "INT32" |
| Entier non signé de 32 bits | "UINT32" |
| Valeur à virgule flottante 32 bits | "FLOAT32" |
| Float 64 bits | "FLOAT64" |
tilesets[i].id
string
ID du jeu de tuiles. Doit être unique parmi les ensembles de tuiles spécifiés dans le fichier manifeste de l'élément. 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 forme de 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 side-car. 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 side-cars doivent être listés ensuite. Chaque URI est précédé de ImageManifest.uriPrefix s'il est défini.
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 side-cars) ne sont pas suffisantes pour placer les pixels.
Fourni sous forme de dictionnaire avec les clés suivantes : "scaleX", "shearX", "translateX", "shearY", "scaleY", "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 bandes 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 l'ensemble de tuiles correspondant à la bande.
bands[i].tilesetBandIndex
int32
Index de bande basé sur zéro de l'ensemble 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
La règle de pyramide. Pour en savoir plus, consultez ce lien. Plusieurs options sont disponibles :
- "MEAN" (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 l'ensemble de tuiles correspondant à la bande de masque. La dernière bande de l'ensemble 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 masque s'applique. Si ce champ est vide, la bande de masque est appliquée à toutes les bandes de l'élément. 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 est 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 avec des clés "x" et "y" ayant des valeurs flottantes. Une liste de points doit décrire un anneau qui forme l'extérieur d'un polygone simple devant 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 identique 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 1x1) croise l'empreinte. Pour éviter de sélectionner accidentellement des pixels voisins, n'utilisez pas de coordonnées à valeur entière, car elles correspondent aux limites entre les pixels. Le fait de dessiner l'empreinte le long des centres des pixels évite d'inclure des pixels non souhaités, ce qui peut provoquer des erreurs lorsque les pixels souhaités sont adjacents à une limite de la carte, comme l'antiméridien ou un pôle.
Par exemple, pour une image 2x2 avec 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 CRS 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
La règle de pyramide. Si elle n'est pas spécifiée, la règle "MEAN" est appliquée par défaut. S'applique à toutes les bandes qui ne spécifient pas la leur. Pour en savoir plus, consultez ce lien. Plusieurs options sont disponibles :
- "MEAN" (par défaut)
- "MODE"
- "SAMPLE"
uriPrefix
string
Préfixe facultatif ajouté à tous les uris définis dans le fichier manifeste.
startTime
integer
Code temporel associé à l'asset, le cas échéant. Cela correspond généralement à l'heure à laquelle une image satellite a été prise. Pour les éléments correspondant à un intervalle de temps, tels que 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 (éventuellement) en nanosecondes depuis l'epoch (1970-01-01). Supposé être dans le fuseau horaire UTC.
endTime
integer
Pour les éléments qui correspondent à un intervalle de temps, comme les valeurs moyennes sur un mois ou une année, ce code temporel correspond à la fin de cet intervalle (exclusif). Spécifié en secondes et (éventuellement) en nanosecondes depuis l'epoch (1970-01-01). Supposé être dans le fuseau horaire UTC.
propriétés
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 éléments importés par l'utilisateur.
Limites
Taille du fichier manifeste JSON
La taille du fichier manifeste JSON ne doit pas dépasser 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 vous devez encore réduire la taille, essayez de raccourcir les noms de fichiers.
Format de fichier image
Chaque fichier image doit être une image TIFF. Si le CRS n'est pas spécifié dans le fichier manifeste, le fichier doit être un GeoTIFF avec un CRS 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 des 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 plus longs.
- Compression avec perte (par exemple, JPEG) : peut modifier les valeurs des pixels. Utilisez la compression sans perte (par exemple, DEFLATE, LZMA, LZW, ZSTD), sauf si vous comprenez l'impact potentiel sur vos données.