Outil de ligne de commande

L'outil earthengine est un programme utilitaire qui vous permet de gérer les ressources 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écapitulatif 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 l'interface de ligne de commande avec les identifiants d'un compte de service, utilisez l'indicateur 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 à l'emploi dans Google Colab.

Authentification

Authentifiez-vous pour chaque nouvelle session Colab ou si la machine virtuelle expire en raison de l'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. Pour connaître les autres options, consultez le guide d'authentification.

import ee
ee.Authenticate()

Exécution des commandes

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

!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 par 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 suivantes, 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 de l'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. Consultez les autres modes d'authentification disponibles via le paramètre auth_mode dans le guide d'authentification.

acl

Affiche 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 un ACL fourni dans un fichier au même format JSON. Vous pouvez copier une ACL d'un élément vers d'autres en enregistrant la sortie de get et en la fournissant à set.

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

  • private : supprime les autorisations pour 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 peut-être également accordées à des utilisateurs individuels.)

asset

Affiche 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

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 composant.

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és à l'aide des indicateurs --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, mais vous pouvez également 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 type chaîne avec la valeur "42" :

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

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

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 ne sont que des nombres représentant un nombre de millisecondes depuis l'époque 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 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éer 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 les dossiers parents si nécessaire. Par défaut, les dossiers et les images nouvellement créés sont associés à des LCA privées.

ls

Liste 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

Si vous exécutez la commande ls sans aucun argument, la liste des dossiers de premier niveau dont vous êtes propriétaire s'affiche.

modèle

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

model prepare

Préparez un modèle enregistré pour la diffusion dans Earth Engine. Plus précisément, cela transforme votre SavedModel en un format 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"}'

Pour en savoir plus sur les modèles AI Platform, cliquez ici. Pour voir un exemple complet, cliquez ici.

mv

Déplace ou renomme un élément. 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, assurez-vous de définir un projet à l'aide de set_project.

get

Pour afficher la configuration d'un 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 d'abonnement du compte de facturation associé.

En outre, si vous disposez de l'autorisation d'afficher la configuration du plan, la sortie contient les éléments suivants :

  • planMaxConcurrentExports, un 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. Vous pouvez configurer les paramètres suivants :

Par exemple, pour configurer un projet afin qu'il n'autorise jamais l'exécution de plus de 10 tâches en parallèle pour le projet en question :

    earthengine alpha project_config set --max_concurrent_exports=10

Le résultat affiche la configuration du projet mise à jour, identique à celle renvoyée par 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 composants. 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 supprimer plusieurs composants de manière sécurisée, vous pouvez utiliser l'option --dry_run afin de vérifier exactement ce qui sera supprimé sans rien supprimer.

set_project

Définit le projet Google Cloud par 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 imprime 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 crée des éléments soutenus par des 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 mosaïques d'un seul composant Image. Pour en savoir plus sur les options d'importation d'images dans Earth Engine, consultez Importer des composants Image : options avancées.

Vous pouvez spécifier la stratégie de réduction de la pyramide à l'aide de l'indicateur --pyramiding_policy, qui peut être défini sur l'une des valeurs suivantes : mean (par défaut), sample, mode, min ou max. Cela contrôle la façon dont Earth Engine génère la pyramide de versions basse résolution de votre image :

    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 "aucune donnée" à l'aide de l'option --nodata_value. Cela masquera tous les pixels de l'image avec 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 le composant à l'aide des mêmes indicateurs que ceux acceptés par la commande asset set décrite ci-dessus. Les options sont également décrites dans le guide Manifeste d'image.

table

Pour importer un fichier Shapefile, CSV ou TFRecord depuis Google Cloud Storage vers un élément 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 façon dont les fichiers CSV et TFRecord sont interprétés. Pour obtenir la liste complète des options d'importation de tableaux, consultez le guide Manifeste de tableau ou utilisez la commande suivante :

    earthengine upload table -h

external_image

Pour créer un asset soutenu par une image externe, exécutez la commande upload_image avec un fichier manifeste :

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

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 Cloud GeoTIFF et le guide Manifeste d'image.