Outil de ligne de commande

L'outil earthengine est un utilitaire qui vous permet de gérer les éléments et les tâches Earth Engine à partir de la ligne de commande. Il est installé automatiquement lorsque vous installez l'API Python. Pour vérifier si l'outil est installé et fonctionne correctement, saisissez la commande suivante sur une ligne de commande :

    earthengine

Si l'outil est correctement installé, il affiche un bref résumé des commandes disponibles. Pour obtenir de l'aide sur une commande spécifique, utilisez :

    earthengine command -h

Lorsque vous installez l'API Python pour la première fois, vous devez vous connecter à l'aide de la commande authenticate décrite ci-dessous. Les sections suivantes décrivent plus en détail les commandes disponibles.

Identifiants du compte de service

Pour utiliser la CLI avec les identifiants d'un compte de service, utilisez l'option service_account_file pour pointer vers un fichier JSON contenant la clé du compte de service.

    earthengine --service_account_file=service_account_creds.json

Utilisation dans Colab

L'outil de ligne de commande Earth Engine est préinstallé et prêt à être utilisé dans Google Colab.

Authentification

Authentifiez-vous pour chaque nouvelle session Colab ou si la machine virtuelle expire en raison d'une inactivité (les identifiants ne sont pas enregistrés d'une session à l'autre).

Importez la bibliothèque cliente Python et appelez ee.Authenticate() pour déclencher le flux d'authentification. Suivez les instructions pour terminer l'authentification. La valeur par défaut de auth_mode dans Colab est colab. Consultez le guide d'authentification pour connaître les autres options.

import ee
ee.Authenticate()

Exécution des commandes

Pour exécuter des utilitaires de ligne de commande, comme la CLI Earth Engine, vous devez faire précéder les appels de commande d'un point d'exclamation.

!earthengine -h

Définir un projet Cloud

Utilisez l'option --project pour définir un projet Cloud pour chaque commande earthengine.

!earthengine --project my-project <command>

Vous pouvez également définir un projet par défaut à utiliser pour tous les appels earthengine à l'aide de la commande set_project. Le projet sera ajouté à un fichier d'identifiants (~/.config/earthengine/credentials) et utilisé pour les commandes ultérieures, sauf s'il est remplacé par l'option --project. Définissez un projet par défaut pour chaque nouvelle session Colab ou si la machine virtuelle expire en raison d'une inactivité (les identifiants ne sont pas enregistrés d'une session à l'autre).

!earthengine set_project my-project

Document de référence sur les commandes

authenticate

Authentifie l'outil de ligne de commande et la bibliothèque cliente Python auprès d'Earth Engine. Exemple :

    earthengine authenticate

Earth Engine utilise le protocole OAuth 2.0 pour authentifier les clients. La commande "earthengine authenticate" vous guidera tout au long du processus d'authentification à l'aide de votre navigateur Web.

Vous devrez installer gcloud si vous utilisez le mode d'authentification gcloud par défaut. Découvrez les autres modes d'authentification disponibles via le paramètre auth_mode dans le guide d'authentification.

acl

Imprime ou met à jour la liste de contrôle d'accès (LCA) d'un élément Earth Engine. La LCA contrôle qui peut lire ou écrire dans un élément. Exemples :

    earthengine acl get projects/my-project/assets/asset_id
    earthengine acl set public projects/my-project/assets/asset_id
    earthengine acl ch -u username@gmail.com:R projects/my-project/assets/asset_id

La sous-commande get affiche une description JSON de la LCA. La sous-commande set définit une LCA fournie dans un fichier au même format JSON. Vous pouvez copier une LCA d'un élément vers d'autres en enregistrant le résultat de get et en le fournissant à set.

La sous-commande "set" accepte également deux noms de LCA spéciaux :

  • private : supprime les autorisations de tous les utilisateurs, à l'exception du propriétaire.
  • public : accorde l'autorisation de lecture à tous les utilisateurs.

La sous-commande ch vous permet d'apporter des modifications individuelles à une LCA. Pour accorder l'autorisation de lecture, spécifiez -u username@gmail.com:R. Pour accorder l'autorisation d'écriture, spécifiez -u username@gmail.com:W. Pour supprimer les autorisations d'un utilisateur, spécifiez -d username@gmail.com. L'identifiant utilisateur spécial AllUsers peut être utilisé pour accorder ou révoquer l'autorisation de lecture à tous les utilisateurs. (Notez que la révocation des autorisations AllUsers ne révoque pas les autorisations supplémentaires que vous avez pu accorder à des utilisateurs individuels.)

asset

Imprime ou met à jour les métadonnées associées à un élément Earth Engine. Exemples :

    earthengine asset info projects/my-project/assets/asset_id
    earthengine asset set -p name=value projects/my-project/assets/asset_id
    earthengine asset setbands projects/my-project/assets/asset_id band1 band2

La sous-commande info affiche des informations détaillées sur l'élément, y compris ses métadonnées, au format JSON. La sous-commande set définit des propriétés de métadonnées individuelles sur un élément. La sous-commande setbands met à jour les noms de bande d'un élément.

Les valeurs des propriétés de métadonnées que vous définissez peuvent être des nombres ou des chaînes. Lorsque vous définissez des noms de propriété à l'aide de l'option --property ou -p, séparez le nom et la valeur de la propriété par un signe égal. Le type de données est détecté automatiquement, ou vous pouvez le spécifier explicitement en ajoutant le préfixe (string), (number) ou (date) au nom de la propriété. Par exemple, cela définit une propriété de valeur de chaîne avec la valeur "42" :

    earthengine asset set -p '(string)name=42' projects/my-project/assets/asset_id

(Les guillemets dans cet exemple empêchent l'interface système d'interpréter les parenthèses. (Elles peuvent être nécessaires ou non, selon votre shell et votre plate-forme.)

Pour créer des propriétés spéciales pour les visualisations de bandes de classification, vous pouvez stocker les listes de valeurs et de couleurs sous forme de chaînes séparées par une virgule. Par exemple, pour définir la palette et les valeurs de classe d'une bande nommée landcover :

    earthengine asset set -p 'landcover_class_palette=ff0000,00ff00,0000ff' projects/my-project/assets/asset_id
    earthengine asset set -p 'landcover_class_values=1,2,3' projects/my-project/assets/asset_id

Pour supprimer une propriété, définissez-la sur null sans type :

    earthengine asset set -p name=null projects/my-project/assets/asset_id

Les propriétés de date sont simplement des nombres qui représentent un nombre de millisecondes depuis l'epoch Unix (c'est-à-dire le 1er janvier 1970 à minuit). Elles peuvent être spécifiées directement sous forme de nombre ou dans l'un des formats suivants :

    YYYY-MM-DD
    YYYY-MM-DDThh:mm:ss
    YYYY-MM-DDThh:mm:ss.f

Le fuseau horaire est supposé être UTC. Vous pouvez définir les propriétés spéciales d'heure de début et de fin à l'aide des options --time_start et --time_end :

    earthengine asset set --time_start 1978-10-15T12:34:56 projects/my-project/assets/asset_id

cp

Copie un élément. Exemple :

    earthengine cp projects/my-project/assets/asset_id projects/my-project/assets/new_asset_id

create

Crée des dossiers et des collections d'images. Exemple :

    earthengine create folder projects/my-project/assets/folder_id
    earthengine create collection projects/my-project/assets/collection_id

Utilisez la sous-commande folder pour créer des dossiers et collection pour créer des collections d'images. Vous pouvez spécifier l'option -p pour créer de manière récursive des dossiers parents, si nécessaire. Les dossiers et les images nouvellement créés ont des LCA privées par défaut.

ls

Répertorie le contenu d'un ou de plusieurs dossiers ou collections. Exemple :

    earthengine ls users/username

L'option -l demande un format long avec plus d'informations sur chaque élément (actuellement, uniquement son type). Vous pouvez spécifier --max_items number (ou -m en abrégé) pour limiter le nombre d'éléments de chaque dossier ou collection que vous listez :

    earthengine ls -m 10 projects/my-project/assets/my_large_collection

L'exécution de la commande ls sans argument listera les dossiers de premier niveau dont vous êtes propriétaire.

modèle

Outil permettant de manipuler les modèles enregistrés TensorFlow.

model prepare

Préparez un modèle enregistré pour la diffusion dans Earth Engine. Plus précisément, cela transforme votre SavedModel en un formulaire adapté au traitement des requêtes d'Earth Engine. (En savoir plus sur SavedModel)

    earthengine model prepare my_source_dir my_dest_dir '{"Conv2D:0":"my_input_band"}' '{"Sigmoid:0":"my_output_band"}'

En savoir plus sur les modèles de plate-forme IA Pour voir un exemple complet, cliquez ici.

mv

Déplace ou renomme un asset. Exemple :

    earthengine mv projects/my-project/assets/asset_id projects/my-project/assets/new_asset_id

project_config

Définit les valeurs de configuration du projet. Avant d'utiliser cette commande, veillez à définir un projet à l'aide de set_project.

get

Pour afficher une configuration de projet, utilisez la sous-commande get :

    earthengine alpha project_config get

Si vous êtes autorisé à afficher les paramètres des tâches par lot du projet, le résultat contient les éléments suivants :

  • maxConcurrentExports : nombre indiquant le nombre maximal de tâches par lot pouvant être exécutées en parallèle pour tous les utilisateurs du projet donné. Par défaut, cette valeur est définie sur le maximum autorisé par le forfait du compte de facturation associé.

De plus, si vous êtes autorisé à afficher la configuration du plan, le résultat contient les éléments suivants :

  • planMaxConcurrentExports : nombre indiquant le nombre maximal de tâches par lot pouvant être exécutées en parallèle pour tous les utilisateurs et projets qui utilisent le compte de facturation.

set

Pour mettre à jour la configuration du projet, utilisez la sous-commande set. Les paramètres suivants peuvent être configurés :

Par exemple, pour configurer un projet de sorte qu'il n'autorise jamais plus de 10 tâches à s'exécuter en parallèle :

    earthengine alpha project_config set --max_concurrent_exports=10

Le résultat affiche la configuration du projet mise à jour, identique à ce que renvoie get.

Pour en savoir plus sur le parallélisme des tâches par lot, consultez la page Quotas Earth Engine.

rm

Supprime un ou plusieurs éléments. Exemple :

    earthengine rm projects/my-project/assets/asset_id
    earthengine rm -r projects/my-project/assets/folder_id

Vous pouvez utiliser l'option -r pour supprimer de manière récursive le contenu d'un dossier ou d'une collection. Pour plus de sécurité lors de la suppression de plusieurs éléments, vous pouvez utiliser l'option --dry_run pour vérifier exactement ce qui sera supprimé sans rien supprimer.

set_project

Définit le projet Google Cloud via lequel les requêtes de calcul sont acheminées.

    earthengine set_project foo-project

Cette commande est nécessaire avant d'exécuter des commandes qui nécessitent des fonctionnalités cloud, par exemple model.

opération

Affiche des informations sur les tâches de longue durée ou les gère. Exemples :

    earthengine task list
    earthengine task list -l
    earthengine task info TASK_ID
    earthengine task cancel TASK_ID

La sous-commande list liste les informations de base sur les tâches que vous avez envoyées récemment. L'option -l demande un format long avec plus d'informations sur chaque tâche. La sous-commande info affiche des informations détaillées sur les tâches individuelles. La sous-commande cancel annule une ou plusieurs tâches en cours d'exécution.

importation

Importe des images ou des tables depuis Google Cloud Storage vers Earth Engine, ou enregistre des fichiers GeoTIFF optimisés pour le cloud (COG) dans Cloud Storage en tant qu'éléments COG (images externes).

image

Pour importer un composant Image à l'aide des paramètres par défaut :

    earthengine upload image --asset_id=projects/my-project/assets/asset_id gs://bucket/image.tif

Si vous spécifiez plusieurs fichiers image d'entrée, ils seront interprétés comme des tuiles d'un seul composant Image. Pour en savoir plus sur les options d'importation d'images dans Earth Engine, consultez Importer des éléments d'image : options avancées.

Vous pouvez spécifier la règle de réduction pyramidale à l'aide de l'option --pyramiding_policy, qui peut être définie sur l'une des valeurs suivantes : mean (par défaut), sample, mode, min ou max. Cela permet de contrôler la façon dont Earth Engine génère la pyramide des versions de votre image en résolution inférieure :

    earthengine upload image --asset_id=projects/my-project/assets/asset_id --pyramiding_policy=sample gs://bucket/image.tif

Vous pouvez utiliser --last_band_alpha pour indiquer que le masque de l'image doit être extrait d'un canal alpha dans la dernière bande :

    earthengine upload image --asset_id=projects/my-project/assets/asset_id --last_band_alpha gs://bucket/image.tif

Vous pouvez spécifier une valeur sans données à l'aide de l'option --nodata_value. Cela masquera tous les pixels de l'image ayant cette valeur :

    earthengine upload image --asset_id=users/myuser/asset --nodata_value=255 gs://bucket/image.tif

Vous pouvez également spécifier les propriétés de métadonnées à définir sur l'élément à l'aide des mêmes options que celles acceptées par la commande asset set décrite ci-dessus. Les options sont également décrites dans le guide Image Manifest (fichier manifeste d'image).

table

Pour importer un fichier Shapefile, CSV ou TFRecord depuis Google Cloud Storage vers un asset de table Earth Engine, vous pouvez utiliser l'une des méthodes suivantes :

    earthengine upload table --asset_id=projects/my-project/assets/myUploadedShapefile gs://bucket/foo.shp
    earthengine upload table --asset_id=projects/my-project/assets/myUploadedCSV gs://bucket/foo.csv
    earthengine upload table --asset_id=projects/my-project/assets/myUploadedTFRecord gs://bucket/foo.tfrecord

Il existe de nombreuses options concernant la manière dont les fichiers CSV et TFRecord sont interprétés. Pour afficher la liste complète des options d'importation de tables, consultez le guide Fichier manifeste de table ou exécutez la commande suivante :

    earthengine upload table -h

external_image

Pour enregistrer un fichier GeoTIFF optimisé pour le cloud (COG) dans Cloud Storage en tant qu'élément basé sur un COG (appelé image externe dans l'API), exécutez la commande upload external_image avec un fichier manifeste :

earthengine upload external_image --manifest /tmp/foo.json

Ajoutez --force pour écraser un élément existant, par exemple pour le faire pointer vers une nouvelle version de son fichier (voir Mettre à jour des éléments basés sur COG).

Voici un exemple de fichier manifeste :

{
  "name": "projects/{project}/assets/cogdemo1",
  "tilesets": [
    { "id": "0", "sources": [{ "uris": ["gs://ee-docs-demos/COG_demo.tif"] }] }
  ],
  "properties": {
    "source": "https://code.earthengine.google.com/d541cf8b268b2f9d8f834c255698201d"
  },
  "startTime": "2016-01-01T00:00:00.000000000Z",
  "endTime": "2016-12-31T15:01:23.000000000Z"
}

Pour en savoir plus sur la création du fichier manifeste, consultez le guide d'enregistrement des COG et le guide du fichier manifeste d'image.