Lo strumento earthengine è un programma di utilità che ti consente di gestire asset e 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 in modo più dettagliato
i comandi disponibili.
Credenziali dell'account di servizio
Per utilizzare la CLI con le credenziali di un service account, utilizza il
flag service_account_file per indicare 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 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 per 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. Il valore predefinito
auth_mode in Colab è colab. Per altre opzioni, consulta la
Guida all'autenticazione.
import ee
ee.Authenticate()
Esecuzione del comando
Per eseguire utilità della riga di comando, come l'interfaccia a riga di comando di Earth Engine, devi anteporre un punto esclamativo alle chiamate di comando.
!earthengine -h
Imposta 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 chiamate earthengine
utilizzando il comando set_project. Il progetto verrà aggiunto
a un file delle credenziali (~/.config/earthengine/credentials) e utilizzato per
i comandi successivi, a meno che non venga sostituito dall'opzione --project
!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 autenticare i client. Il comando earthengine authenticate ti guiderà nella procedura di autenticazione utilizzando il browser web.
Se utilizzi la modalità di autenticazione gcloud predefinita, devi installare gcloud. Consulta le altre modalità di autenticazione
disponibili tramite il parametro auth_mode nella guida
all'autenticazione.
acl
Stampa o aggiorna l'elenco di controllo dell'accesso (ACL) di un asset Earth Engine. La ACL controlla chi può leggere o scrivere in una risorsa. 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 set sottocomando 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 per tutti tranne che per 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 eventuali autorizzazioni aggiuntive che potresti aver concesso anche
a singoli utenti.
asset
Stampa o aggiorna i metadati associati a una risorsa 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 proprietà dei metadati individuali di una risorsa.
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 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 necessari o meno, a seconda della shell e della piattaforma.)
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
Il fuso orario è considerato 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 in base alle esigenze. 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
abbreviazione) per limitare il numero di elementi di ogni cartella o raccolta che elenchi:
earthengine ls -m 10 projects/my-project/assets/my_large_collection
L'esecuzione del comando ls senza argomenti elenca 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. Nello specifico, 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 AI Platform qui. Vedi un esempio completo 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 disponi dell'autorizzazione per visualizzare le impostazioni del batch di attività del progetto, l'output contiene:
maxConcurrentExports: un numero che indica il numero massimo di attività batch che possono essere eseguite in parallelo per tutti gli utenti per il progetto specificato. Per impostazione predefinita, questo valore è impostato sul massimo consentito dal piano di abbonamento dell'account di fatturazione associato.
Inoltre, se disponi dell'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 su tutti gli utenti e i progetti che utilizzano l'account di fatturazione.
imposta
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- richiede le autorizzazioni corrette
Ad esempio, per configurare un progetto in modo che consenta l'esecuzione di 10 attività in parallelo per il progetto specificato:
earthengine alpha project_config set --max_concurrent_exports=10
L'output mostra la configurazione del progetto aggiornata, identica a quella restituita da
get.
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 una raccolta. Per sicurezza quando elimini più asset, puoi utilizzare il flag
--dry_run per verificare esattamente cosa verrà eliminato senza eliminare
nulla.
set_project
Imposta il progetto cloud di Google tramite il quale vengono indirizzate le richieste di calcolo.
earthengine set_project foo-project
Questo comando è necessario prima di eseguire comandi che richiedono funzionalità Cloud, ad esempio model.
attività
Stampa informazioni o gestisce attività a esecuzione prolungata. 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 in 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 unico asset immagine. Puoi scoprire di più sulle opzioni per caricare immagini su 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 uno dei seguenti valori: mean (valore predefinito), sample, mode, min o max. Questo parametro controlla il modo in cui Earth Engine genera 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 per l'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 senza dati 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
Manifest dell'immagine.
tabella
Per caricare un file Shapefile, CSV o TFRecord da Google Cloud Storage in una risorsa tabella 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 al modo in cui vengono interpretati i file CSV e TFRecord. Puoi visualizzare un elenco completo delle opzioni di caricamento delle tabelle visitando la guida al manifesto delle tabelle o con:
earthengine upload table -h
external_image
Per creare una risorsa supportata da un'immagine esterna, esegui il comando upload_image
con un manifest:
earthengine upload external_image --manifest /tmp/foo.json
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 Cloud GeoTIFF e la guida Manifest dell'immagine.