Aller au contenu
FR

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.

GET /api/rooms/:roomId/science

Ré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.

PUT /api/rooms/:roomId/science
Content-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, avec errors: [{ "path", "code" }] (par exemple { "path": "sources[3].measure", "code": "unknown_measure" }) et warnings pour les clés inconnues. La salle garde sa configuration précédente.
  • 503 room_snapshot_unavailable signifie que l’état de la salle n’a pas pu être lu sans risque. Réessayez.

DELETE /api/rooms/:roomId/science supprime la configuration.

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

Prend le même corps que PUT et répond avec les mêmes erreurs, sans rien écrire.

POST /api/rooms/:roomId/science/sample
Content-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 } }] }
  • values contient une valeur par bande. Nodata vaut null, jamais 0. Rien n’est interpolé.
  • cell donne 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).
  • status vaut l’un de :
    • ok ;
    • outside : le point se trouve hors du raster ;
    • warming : le serveur récupère le fichier ; redemandez après retryAfter secondes ;
    • 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.

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] }] }

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 }] }] }
  • count indique combien des cellCount cellules 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 vaut null, jamais 0.
  • Les centiles sont linéaires, std est 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.
  • partial vaut true quand la forme dépasse le raster, et cellSizeM est la taille d’une cellule au sol, en mètres. repaired vaut true quand une forme invalide (qui se recoupe, ou dont des parties se chevauchent) a été réparée avant le comptage.
  • status vaut l’un de :
    • ok ;
    • outside : la forme se trouve hors du raster ;
    • warming : le serveur récupère le fichier ; redemandez après retryAfter secondes ;
    • 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 (windowCells dit combien) ;
    • invalid_band : le raster n’a que bandCount bandes ;
    • 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.