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 ha 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 unico 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 restituiti per la visualizzazione nella scheda Mappa e/o Console. Per eseguire l'editor di codice, ti servono solo un browser web (utilizza Google Chrome per risultati ottimali) e una connessione a internet. Le sezioni seguenti descrivono in modo più dettagliato gli elementi dell'editor di codice di Earth Engine.

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
  • Completare automaticamente le 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 a API Docs nel riquadro sinistro 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 tu non li condivida 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 Writer. 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 gli script 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 . 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 Gestione script.

È 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 in questo tutorial. Fai clic sull'icona accanto al nome del repository per istruzioni sulla clonazione del repository. Tieni presente che puoi sfogliare i repository a cui hai accesso andando su earthengine.googlesource.com. Per alcune operazioni Git, potrebbe essere necessario creare credenziali di autenticazione andando al link "Genera password" nella parte superiore della pagina earthengine.googlesource.com.

Moduli di script

È buona norma scrivere codice modulare e riutilizzabile che possa essere condiviso tra gli script senza dover copiare e incollare in modo esteso. 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());

Nota l'utilizzo della parola chiave exports nella forma 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 a cui fa 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. Asset Manager.

Gli script dell'editor di codice possono essere condivisi tramite un URL codificato. Le sezioni seguenti descrivono vari modi per generare un URL script, le opzioni disponibili e i metodi per gestire gli URL 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 degli script. Tieni presente 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 un utente con un account Earth Engine, il browser passa all'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 giù 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 altri, 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, si apre una nuova scheda del browser con un'interfaccia che ti consente di 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 tuo sistema contenente un file .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 archiviare 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 specifici.

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 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 nello script sono organizzati in una sezione importazioni nella parte superiore dello script, nascosta finché non importi qualcosa. Una volta create alcune importazioni, dovresti vedere qualcosa di simile alla 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 degli import 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.

Layer Manager

Utilizza il Gestore 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) ti 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 base ai percentili o alle deviazioni standard dei valori dell'immagine nella finestra di visualizzazione. Le statistiche vengono calcolate in base a tutti i pixel nella finestra Mappa al livello di zoom corrente. 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 di stringhe esadecimali separate da virgole (). 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. La posizione del cursore e il livello di zoom vengono visualizzati 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 visualizzare maggiori dettagli.

Scheda Attività

Le attività 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 permanenti 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 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 compila 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 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 che le ha 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 ulteriori informazioni e opzioni 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à in Cloud Console.

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 il motivo per cui 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 si attiva 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 scomparirà e il profiler verrà 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 del segnaposto , per disegnare linee, utilizza l'icona della linea , per disegnare poligoni, utilizza l'icona del poligono , per disegnare rettangoli, utilizza l'icona del 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 di geometrie per convertirle 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 una visita guidata dell'editor di codice e a un elenco di scorciatoie da tastiera che aiutano a codificare, eseguire il codice e visualizzare i 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.