Editor di codice di Earth Engine

L'editor di codice di Earth Engine (EE) all'indirizzo code.earthengine.google.com è un IDE basato sul web per l'API JavaScript di Earth Engine. Le funzionalità dell'editor di codice sono progettate per velocizzare e semplificare lo sviluppo di flussi di lavoro geospaziali complessi. L'editor di codice contiene i seguenti elementi (illustrati nella Figura 1):

  • Editor di codice JavaScript
  • Visualizzazione mappa per la visualizzazione di set di dati geospaziali
  • Documentazione di riferimento dell'API (scheda Documenti)
  • Gestore di script basato su Git (scheda Script)
  • Output console (scheda Console)
  • Task Manager (scheda Attività) per gestire le query a lunga esecuzione
  • Query interattiva sulla mappa (scheda Strumento di controllo)
  • Ricerca nell'archivio dati o negli script salvati
  • Strumenti di disegno geometrico

Componenti dell'editor di codice

Figura 1. Diagramma dei componenti dell'Editor di codice di Earth Engine all'indirizzo code.earthengine.google.com.

L'editor di codice offre una serie di funzionalità per aiutarti a sfruttare al meglio l'API Earth Engine. Visualizza script di esempio o salva i tuoi script nella scheda Script. Esegui query sugli oggetti posizionati sulla mappa con la scheda Strumento di controllo. Visualizza e traccia i risultati numerici utilizzando l'API di visualizzazione Google. Condividi un URL univoco del tuo copione con collaboratori e amici con il pulsante Ottieni link. Gli script che sviluppi nell'editor di codice vengono inviati a Google per l'elaborazione e i riquadri della mappa e/o i messaggi generati vengono inviati di nuovo per la visualizzazione nella scheda Mappa e/o Console. Per eseguire l'editor di codice è sufficiente un browser web (utilizza Google Chrome per risultati ottimali) e una connessione a internet. Le sezioni seguenti descrivono gli elementi dell'editor di codice di Earth Engine in modo più dettagliato.

Editor JavaScript

L'editor JavaScript:

  • Formattare ed evidenziare il codice durante la digitazione
  • Sottolinea il codice con problemi, offre correzioni e altri suggerimenti per la sintassi corretta
  • Completamento automatico di coppie di virgolette, parentesi quadre e tonde
  • Offrire suggerimenti per il completamento del codice per le funzioni di Earth Engine

Sopra l'editor di codice si trovano i pulsanti per eseguire lo script, salvarlo, reimpostare la mappa di output e la console e ottenere un link allo script. Quando viene premuto il pulsante Ottieni link, nella barra degli indirizzi del browser viene visualizzato un link univoco. Questo link rappresenta il codice nell'editor al momento della pressione del pulsante.

Riferimento API (scheda Documenti)

Sul lato sinistro dell'editor di codice si trova la scheda Docs, che contiene la documentazione completa dell'API JavaScript. La documentazione può essere cercata e sfogliata dalla scheda Documenti.

Gestore script (scheda Script)

La scheda Script si trova accanto alla documentazione API nel riquadro a sinistra dell'editor di codice. Script Manager archivia script privati, condivisi e di esempio in repository Git ospitati da Google. I repository sono organizzati in base al livello di accesso. Gli script privati sono archiviati in un repository di tua proprietà nella cartella Proprietario: users/username/default. Tu (e solo tu) hai accesso ai repository nella cartella Proprietario, a meno che non li condividi con qualcun altro. I repository nella cartella Scrittore sono repository per i quali ti è stato concesso l'accesso in scrittura dal proprietario. Puoi aggiungere nuovi script, modificare quelli esistenti o cambiare l'accesso (non puoi rimuovere il proprietario) ai repository nella cartella Scrittore. I repository nella cartella Lettore sono repository per i quali ti è stato concesso l'accesso in lettura dal proprietario. La cartella Examples è un repository speciale gestito da Google che contiene esempi di codice. La cartella Archivio contiene repository legacy a cui hai accesso, ma che non sono ancora stati migrati dal proprietario da una versione precedente di Script Manager. Cerca tra i tuoi script utilizzando la barra dei filtri nella parte superiore della scheda Script.

Gestore script

Figura 2. Gestore script.

Fai clic sul pulsante per creare un nuovo repository nella cartella Proprietario o per creare cartelle e file all'interno di un repository. Puoi rinominare gli script con l'icona ed eliminarli con l'icona . Puoi spostare i copioni e organizzarli in cartelle utilizzando il trascinamento (Figura 2). Se trascini uno script in un altro repository, viene copiato.

Tutti gli script e i repository mantengono la cronologia completa delle versioni. Fai clic sull'icona accanto a uno script o a un repository per confrontarlo o ripristinarlo a una versione precedente. Per eliminare un repository, fai clic sull'icona (l'eliminazione di un repository comporta la rimozione definitiva del repository, dei relativi script e della cronologia dei commit). Per configurare l'accesso a un repository, fai clic sull'icona accanto al nome del repository. Tieni presente che se condividi un repository, la persona con cui lo condividi dovrà accettarlo facendo clic sul link mostrato nella finestra di dialogo delle impostazioni. I repository accettati in precedenza possono essere nascosti facendo clic sull'icona dopo il nome del repository in Script Manager.

È possibile accedere ai repository utilizzando Git, in modo da poter gestire e modificare gli script al di fuori dell'editor di codice o sincronizzarli con un sistema esterno come GitHub (scopri di più su Git nella documentazione di Git). Fai clic sull'icona accanto al nome del repository per istruzioni sulla clonazione del repository. Puoi sfogliare i repository a cui hai accesso andando alla pagina earthengine.googlesource.com (richiede l'accesso con il tuo Account Google Earth Engine). Per istruzioni sull'utilizzo di Git per ripristinare script o cartelle eliminati o per eseguire la migrazione di un repository a un altro account, vedi Recupero di script e migrazione di repository.

Moduli di script

È buona norma scrivere codice modulare e riutilizzabile che possa essere condiviso tra script senza dover copiare e incollare in modo eccessivo. Per consentire lo sviluppo modulare, Earth Engine offre la possibilità di condividere il codice tra gli script. Ad esempio, supponiamo di scrivere una funzione che esegue un insieme utile di operazioni. Anziché copiare il codice della funzione in un nuovo script, è più semplice per il nuovo script caricare direttamente la funzione. Per rendere una funzione o un oggetto disponibile per altri script, aggiungilo a un oggetto speciale chiamato exports. Per utilizzare il codice in un altro script, utilizza la funzione require per caricare le esportazioni da un altro script. Ad esempio, supponiamo di definire il seguente modulo in un file denominato FooModule.js che si trova in una cartella denominata Modules:

Editor di codice (JavaScript)

/**
 * The Foo module is a demonstration of script modules.
 * It contains a foo function that returns a greeting string.
 * It also contains a bar object representing the current date.
 * @module Modules/FooModule
 */

/**
 * Returns a greeting string.
 * @param {ee.String} arg The name to which the greeting should be addressed
 * @return {ee.String} The complete greeting.
 */
exports.foo = function(arg) {
  return 'Hello, ' + arg + '!  And a good day to you!';
};

/**
 * An ee.Date object containing the time at which the object was created.
 */
exports.bar = ee.Date(Date.now());

Prendi nota dell'utilizzo della parola chiave exports nel formato exports.objectToExport. Puoi utilizzare questo modulo in un altro script utilizzando la funzione require. Ad esempio:

Editor di codice (JavaScript)

var Foo = require('users/username/default:Modules/FooModule.js');

print(Foo.doc);

print(Foo.foo('world'));

print('Time now:', Foo.bar);

La funzione require prevede una stringa che descrive il percorso assoluto alla posizione del modulo. Nello specifico, l'argomento di require() è nel formato 'pathToRepository:pathToModuleScript'. Puoi caricare moduli solo da repository di tua proprietà e/o a cui hai accesso in lettura. Se vuoi che altri possano utilizzare il tuo modulo, il repository deve essere condiviso con gli altri utenti a cui vuoi concedere l'accesso. Ti consigliamo di documentare il modulo per aiutare gli altri a capire come utilizzarlo. Ti consigliamo di utilizzare lo stile JSDoc con il tag @module.

Puoi utilizzare il parametro URL ?scriptPath={repo}:{script} per condividere un riferimento a un file nel tuo repository, ad esempio https://code.earthengine.google.com/?scriptPath=users/username/utils:utils. Quando visiti l'URL, il file di riferimento e il relativo repository vengono aggiunti alla directory Reader o Writer nella scheda Script, a seconda del tuo livello di autorizzazione per il repository condiviso.

Responsabile asset (scheda Asset)

Asset Manager si trova nella scheda Asset nel riquadro a sinistra. Utilizza Asset Manager (Figura 3) per caricare e gestire le tue risorse immagine in Earth Engine. Per i dettagli, consulta la pagina di Asset Manager.

Asset Manager

Figura 3. Responsabile asset.

Gli script dell'editor di codice possono essere condivisi tramite un URL codificato. Le sezioni seguenti descrivono vari modi per generare un URL dello script, le opzioni disponibili e i metodi per gestire gli URL dello script.

Il pulsante "Ottieni link" nella parte superiore dell'editor di codice (Figura 4) fornisce un'interfaccia per generare URL di script e impostare le opzioni di comportamento dello script. Nota le distinzioni tra gli URL degli snapshot e degli script salvati descritti di seguito.

La libreria

Immagine 4. Il pulsante "Ottieni link".

Il codice nell'editor può essere condiviso tramite un URL snapshot codificato che viene creato quando si fa clic sul pulsante "Ottieni link" nella parte superiore dell'editor di codice. Quando l'URL viene visitato da una persona con un account Earth Engine, il browser si sposta nell'editor di codice e replica l'ambiente così com'era quando è stato creato il link, inclusi codice, importazioni, livelli della mappa e posizione della mappa. Se fai clic sul pulsante "Ottieni link", il link dello script verrà copiato automaticamente negli appunti. Inoltre, verrà visualizzata una finestra di dialogo con le opzioni per controllare l'esecuzione dello script condiviso, insieme ai pulsanti per copiare e visitare il link generato. Le opzioni di controllo includono l'impedimento dell'esecuzione automatica dello script e l'occultamento del riquadro del codice quando qualcuno apre il link condiviso. La finestra di dialogo trascinabile può essere chiusa tramite il tasto "Esc" o un clic in un altro punto della pagina.

Gli script salvati hanno un'opzione per condividere un link che caricherà sempre la versione salvata più recente ed è accessibile solo a te e ad altri utenti con accesso attuale al repository contenente lo script. Per utilizzare questa funzionalità, carica uno script salvato dalla scheda Gestione script, fai clic sulla freccia del menu a discesa a destra del pulsante "Ottieni link" e seleziona "Copia percorso script". Verrà visualizzata una finestra di dialogo con l'URL dello script condivisibile. Tieni presente che l'URL dello script è stato impostato anche nella barra degli indirizzi del browser. Per indicazioni sulla condivisione del repository con altre persone, consulta la sezione Gestione script.

Il pulsante del menu a discesa a destra del pulsante "Ottieni link" include l'opzione "Gestisci link". Se fai clic su questa opzione, viene caricata una nuova scheda del browser con un'interfaccia per richiamare, rimuovere e scaricare i link agli script generati in precedenza. Se selezioni uno script e premi il pulsante di download, verrà scaricata una cartella compressa ("code_editor_links.zip") nel sistema contenente una rappresentazione in formato .txt per ogni script selezionato.

Il modulo ui.url consente la manipolazione programmatica dell'identificatore di frammento dell'URL dello script tramite i metodi get e set. Ciò significa che gli script dell'editor di codice e le app Earth Engine possono leggere e memorizzare i valori nell'URL della pagina. Nota la fine dei due URL seguenti: il primo imposta la variabile debug come false e il secondo come true. Visita entrambi i link e nota che la casella di controllo di debug nella console non è selezionata nel primo, mentre è selezionata nel secondo, modificando il comportamento di ogni script.

https://code.earthengine.google.com/5695887aad76979388a723a85339fbf2#debug=false;

https://code.earthengine.google.com/5695887aad76979388a723a85339fbf2#debug=true;

Questa funzionalità può essere utilizzata per impostare lo zoom e il centro della mappa, nonché altri comportamenti che potresti voler personalizzare quando invii link a persone o gruppi particolari.

Strumento di ricerca

Per trovare i set di dati da utilizzare negli script, puoi utilizzare lo strumento di ricerca dell'archivio dei dati. Lo strumento di ricerca è la casella di testo nella parte superiore dell'editor di codice in cui è scritto "Cerca luoghi e set di dati…". Digita il nome di un prodotto di dati, un sensore o un'altra parola chiave nella barra di ricerca e fai clic sul pulsante per visualizzare un elenco di luoghi, raster e set di dati tabellari corrispondenti. Fai clic su un risultato raster o di tabella per visualizzare la descrizione del set di dati nell'archivio. Per importare il set di dati direttamente nello script, fai clic sul link importa o sul pulsante dalla descrizione del set di dati.

Importazioni

I risultati dell'importazione dei set di dati importati nello script sono organizzati in una sezione importazioni nella parte superiore dello script, nascosta finché non importi qualcosa. Dopo aver creato alcune importazioni, dovresti vedere una schermata simile a quella della Figura 5. Per copiare le importazioni in un altro script o convertirle in JavaScript, fai clic sull'icona accanto all'intestazione Importazioni e copia il codice generato nello script. Puoi eliminare l'importazione con l'icona .

Sezione Importazioni dell'editor di codice

Figura 5. La sezione delle importazioni nella parte superiore dell'editor di codice.

Mappa

L'oggetto Map nell'API si riferisce alla visualizzazione della mappa nell'editor di codice. Ad esempio, Map.getBounds() restituirà la regione geografica visibile nell'editor di codice. Controlla le funzioni Map nell'API per visualizzare altre personalizzazioni per questa visualizzazione.

Gestore dei livelli

Utilizza il gestore dei livelli nell'angolo in alto a destra della mappa per regolare la visualizzazione dei livelli che hai aggiunto alla mappa. In particolare, puoi attivare/disattivare la visibilità di un livello o regolarne la trasparenza con il cursore. Fai clic sull'icona per regolare i parametri di visualizzazione per i singoli livelli. Lo strumento di visualizzazione che viene visualizzato (Figura 6) consente di configurare in modo interattivo i parametri di visualizzazione dei livelli. Fai clic sul pulsante a destra dello strumento (che esegue un allungamento personalizzato all'intervallo minimo e massimo fornito per impostazione predefinita) per allungare linearmente la visualizzazione in percentili o deviazioni standard dei valori dell'immagine nella finestra di visualizzazione. Le statistiche vengono calcolate da tutti i pixel nella finestra Mappa al livello di zoom attuale. Utilizza i cursori per regolare la gamma e/o la trasparenza. Fai clic sul pulsante di opzione Tavolozza e specifica una tavolozza personalizzata aggiungendo colori (), rimuovendo colori () o inserendo manualmente un elenco separato da virgole di stringhe esadecimali (). Fai clic su Applica per applicare i parametri di visualizzazione alla visualizzazione corrente. Fai clic su Importa per caricare un oggetto di parametri di visualizzazione come nuova variabile nella sezione importazioni dello script.

Lo strumento di visualizzazione dei livelli.

Immagine 6. Lo strumento di visualizzazione dei livelli.

Scheda Strumento di controllo

La scheda Strumento di controllo accanto a Task Manager ti consente di eseguire query interattive sulla mappa. Quando la scheda Ispettore è attiva, il cursore diventa un mirino che mostra la posizione e i valori del livello sotto il cursore quando fai clic sulla mappa. Ad esempio, la Figura 7 mostra i risultati del clic sulla mappa all'interno della scheda Inspector. Vengono visualizzati la posizione del cursore e il livello di zoom, insieme ai valori dei pixel e a un elenco di oggetti sulla mappa. L'elenco degli oggetti è interattivo. Per visualizzare ulteriori informazioni, espandi gli oggetti nella scheda Inspector.

Scheda Strumento di controllo

Immagine 7. La scheda Inspector mostra informazioni sulla posizione del cursore e sui valori del livello sotto il cursore.

Scheda Console

Quando print() qualcosa dallo script, ad esempio testo, oggetti o grafici, il risultato viene visualizzato nella console. La console è interattiva, quindi puoi espandere gli oggetti stampati per ottenere maggiori dettagli.

Scheda Attività

Le attività di Earth Engine sono operazioni in grado di essere eseguite per un periodo di tempo molto più lungo rispetto al timeout standard delle richieste API. Queste attività a esecuzione prolungata sono l'unico meccanismo per creare artefatti persistenti in Earth Engine e nei sistemi adiacenti (Google Cloud Storage, Google Drive e così via) e rientrano in due categorie: Import e Export.

Le attività di importazione possono essere utilizzate per caricare immagini o caricare tabelle in Earth Engine da una serie di tipi di file (.csv, .tif e così via). Le attività di esportazione possono essere utilizzate per eseguire e scrivere i risultati del sistema di calcolo EE (consulta la guida per l'esportazione dei dati).

Per le esportazioni, ogni chiamata a una funzione Export nell'editor di codice compilerà una voce nella sezione Attività non inviate della scheda Attività. Per inviare un'attività di esportazione al server, fai clic sul pulsante Esegui accanto all'attività. Viene visualizzata una finestra di dialogo di configurazione che ti consente di specificare una serie di parametri per l'attività. Se l'attività è completamente specificata al momento della creazione (ovvero la chiamata a Export ha tutti i parametri necessari), tieni premuto ctrl o ⌘ mentre fai clic su Esegui per inviare l'attività senza mostrare la finestra di dialogo.

Per le importazioni, il caricamento dei file avviene localmente prima che l'attività venga inviata al server. Le attività di importazione nella fase di caricamento mostreranno l'avanzamento nella sezione Attività non inviate e verranno inviate automaticamente al server al termine del caricamento del file.

Le attività non inviate vengono visualizzate solo nella pagina in cui sono state create e vengono perse quando la pagina viene chiusa. Una volta inviata un'attività al server, se fai clic sulla relativa riga nell'interfaccia utente, vengono visualizzate informazioni e opzioni aggiuntive sullo stato dell'attività, inclusa l'opzione per richiedere l'annullamento.

Per visualizzare e annullare più attività in una visualizzazione a schermo intero (inclusi i client mobile), utilizza la pagina Attività nella console Cloud.

Profiler

Profiler mostra informazioni sulle risorse (tempo di CPU, memoria) utilizzate da algoritmi specifici e da altre parti di un calcolo. Ciò consente di diagnosticare perché uno script viene eseguito lentamente o non riesce a essere eseguito a causa dei limiti di memoria. Per utilizzare il profiler, fai clic sull'opzione Esegui con profiler nel menu a discesa del pulsante Esegui. Come scorciatoia, tieni premuto Alt (o Opzione su Mac) e fai clic su Esegui oppure premi Ctrl+Alt+Invio. In questo modo viene attivata una scheda Profiler sul lato destro dell'editor di codice. Durante l'esecuzione dello script, la scheda Profiler mostrerà una tabella con l'utilizzo delle risorse dello script. Se fai clic sul pulsante Esegui (senza profilazione), la scheda Profiler scompare e il profiler viene disattivato.

Consulta la pagina Panoramica del calcolo per una suddivisione dell'output del profiler.

Assistente AI (scheda Chiedi)

L'editor di codice include un assistente AI, basato su Gemini, per aiutarti a scrivere, eseguire il debug e comprendere i tuoi script. L'assistente è disponibile nella scheda Chiedi nel riquadro a destra.

Per informazioni dettagliate su come configurare e utilizzare l'assistente, consulta la guida Assistente AI nell'editor di codice di Earth Engine.

Strumenti di geometria

Puoi anche importare geometrie nello script disegnandole sullo schermo. Per creare geometrie, utilizza gli strumenti di disegno delle geometrie nell'angolo in alto a sinistra della visualizzazione della mappa (Figura 8). Per disegnare punti, utilizza l'icona Segnaposto , per disegnare linee, utilizza l'icona Linea , per disegnare poligoni, utilizza l'icona Poligono , per disegnare rettangoli, utilizza l'icona Rettangolo . (Tieni presente che i rettangoli sono geometrie planari, quindi non possono essere posizionati su un livello con geometrie geodetiche come linee e poligoni.)

L'utilizzo di uno qualsiasi degli strumenti di disegno creerà automaticamente un nuovo livello di geometria e aggiungerà un'importazione per quel livello alla sezione Importazioni. Per aggiungere geometrie a un nuovo livello, passa il mouse sopra Importazioni geometrie nella visualizzazione della mappa e fai clic sul link +nuovo livello. Puoi anche attivare/disattivare la visibilità delle geometrie dalla sezione Importazioni di geometrie. Tieni presente che le geometrie disegnate sono geodetiche per impostazione predefinita, ad eccezione dei rettangoli, che sono solo planari. Utilizza il costruttore Geometry per convertirli in geometrie planari. Scopri di più sulle geometrie in Earth Engine nella pagina Geometria.

Immagine 8. Gli strumenti di disegno della geometria si trovano nell'angolo in alto a sinistra della visualizzazione della mappa.

Per configurare la modalità di importazione delle geometrie nello script, fai clic sull'icona accanto al livello nella sezione Importazioni di geometrie della mappa o nella sezione Importazioni dell'editor di codice. Lo strumento per le impostazioni del livello di geometria verrà visualizzato in una finestra di dialogo simile alla Figura 9. Tieni presente che puoi importare le forme disegnate come geometrie, caratteristiche o raccolte di caratteristiche. Le impostazioni di importazione della geometria ti consentono anche di modificare il colore con cui viene visualizzato il livello, aggiungere proprietà al livello (se viene importato come Feature o FeatureCollection) o rinominarlo.

Lo strumento di configurazione della geometria

Figura 9. Lo strumento di configurazione della geometria.

Infine, per impedire la modifica delle geometrie in un livello, puoi bloccare il livello premendo l'icona accanto al livello. In questo modo, non sarà possibile aggiungere, eliminare o modificare geometrie nel livello. Per sbloccare di nuovo il livello, premi l'icona .

Aiuto!

Fai clic sul pulsante in alto a destra dell'editor di codice per visualizzare i link a questa Guida per gli sviluppatori, ad altri forum di assistenza, a un tour guidato dell'editor di codice e a un elenco di scorciatoie da tastiera utili per la programmazione, l'esecuzione del codice e la visualizzazione dei dati sulla mappa. Fai clic sul pulsante per segnalare un bug, richiedere una nuova funzionalità, suggerire un set di dati o inviare un feedback quando non è necessaria una risposta.