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.
Leggere la configurazione
Sezione intitolata “Leggere la configurazione”GET /api/rooms/:roomId/scienceRisponde { "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.
Salvarla o rimuoverla
Sezione intitolata “Salvarla o rimuoverla”PUT /api/rooms/:roomId/scienceContent-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, conerrors: [{ "path", "code" }](per esempio{ "path": "sources[3].measure", "code": "unknown_measure" }) ewarningsper le chiavi sconosciute. La stanza conserva la configurazione precedente. 503 room_snapshot_unavailablesignifica che lo stato della stanza non è stato letto in modo sicuro. Riprova.
DELETE /api/rooms/:roomId/science rimuove la configurazione.
Verificare senza salvare
Sezione intitolata “Verificare senza salvare”POST /api/rooms/:roomId/science/validateAccetta lo stesso corpo di PUT e risponde con gli stessi errori, senza scrivere nulla.
Leggere i valori in un punto
Sezione intitolata “Leggere i valori in un punto”POST /api/rooms/:roomId/science/sampleContent-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 } }] }valuescontiene un valore per banda. Nodata ènull, mai0. Nulla viene interpolato.cellindica 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 doporetryAftersecondi;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.
Leggere le statistiche in una forma
Sezione intitolata “Leggere le statistiche in una forma”POST /api/rooms/:roomId/science/statsContent-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 }] }] }countindica quante dellecellCountcelle contengono dati. Le celle senza dati — nodata, mascherate o NaN — sono escluse da ogni statistica, e se non ne resta nessuna, ogni statistica ènull, mai0.- 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ètruequando la forma va oltre il raster, ecellSizeMè la dimensione di una cella sul terreno, in metri.repairedètruequando 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 doporetryAftersecondi;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 (windowCellsdice quante);invalid_band: il raster ha solobandCountbande;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.