Strumento della riga di comando

Lo strumento earthengine è un programma di utilità che consente di gestire gli asset e le attività di Earth Engine dalla riga di comando. Viene installato automaticamente quando installi l'API Python. Per verificare se lo strumento è installato e funziona correttamente, digita quanto segue in una riga di comando:

    earthengine

Se lo strumento è installato correttamente, stampa un breve riepilogo dei comandi disponibili. Per ricevere assistenza su un comando specifico, utilizza:

    earthengine command -h

Quando installi per la prima volta l'API Python, devi accedere utilizzando il comando authenticate descritto di seguito. Le sezioni seguenti descrivono i comandi disponibili in modo più dettagliato.

Credenziali del service account

Per utilizzare la CLI con le credenziali di un service account, utilizza il flag service_account_file per puntare a un file JSON contenente la chiave del service account.

    earthengine --service_account_file=service_account_creds.json

Utilizzo in Colab

Lo strumento a riga di comando di Earth Engine è preinstallato e pronto per l'uso in Google Colab.

Autenticazione

Esegui l'autenticazione per ogni nuova sessione di Colab o se la macchina virtuale scade a causa dell'inattività (le credenziali non vengono salvate tra le sessioni).

Importa la libreria client Python e chiama ee.Authenticate() per attivare il flusso di autenticazione. Segui le istruzioni per completare l'autenticazione. `auth_mode` predefinito auth_mode in Colab è colab. Per altre opzioni, consulta la guida all'autenticazione .

import ee
ee.Authenticate()

Esecuzione dei comandi

Per eseguire le utilità della riga di comando, come la CLI di Earth Engine, devi anteporre un punto esclamativo alle chiamate dei comandi.

!earthengine -h

Impostare un progetto Cloud

Utilizza l'opzione --project per impostare un progetto Cloud per ogni singolo comando earthengine.

!earthengine --project my-project <command>

In alternativa, imposta un progetto predefinito da utilizzare per tutte le earthengine chiamate utilizzando il set_project comando. Il progetto verrà aggiunto a un file di credenziali (~/.config/earthengine/credentials) e utilizzato per i comandi successivi, a meno che non venga sostituito dall'opzione --project. Imposta un progetto predefinito per ogni nuova sessione di Colab o se la macchina virtuale scade a causa dell'inattività (le credenziali non vengono salvate tra le sessioni).

!earthengine set_project my-project

Riferimenti dei comandi

autenticare

Autentica lo strumento a riga di comando e la libreria client Python in Earth Engine. Esempio:

    earthengine authenticate

Earth Engine utilizza il protocollo OAuth 2.0 per l'autenticazione dei client. Il comando earthengine authenticate ti guiderà nella procedura di autenticazione utilizzando il browser web.

Se utilizzi la modalità di autenticazione gcloud predefinita, dovrai installare gcloud se. Consulta gli altri metodi di autenticazione disponibili tramite il auth_mode parametro nella guida all'autenticazione.

acl

Stampa o aggiorna l'elenco di controllo dell'accesso (ACL) di un asset di Earth Engine. L'ACL controlla chi può leggere o scrivere in un asset. Esempi:

    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

Il sottocomando get stampa una descrizione JSON dell'ACL. Il sottocomando set imposta un ACL fornito in un file con lo stesso formato JSON. Puoi copiare un ACL da un asset ad altri salvando l'output di get e fornendolo a set.

Il sottocomando set accetta anche due nomi ACL speciali:

  • private: rimuove le autorizzazioni da tutti gli utenti tranne il proprietario.
  • public: concede l'autorizzazione di lettura a tutti gli utenti.

Il sottocomando ch consente di apportare modifiche individuali a un ACL. Per concedere l'autorizzazione di lettura specifica -u username@gmail.com:R, per concedere l'autorizzazione di scrittura, specifica -u username@gmail.com:W e per rimuovere le autorizzazioni di un utente, specifica -d username@gmail.com. L'identificatore utente speciale AllUsers può essere utilizzato per concedere o revocare l'autorizzazione di lettura a tutti gli utenti. (Tieni presente che la revoca delle autorizzazioni AllUsers non revoca le autorizzazioni aggiuntive che potresti aver concesso anche ai singoli utenti.)

asset

Stampa o aggiorna i metadati associati a un asset di Earth Engine. Esempi:

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

Il sottocomando info stampa informazioni dettagliate sull'asset, inclusi i relativi metadati, in formato JSON. Il sottocomando set imposta le singole proprietà dei metadati di un asset.

I valori delle proprietà dei metadati che imposti possono essere numeri o stringhe. Quando imposti i nomi delle proprietà utilizzando il flag --property o -p, separa il nome e il valore della proprietà con un segno di uguale. Il tipo di dati viene rilevato automaticamente oppure puoi specificarlo in modo esplicito anteponendo al nome della proprietà (string), (number) o (date). Ad esempio, questo comando imposta una proprietà con valore stringa con il valore "42":

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

Le virgolette in questo esempio impediscono alla shell di interpretare le parentesi. Potrebbero essere necessarie o meno, a seconda della shell e della piattaforma.

Per creare proprietà speciali per le visualizzazioni delle bande di classificazione, puoi archiviare gli elenchi di valori e colori come stringhe separate da virgole. Ad esempio, per impostare i valori di tavolozza e classe per una banda denominata 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

Per eliminare una proprietà, impostala su null senza un tipo:

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

Le proprietà della data sono solo numeri che rappresentano un numero di millisecondi dall'epoca Unix (ovvero la mezzanotte del 1° gennaio 1970) e possono essere specificate direttamente come numero o in uno dei seguenti formati:

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

Si presuppone che il fuso orario sia UTC. Puoi impostare le proprietà speciali di ora di inizio e di fine utilizzando i flag --time_start e --time_end:

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

cp

Copia un asset. Esempio:

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

create

Crea nuove cartelle e raccolte di immagini. Esempio:

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

Utilizza il sottocomando folder per creare cartelle e collection per creare raccolte di immagini. Puoi specificare l'opzione -p per creare in modo ricorsivo le cartelle principali, se necessario. Per impostazione predefinita, le cartelle e le immagini appena create hanno ACL privati.

ls

Elenca i contenuti di una o più cartelle o raccolte. Esempio:

    earthengine ls users/username

L'opzione -l richiede un formato lungo con maggiori informazioni su ogni asset (attualmente solo il tipo). Puoi specificare --max_items number (o -m per breve) per limitare il numero di elementi di ogni cartella o raccolta che elenchi:

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

Se esegui il comando ls senza argomenti, verranno elencate le cartelle di primo livello di tua proprietà.

modello

Strumento con cui manipolare i modelli salvati di TensorFlow.

model prepare

Prepara un modello salvato per la pubblicazione in Earth Engine. In particolare, questo comando trasforma il tuo SavedModel in un formato adatto all'elaborazione delle richieste di Earth Engine. (Scopri di più su SavedModel.)

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

Scopri di più sui modelli di AI Platform qui. Vedi un esempio completo esempio qui.

mv

Sposta o rinomina un asset. Esempio:

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

project_config

Imposta i valori di configurazione del progetto. Prima di utilizzare questo comando, assicurati di impostare un progetto utilizzando set_project.

get

Per visualizzare la configurazione di un progetto, utilizza il sottocomando get:

    earthengine alpha project_config get

Se hai l'autorizzazione per visualizzare le impostazioni delle attività batch del progetto, l'output contiene:

Inoltre, se hai l'autorizzazione per visualizzare la configurazione del piano, l' output contiene:

  • planMaxConcurrentExports, un numero che indica il numero massimo di attività batch che possono essere eseguite in parallelo per tutti gli utenti e i progetti che utilizzano l'account di fatturazione.

set

Per aggiornare la configurazione del progetto, utilizza il sottocomando set. È possibile configurare le seguenti impostazioni:

  • max_concurrent_exports, per controllare il parallelismo massimo delle attività batch del progetto

Ad esempio, per configurare un progetto in modo che consenta l'esecuzione in parallelo di un massimo di 10 attività per il progetto specificato:

    earthengine alpha project_config set --max_concurrent_exports=10

L'output mostra la configurazione del progetto aggiornata, identica a quella che get restituisce.

Per saperne di più sul parallelismo delle attività batch, consulta la pagina Quote di Earth Engine.

rm

Elimina uno o più asset. Esempio:

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

Puoi utilizzare il flag -r per eliminare in modo ricorsivo i contenuti di una cartella o di una raccolta. Per sicurezza durante l'eliminazione di più asset, puoi utilizzare il flag --dry_run per verificare esattamente cosa verrà eliminato senza eliminare effettivamente nulla.

set_project

Imposta il progetto cloud di Google tramite il quale vengono instradate le richieste di calcolo.

    earthengine set_project foo-project

Questo comando è necessario prima di eseguire i comandi che richiedono funzionalità Cloud, ad esempio model.

attività

Stampa informazioni sulle attività a lunga esecuzione o le gestisce. Esempi:

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

Il sottocomando list elenca le informazioni di base sulle attività che hai inviato di recente. L'opzione -l richiede un formato lungo con maggiori informazioni su ogni attività. Il sottocomando info stampa informazioni dettagliate sulle singole attività. Il sottocomando cancel annulla una o più attività in esecuzione.

upload

Carica immagini o tabelle da Google Cloud Storage a Earth Engine oppure crea asset supportati da immagini esterne.

immagine

Per caricare un asset immagine utilizzando le impostazioni predefinite:

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

Se specifichi più file immagine di input, questi verranno interpretati come riquadri di un singolo asset immagine. Puoi scoprire di più sulle opzioni per il caricamento delle immagini in Earth Engine in Caricamento di asset immagine: opzioni avanzate.

Puoi specificare la policy di riduzione della piramide utilizzando il flag --pyramiding_policy, che può essere impostato su mean (valore predefinito), sample, mode, min o max. In questo modo, Earth Engine genererà la piramide di versioni a risoluzione inferiore dell'immagine:

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

Puoi utilizzare --last_band_alpha per indicare che la maschera dell'immagine deve essere presa da un canale alfa nell'ultima banda:

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

Puoi specificare un valore no-data utilizzando il flag --nodata_value. In questo modo, verranno mascherati tutti i pixel dell'immagine con quel valore:

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

Puoi anche specificare le proprietà dei metadati da impostare sull'asset utilizzando gli stessi flag accettati dal comando asset set descritto sopra. Le opzioni sono descritte anche nella guida al manifest dell'immagine.

tabella

Per caricare un file Shapefile, CSV o TFRecord da Google Cloud Storage a un asset tabella di Earth Engine, puoi utilizzare uno dei seguenti metodi:

    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

Esistono molte opzioni relative alla modalità di interpretazione dei file CSV e TFRecord. Puoi visualizzare un elenco completo delle opzioni di caricamento delle tabelle visitando la guida al manifest delle tabelle o con:

    earthengine upload table -h

external_image

Per creare un asset supportato da un'immagine esterna, esegui il comando upload_image con un manifest:

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

Di seguito è riportato un esempio di manifest:

{
  "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"
}

Per maggiori dettagli sulla creazione del manifest, consulta la guida a Cloud GeoTIFF e la guida al manifest dell'immagine.