Salta ai contenuti
IT

Pannello scientifico

La configurazione Science di una stanza (comap.science/2, vedi Configurare il pannello scientifico), la lettura in un punto su cui si basano le sue viste, e le statistiche in una forma che leggono i popup degli elementi (vedi Leggere i raster sotto un elemento).

Metodo Percorso Permesso del token
GET /api/rooms/:roomId/science read (anonimo in una stanza pubblica)
PUT /api/rooms/:roomId/science write
DELETE /api/rooms/:roomId/science write
POST /api/rooms/:roomId/science/validate write; non salva nulla
POST /api/rooms/:roomId/science/sample read (anonimo in una stanza pubblica)
POST /api/rooms/:roomId/science/stats read (anonimo in una stanza pubblica)

I membri che hanno effettuato l’accesso hanno bisogno degli stessi diritti: proprietari ed editor scrivono, e chiunque possa vedere la stanza legge.

GET /api/rooms/:roomId/science

Risponde { "settings": null } quando la stanza non ne ha una, altrimenti:

{ "settings": { "version": 2, "config": { "schema": "comap.science/2", "…": "…" },
"bindings": {}, "updatedAt": 1792300000000, "updatedBy": "api-token:my-script" } }

updatedBy è l’ID client della scheda che ha salvato, o api-token:<nome> del token, mai un nome o un indirizzo e-mail.

PUT /api/rooms/:roomId/science
Content-Type: application/json
{ "config": { "schema": "comap.science/2", "…": "…" }, "bindings": { "obs-mean": "tiff-1760000000000-example" } }

bindings (facoltativo) lega la chiave di una fonte all’ID di un livello raster, per un nome di livello ambiguo o cambiato.

  • Una configurazione non valida viene rifiutata per intero e mai salvata in parte: 400 invalid_science_config, con errors: [{ "path", "code" }] (per esempio { "path": "sources[3].measure", "code": "unknown_measure" }) e warnings per le chiavi sconosciute. La stanza conserva la configurazione precedente.
  • 503 room_snapshot_unavailable significa che lo stato della stanza non è stato letto in modo sicuro. Riprova.

DELETE /api/rooms/:roomId/science rimuove la configurazione.

POST /api/rooms/:roomId/science/validate

Accetta lo stesso corpo di PUT e risponde con gli stessi errori, senza scrivere nulla.

POST /api/rooms/:roomId/science/sample
Content-Type: application/json
{ "lon": 8.553, "lat": 47.256, "layers": [{ "layerId": "tiff-1760000000000-example" }] }

Legge tutte le bande di 1–24 livelli raster nella cella memorizzata sotto il punto:

{ "layers": [{ "layerId": "tiff-1760000000000-example", "status": "ok", "bandCount": 1, "values": [2.2],
"cell": { "col": 1150, "row": 422, "corners": [[8.5509, 47.2575], [8.5532, 47.2575], [8.5532, 47.2560], [8.5509, 47.2560]], "sizeM": 250 } }] }
  • values contiene un valore per banda. Nodata è null, mai 0. Nulla viene interpolato.
  • cell indica colonna e riga della cella, i suoi quattro angoli come [lon, lat] in senso orario a partire da quello in alto a sinistra e, per un raster proiettato, la sua dimensione nelle unità del raster (sizeM).
  • status è uno tra:
    • ok;
    • outside: il punto è fuori dal raster;
    • warming: il server sta recuperando il file; richiedi dopo retryAfter secondi;
    • not_found: un ID sconosciuto, o un livello di un’altra stanza (le due risposte sono identiche);
    • error.

503 geo_service_busy (con Retry-After) chiede di riprovare più tardi, e 502 sample_failed significa che la lettura non è riuscita. L’endpoint è limitato a 120 richieste al minuto per chiamante.

POST /api/rooms/:roomId/science/stats
Content-Type: application/json
{ "geometry": { "type": "Polygon", "coordinates": [[[8.55, 47.25609], [8.55013, 47.25609],
[8.55013, 47.256], [8.55, 47.256], [8.55, 47.25609]]] },
"layers": [{ "layerId": "tiff-1760000000000-example", "bands": [1] }] }

Accetta un Polygon o un MultiPolygon GeoJSON in longitudine e latitudine, e da 1 a 8 livelli raster con le bande da leggere: al massimo 16 coppie livello–banda in tutto, e al massimo 5000 posizioni nella forma. Per ogni banda risponde con le statistiche delle celle il cui centro cade dentro la forma, buchi esclusi:

{ "repaired": false, "layers": [{ "layerId": "tiff-1760000000000-example", "status": "ok", "bandCount": 1,
"cellCount": 25, "cellRule": "centre", "partial": false, "cellSizeM": 2,
"bands": [{ "band": 1, "count": 25, "mean": 0.4312, "median": 0.4357, "p10": 0.3904, "p90": 0.4655,
"min": 0.3725, "max": 0.4801, "std": 0.0291 }] }] }
  • count indica quante delle cellCount celle contengono dati. Le celle senza dati — nodata, mascherate o NaN — sono escluse da ogni statistica, e se non ne resta nessuna, ogni statistica è null, mai 0.
  • I percentili sono lineari, std è la deviazione standard della popolazione, e i valori sono quelli memorizzati, arrotondati a 7 cifre significative.
  • Una forma troppo piccola per contenere il centro di una cella legge invece la cella sottostante (cellRule: "point"), così anche una forma piccola legge la propria cella; quel valore è uguale a quello della lettura in un punto.
  • partial è true quando la forma va oltre il raster, e cellSizeM è la dimensione di una cella sul terreno, in metri. repaired è true quando una forma non valida (che si autointerseca, o con parti sovrapposte) è stata riparata prima del conteggio.
  • status è uno tra:
    • ok;
    • outside: la forma è fuori dal raster;
    • warming: il server sta recuperando il file; richiedi dopo retryAfter secondi;
    • not_found: un ID sconosciuto, o un livello di un’altra stanza (le due risposte sono identiche);
    • too_large: il riquadro che contiene la forma leggerebbe più celle di quante una richiesta ne consenta (windowCells dice quante);
    • invalid_band: il raster ha solo bandCount bande;
    • error.

Una richiesta rifiutata risponde 400 con il primo problema e dove si trova: { "error": "invalid_request" | "shape_too_complex" | "invalid_shape", "path": "layers[0].bands[1]" }. Una forma senza alcuna area dopo la riparazione è invalid_shape. Il corpo è al massimo di 256 KiB (413 oltre). 503 geo_service_busy (con Retry-After) chiede di riprovare più tardi, e 502 stats_failed significa che la lettura non è riuscita. L’endpoint è limitato a 120 richieste al minuto per chiamante.