Panneau scientifique
La configuration Science d’une salle (comap.science/2, voir Configurer le panneau
scientifique), la lecture en un point sur laquelle reposent ses vues, et les
statistiques dans une forme que lisent les bulles des entités (voir Lire les rasters sous une
entité).
| Méthode | Chemin | Permission du jeton |
|---|---|---|
GET |
/api/rooms/:roomId/science |
read (anonyme dans une salle publique) |
PUT |
/api/rooms/:roomId/science |
write |
DELETE |
/api/rooms/:roomId/science |
write |
POST |
/api/rooms/:roomId/science/validate |
write ; n’enregistre rien |
POST |
/api/rooms/:roomId/science/sample |
read (anonyme dans une salle publique) |
POST |
/api/rooms/:roomId/science/stats |
read (anonyme dans une salle publique) |
Les membres connectés ont besoin des mêmes droits : les propriétaires et les éditeurs écrivent, et toute personne qui voit la salle lit.
Lire la configuration
Section intitulée « Lire la configuration »GET /api/rooms/:roomId/scienceRépond { "settings": null } quand la salle n’en a pas, sinon :
{ "settings": { "version": 2, "config": { "schema": "comap.science/2", "…": "…" }, "bindings": {}, "updatedAt": 1792300000000, "updatedBy": "api-token:my-script" } }updatedBy est l’identifiant client de l’onglet qui a enregistré, ou api-token:<nom> du jeton, jamais
un nom ou une adresse e-mail.
L’enregistrer ou la supprimer
Section intitulée « L’enregistrer ou la supprimer »PUT /api/rooms/:roomId/scienceContent-Type: application/json{ "config": { "schema": "comap.science/2", "…": "…" }, "bindings": { "obs-mean": "tiff-1760000000000-example" } }bindings (facultatif) lie une clé de source à l’identifiant d’une couche raster, pour un nom de couche
ambigu ou qui a changé.
- Une configuration invalide est refusée en bloc et jamais enregistrée en partie :
400 invalid_science_config, avecerrors: [{ "path", "code" }](par exemple{ "path": "sources[3].measure", "code": "unknown_measure" }) etwarningspour les clés inconnues. La salle garde sa configuration précédente. 503 room_snapshot_unavailablesignifie que l’état de la salle n’a pas pu être lu sans risque. Réessayez.
DELETE /api/rooms/:roomId/science supprime la configuration.
Vérifier sans enregistrer
Section intitulée « Vérifier sans enregistrer »POST /api/rooms/:roomId/science/validatePrend le même corps que PUT et répond avec les mêmes erreurs, sans rien écrire.
Lire les valeurs en un point
Section intitulée « Lire les valeurs en un point »POST /api/rooms/:roomId/science/sampleContent-Type: application/json{ "lon": 8.553, "lat": 47.256, "layers": [{ "layerId": "tiff-1760000000000-example" }] }Lit toutes les bandes de 1 à 24 couches raster dans la cellule stockée sous le point :
{ "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 } }] }valuescontient une valeur par bande. Nodata vautnull, jamais0. Rien n’est interpolé.celldonne la colonne et la ligne de la cellule, ses quatre coins en[lon, lat]dans le sens des aiguilles d’une montre depuis le coin supérieur gauche et, pour un raster projeté, sa taille dans les unités du raster (sizeM).statusvaut l’un de :ok;outside: le point se trouve hors du raster ;warming: le serveur récupère le fichier ; redemandez aprèsretryAftersecondes ;not_found: un identifiant inconnu, ou une couche d’une autre salle (les deux réponses sont identiques) ;error.
503 geo_service_busy (avec Retry-After) demande de réessayer plus tard, et 502 sample_failed signifie
que la lecture a échoué. Le point d’accès est limité à 120 requêtes par minute et par appelant.
Lire les statistiques dans une forme
Section intitulée « Lire les statistiques dans une forme »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] }] }Prend un Polygon ou un MultiPolygon GeoJSON en longitude et latitude, et 1 à 8 couches raster avec les
bandes à lire : au plus 16 paires couche–bande en tout, et au plus 5000 positions dans la forme. Pour
chaque bande, il répond par les statistiques des cellules dont le centre se trouve dans la forme, trous
exclus :
{ "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 }] }] }countindique combien descellCountcellules contiennent des données. Les cellules sans données — nodata, masquées ou NaN — sont omises de toutes les statistiques, et s’il n’en reste aucune, chaque statistique vautnull, jamais0.- Les centiles sont linéaires,
stdest l’écart type de la population, et les valeurs sont celles enregistrées, arrondies à 7 chiffres significatifs. - Une forme trop petite pour contenir le centre d’une cellule lit à la place la cellule qui se trouve
dessous (
cellRule: "point"), si bien qu’une petite forme lit quand même sa propre cellule ; cette valeur est celle de la lecture en un point. partialvauttruequand la forme dépasse le raster, etcellSizeMest la taille d’une cellule au sol, en mètres.repairedvauttruequand une forme invalide (qui se recoupe, ou dont des parties se chevauchent) a été réparée avant le comptage.statusvaut l’un de :ok;outside: la forme se trouve hors du raster ;warming: le serveur récupère le fichier ; redemandez aprèsretryAftersecondes ;not_found: un identifiant inconnu, ou une couche d’une autre salle (les deux réponses sont identiques) ;too_large: l’emprise de la forme lirait plus de cellules qu’une requête ne le permet (windowCellsdit combien) ;invalid_band: le raster n’a quebandCountbandes ;error.
Une requête refusée répond 400 avec le premier problème et son emplacement :
{ "error": "invalid_request" | "shape_too_complex" | "invalid_shape", "path": "layers[0].bands[1]" }.
Une forme qui n’a plus aucune surface après réparation donne invalid_shape. Le corps fait au plus
256 Kio (413 au-delà). 503 geo_service_busy (avec Retry-After) demande de réessayer plus tard, et
502 stats_failed signifie que la lecture a échoué. Le point d’accès est limité à 120 requêtes par minute
et par appelant.