Salta ai contenuti
IT

Creare un set di dati scientifico

Il pannello scientifico legge un unico file: un set di dati scientifico (comap.science-dataset/v1), salvato nelle impostazioni della stanza. Contiene somme precalcolate per zona, che il pannello somma nel browser per le zone che ognuno sceglie. Nessuno lo scrive a mano: un generatore offline lo produce dai dati sorgente, insieme a una ricevuta QA che ne verifica il risultato.

Per tracciare i livelli raster della stanza stessa in un punto scelto da chi legge, scrivi invece una configurazione Science: vedi Configurare il pannello scientifico.

Preparare una stanza richiede quattro passaggi:

  1. Costruisci il file del set di dati ed esamina la sua ricevuta QA.
  2. Carica i poligoni delle suddivisioni nella stanza come livelli della mappa.
  3. Carica il file in Impostazioni della stanza → Pannello scientifico e collega ogni suddivisione al suo livello.
  4. Verifica il pannello nella stanza.
Dato Che cos’è Nella stanza pubblica
Carta delle specie Un GeoTIFF con una banda di probabilità per specie, nel sistema di coordinate svizzero (EPSG:2056) Celle da 30 m, 11 bande: abete rosso, abete bianco, pino, larice, pino cembro, faggio, acero, frassino, quercia, castagno, altre
Alberi morti Un GeoPackage degli alberi morti rilevati per anno di volo, ognuno con la sua superficie in un campo Area Dal 2017 al 2024 — gli stessi file dei livelli Mortality della stanza
Suddivisioni Shapefile di poligoni, ognuno con un campo chiave e, facoltativamente, una suddivisione superiore da cui scendere Cantoni (KANTONSNUM), Distretti (UUID, all’interno dei cantoni), Ecoregioni forestali (Code)
Riferimenti QA Servono solo a verificare il risultato Il raster del legno morto a 10 m, le quote di alberi morti pubblicate e il livello di copertura dei voli

Una configurazione di costruzione nomina tutto questo e aggiunge ciò che il pannello mostra: l’identificativo del set di dati e il suo titolo in ogni lingua, le etichette e i gruppi delle specie, gli anni di volo con il numero di righe atteso e, per ogni suddivisione, i campi di chiave, nome, codice e livello superiore. La configurazione della stanza pubblica è python-geo-service/science/configs/public-room-v1.json nel repository dell’app.

Il generatore si trova in python-geo-service/science/ nel repository dell’app. Eseguilo nell’immagine del geo-service, con i dati di ingresso montati in sola lettura:

Terminal window
docker run --rm \
-v "$PWD:/work:ro" \
-v "$PWD/data:/science-input:ro" \
-v "<manifest.json>:/manifest/MANIFEST.json:ro" \
-v "<output dir>:/science-output" \
-w /work/python-geo-service --entrypoint python3 <image> \
-m science.build_dataset --config science/configs/public-room-v1.json \
--input-root /science-input --output-dir /science-output --expect-manifest /manifest/MANIFEST.json
  • Ogni percorso della configurazione è relativo a --input-root e non può uscirne.
  • --expect-manifest confronta byte per byte i file degli alberi morti con il manifest del set di dati da cui sono stati caricati i livelli della stanza.

Il generatore calcola l’impronta di ogni dato di ingresso e scrive tre file, chiamati come l’identificativo del set di dati:

  • Directoryscience-output/
    • public-forest-v1.json il set di dati da caricare nella stanza
    • public-forest-v1.qa.json la ricevuta QA, per gli strumenti
    • public-forest-v1.qa.md la stessa ricevuta, da leggere

Termina con lo stato 0 solo se ogni controllo obbligatorio è stato superato:

  • i dati di ingresso non sono cambiati durante la costruzione;
  • ogni anno di volo ha il numero atteso di alberi morti;
  • l’Area salvata di ogni oggetto è uguale alla superficie della sua geometria;
  • i file degli alberi morti corrispondono al manifest del set di dati della stanza (con --expect-manifest);
  • per ogni suddivisione, le zone più il resto non assegnato danno l’intera griglia.

La ricevuta segnala inoltre, senza far fallire la costruzione, se una cella è rivendicata da due zone. Per ogni zona confronta la quota di alberi morti ricavata dagli oggetti con il raster del legno morto a 10 m allineato e con la quota pubblicata, e mostra quanto spesso l’ultimo volo dedotto concorda con l’anno del livello di copertura. Leggi il file .qa.md: in alto riporta il risultato complessivo, PASSED o FAILED.

Il pannello disegna ogni suddivisione da un livello di poligoni della stanza. Gli oggetti di quel livello devono avere il campo chiave della suddivisione — per i cantoni KANTONSNUM — con i valori usati dal set di dati. La via più sicura è caricare proprio gli shapefile da cui è stato costruito il set di dati.

python -m science.room_layers carica ogni suddivisione di un set di dati come livello di poligoni attraverso l’API pubblica, poi dimostra attraverso la stessa API che il pannello scientifico può usarla. Gli servono solo la libreria standard di Python (Python 3.12 o successivo) e un token API della stanza.

  1. Emetti un token. In Le mie stanze, fai clic sul pulsante Token API (chiave) della stanza e crea un token con i permessi Lettura e Caricamento, che scada dopo un giorno. Salva il segreto in un file che solo tu puoi leggere (chmod 600): lo strumento rifiuta qualsiasi altro file e non stampa mai il token. Vedi Token API della stanza.

  2. Esegui lo strumento da python-geo-service/, un passaggio dopo l’altro, come mostrato sotto. --api è l’origine dell’app e --room l’identificativo della stanza da riempire; inserisci i tuoi valori per entrambi. apply parte solo se gli passi l’impronta del piano stampata da preflight.

  3. Revoca il token quando hai finito.

Terminal window
ARGS=(--config science/configs/public-room-v1.json --dataset ../data/science/public-forest-v1.json
--input-root ../data --api <app-origin> --room <room-id>)
python -m science.room_layers plan "${ARGS[@]}" # offline
python -m science.room_layers preflight "${ARGS[@]}" --token-file <file> # read-only; prints the plan digest
python -m science.room_layers apply "${ARGS[@]}" --token-file <file> --expect-plan <digest>
python -m science.room_layers verify "${ARGS[@]}" --token-file <file> # read-only, any time

Ogni passaggio verifica qualcosa prima che il successivo possa partire:

Passaggio Verifica
plan I file dello shapefile di ogni suddivisione hanno gli SHA-256 registrati dal set di dati, i suoi valori chiave corrispondono alle zone del set di dati e lo ZIP sta in un’unica richiesta di caricamento. Stampa l’impronta del piano.
preflight In sola lettura. Il token può leggere la stanza, il filtro dei token dell’API rifiuta GET /api/account (fail-closed) e nessun livello della stanza ha già uno dei nomi — i nomi dei livelli sono unici in una stanza.
apply Esegue solo il piano di cui hai approvato l’impronta: carica i livelli uno per uno, attende l’elaborazione, poi esegue verify.
verify In sola lettura. Un livello per nome, il numero di oggetti e il tipo poligono giusti, le tessere vettoriali generate e tessere che portano esattamente le chiavi di zona del set di dati — l’unico modo in cui il pannello trova una zona sulla mappa.

Il riepilogo che stampa (e che scrive in un file con --receipt <file>) elenca gli identificativi dei nuovi livelli per suddivisione. Il suo stato di uscita dice com’è andata: 0 superato, 2 un controllo locale è fallito, 3 l’API ha rifiutato (token, permesso, nome già usato, quota), 4 errore del server o della rete, 5 verifica fallita.

  • I livelli restano nascosti nella legenda, a meno che tu non aggiunga --visible: il pannello ne disegna da sé i contorni finché è aperto.
  • Un token non può eliminare livelli. Per annullare un caricamento, il proprietario della stanza elimina il livello nella stanza.
  • Ogni caricamento aggiunge una voce Add layer alla cronologia della stanza, fatta da api-token:<name>.

Puoi anche caricare tu stesso una suddivisione, come shapefile compresso in zip, dalla scheda Carica livello — vedi Caricare uno Shapefile. Usa lo shapefile da cui è stato costruito il set di dati, così che gli oggetti abbiano il campo chiave con gli stessi valori. Nessuno lo controlla per te: se le chiavi non corrispondono, il pannello mostra comunque i suoi valori, ma non può disegnare né far scegliere quelle zone sulla mappa.

Caricare il set di dati e collegare le suddivisioni

Sezione intitolata “Caricare il set di dati e collegare le suddivisioni”
  1. Nella stanza, fai clic sull’ingranaggio — Impostazioni della stanza — a destra della barra in alto. La sezione Pannello scientifico è visibile solo a proprietari ed editor. (Le stesse impostazioni si trovano anche in Menu → Impostazioni nella barra a sinistra.)

  2. Fai clic su Carica set di dati (.json) e scegli il file. La sezione mostra il suo titolo e il suo identificativo — per la stanza pubblica Specie arboree e alberi morti · public-forest-v1. Un file che non è un set di dati valido viene rifiutato con Non è un set di dati scientifico valido: e il motivo.

  3. In Livello della mappa per Cantoni, Livello della mappa per Distretti e così via, scegli il livello che disegna ogni suddivisione. Un livello il cui nome cita la suddivisione è preselezionato, quindi i livelli chiamati come la loro suddivisione si collegano da soli. Nessun livello lascia una suddivisione senza contorni.

  4. Se vuoi, scegli le Zone predefinite e la Vista predefinita con cui il pannello si apre per tutti. Lasciandole su —, si apre sulla prima suddivisione senza livello superiore, in Composizione.

  5. Fai clic su Salva. Salvato per tutti nella stanza. lo conferma, e il pulsante del pannello compare per tutti nella barra degli strumenti della mappa.

  • Caricare un file riempie solo il modulo: per nessuno cambia nulla finché non fai clic su Salva. Caricare un file reimposta inoltre i collegamenti ai livelli sui suggerimenti e cancella i valori predefiniti, quindi controllali prima di salvare.
  • Se un altro proprietario o editor salva mentre stai modificando, le tue modifiche non salvate vengono sostituite dalle sue.
  • Rimuovi il set di dati toglie il pannello dalla stanza per tutti.
  • Quando il set di dati cambia, il pannello di ognuno riparte dai valori predefiniti della stanza.

Apri il pannello scientifico nella stanza, poi:

  • passa da una suddivisione all’altra — ognuna dovrebbe disegnare i suoi contorni sulla mappa;
  • fai clic su una zona della mappa — dovrebbe risultare selezionata nell’elenco;
  • apri Come leggere — le fonti e la data di creazione dovrebbero corrispondere alla ricevuta QA.

Se una suddivisione mostra i suoi valori ma non i contorni, il suo livello non è collegato, oppure gli oggetti del livello non hanno il campo chiave.

  • 512 KB. La stanza conserva il set di dati, con i suoi collegamenti ai livelli, nelle sue impostazioni, fino a 512 KB. Un set di dati più grande viene rifiutato, mai troncato: Questo set di dati è troppo grande per essere salvato nella stanza.
  • Le suddivisioni si fissano alla costruzione. Una nuova suddivisione, o nuovi confini, richiedono di ricostruire il set di dati. L’analisi di un poligono caricato o disegnato non è disponibile.
  • Ricollegare dopo una clonazione. Clonare o esportare una stanza copia il set di dati, ma i suoi collegamenti alle suddivisioni puntano ancora ai livelli della stanza originale. Ricollegali nella copia, in Impostazioni della stanza → Pannello scientifico — vedi Esportare e importare una stanza.
  • Un formato rigoroso. L’app accetta al massimo 16 specie, 6 suddivisioni, 600 zone per suddivisione, 16 anni di volo e 64 fonti, con etichette fino a 120 caratteri in al massimo 8 lingue.
  • Non in modalità presentazione. La vista di presentazione non mostra il pannello.

Il repository dell’app documenta il resto:

  • docs/features/science-panel.md — il progetto, il contratto del set di dati e le metriche;
  • python-geo-service/science/README.md — i comandi del generatore e del caricamento, e come eseguirne i test;
  • python-geo-service/science/configs/public-room-v1.json — la configurazione di costruzione della stanza pubblica;
  • app/lib/science/science-dataset.ts — il parser che fa rispettare il formato.