Le fichier d'observation

Un enregistrement est un simple fichier JSON. Rien dedans n'est un blob binaire, un identifiant dans une base de données, ni une référence à ce site — vous pouvez en écrire un à la main, en engendrer depuis vos propres archives, ou en comparer deux dans une relecture de code.

Chaque extrait ci-dessous est en lecture seule, et chacun connaît le format : placez le curseur dans un objet et faites Ctrl+Espace (⌥+I sur Mac) pour lister toutes les clés qui pourraient y figurer, avec ce que le modèle dit de chacune.

L'observation#

Plusieurs observateurs : le dossier#

Chaque observateur a son propre enregistrement, et un enregistrement ne dit pas à quel dossier il appartient : un compte rendu se suffit à lui-même. Ce qui les montre ensemble est le dossier, qui les désigne : le case.json d'un dossier RR0, qui énonce le titre, la date et la classification du cas, et liste tout ce qui lui est arrivé en events. Ses événements de type sighting sont ses comptes rendus, chacun pointant vers l'enregistrement d'un observateur :

{
  "id": "ChilesWhitted",
  "title": "Chiles et Whitted",
  "time": "1948-07-24 02:45",
  "events": [
    { "type": "event", "eventType": "sighting", "url": "observer-chiles.json" },
    { "type": "event", "eventType": "sighting", "url": "observer-whitted.json" }
  ]
}

Donnez-le à <rr0-sighting src> ou au lecteur, et chaque observateur se choisit dans une liste. Un enregistrement peut être donné directement, sans dossier, mais un dossier à un seul compte rendu marche de la même façon et nomme ce qu'il montre. Essayez avec case-chiles-whitted.json (le jouer).

Le dire en plusieurs langues#

Un enregistrement se transmet d'un lecteur à un autre : chaque champ écrit par un auteur peut donc porter une chaîne par langue au lieu d'une seule — description, le title d'une forme ou d'un élément de décor, le label et la note d'un repère.

{
  "description": {
    "fr": "Tout le compte rendu de Lonnie Zamora, d'un seul tenant…",
    "en": "Lonnie Zamora's whole account, of a piece…"
  }
}

Les clés sont des étiquettes de langue telles qu'un navigateur les donne (fr, en, pt-BR), et aucune n'est obligatoire. Une chaîne simple reste parfaitement valide et signifie « dans la langue où cela a été écrit » — ce qu'est tout enregistrement antérieur. Un lecteur dont aucune langue n'est présente reçoit ce que le fichier A, plutôt qu'un champ vide : une traduction manquante ne doit jamais transformer ce qu'un observateur a dit en ce qu'il n'a pas dit.

La langue reçue est celle du navigateur, sauf si la page en dit autre chose : un lang sur l'élément lui-même, ou sur ce qui l'entoure, est pris d'abord — un article qui déclare sa langue a déjà énoncé dans quelle langue son lecteur le lit. La liste du navigateur vient ensuite : déclarer une langue force donc un choix sans jeter les autres.

L'éditeur montre une langue, celle du lecteur, et n'écrit que dans celle-là — ouvrir le fichier dans l'autre langue et taper est donc la façon d'ajouter une traduction, et un auteur ne peut pas effacer celle d'un autre.

Ce qui a été vu#

timeline.keyframes est une liste de { t, shapes }, t en millisecondes depuis le début. Chaque forme porte un sourceId — plusieurs formes peuvent partager une chronologie (le phénomène, une flamme qui traîne, une seconde lumière) — et une shape :

{
  "kind": "oval",
  "bounds": { "x": 0, "y": 0, "width": 0, "height": 0 },
  "color": "#39ff14",
  "angle": 0,
  "transparency": 0,
  "haloScale": 1.5,
  "brightness": 0,
  "blur": 0,
  "selected": false,
  "title": "le phénomène",
  "angular": { "widthDeg": 1.2, "heightDeg": 0.4 },
  "aim": { "azimuthDeg": 353.6, "altitudeDeg": 0.6 }
}

aim le place, angular le dimensionne. bounds est la projection des deux sur le canevas fixe de 640×360, au cap et au champ de la pose, à travers l'instrument de l'enregistrement ; il est redérivé au chargement, si bien qu'un fichier survit à un changement de canevas, de champ, d'instrument, ou de direction du regard. Si les pixels et les angles divergent, les angles gagnent : déplacer bounds dans un fichier ne fait rien tant que aim est là. Un fichier écrit à la main peut omettre bounds entièrement.

timeline.order est l'ordre de tracé de l'arrière vers l'avant, timeline.groups les identifiants groupés. Les deux sont facultatifs.

Tout ce qu'il y a autour#

Un objet du décor s'énonce en mètres, comme tout ce qui n'est pas le phénomène :

Ce que c'était : les interprétations#

Un enregistrement énonce des angles, et un corps en mètres ne fait jamais partie de ce qui a été vu. C'est une affirmation à son sujet, et elle se met à l'épreuve en la posant dans la scène et en la regardant depuis l'endroit où se tenait l'observateur : elle projette son ombre, le sol peut la cacher, et son contour est confronté à chaque instant à ce que l'observateur a dit. Une interprétation s'affiche seule, comme le monde qu'elle affirme ; quand on demande la comparaison (le bouton ◌, ou compare-account sur <rr0-sighting>), le lecteur dessine à côté tout ce que l'observateur a vu, en contours pointillés, et indique l'écart de direction et combien de fois plus large et plus haut chaque corps paraît, en rouge quand un observateur n'aurait pas pu se tromper d'autant.

La lecture de l'observateur lui-même va dans l'enregistrement, en interpretation. Celle d'un autre n'est pas dans le compte rendu : c'est une autre observation, listée dans le dossier (voir plus bas). Un compte rendu dont l'observateur a dit ce que c'était se dessine en volume, comme il l'a dit ; celui qui ne dit rien en mètres se dessine avec les angles qu'il énonce. Le lecteur le propose, ainsi que chaque interprétation d'analyste, une à la fois.

{
  "interpretation": {
    "title": "Un engin posé sur ses pieds",
    "bodies": [{
      "id": "craft",
      "explains": ["ufo-1"],
      "model": { "id": "ellipsoid" },
      "track": [
        { "t": 52000, "eastM": -571.6, "northM": -965.5, "onGround": true,
          "sizeM": { "widthM": 3.36, "lengthM": 3.36, "heightM": 1.73 },
          "appearance": { "color": "#e8e6df", "albedo": 0.7 } },
        { "t": 83000, "azimuthDeg": 195.9, "altitudeDeg": 4.1, "distanceM": 44 }
      ]
    }]
  }
}

Une autre lecture : une interprétation est une autre observation#

La lecture qu'un autre fait d'un compte rendu (celle d'un analyste, d'un enquêteur, une comparaison faite pour la mettre à l'épreuve) n'est pas dans le compte rendu : c'est une autre observation, celle qui a eu lieu telle que son auteur la tient. Elle est donc listée dans le dossier comme l'original, en événement de type sighting, marqué comme lecture par interpretationOf, et a un enregistrement à elle à url :

{
  "id": "McMinnville1950",
  "events": [
    { "type": "event", "eventType": "sighting", "id": "trent", "title": "Paul Trent", "url": "observer-mcminnville.json" },
    { "type": "event", "eventType": "sighting",
      "interpretationOf": "trent",
      "time": "2013-06",
      "by": [{ "people": "CousynAntoine" }, { "people": "LouangeFrancois" }],
      "title": "A model on a thread under the line",
      "url": "interpretation-mcminnville-2.json" }
  ]
}

L'enregistrement à url est un enregistrement comme les autres. Il partage le lieu, l'heure et la pose de l'observateur du compte rendu qu'il lit, si bien qu'un corps placé depuis l'observateur, ou en mètres depuis l'endroit où il se tenait, veut dire la même chose dans les deux ; il ne dessine aucune forme (une timeline vide) ; et il porte les corps dans son propre interpretation, décrit plus haut. Les explains d'un corps désignent les formes du compte rendu.

{
  "version": 1,
  "id": "1950-05-11-TrentPaul-interpretation-2",
  "time": { "year": 1950, "month": 5, "day": 11, "hour": 19, "minute": 45 },
  "utcOffsetHours": -7,
  "place": [{ "value": { "lat": 45.104167, "lng": -123.330556 } }],
  "observerTrack": { "keyframes": [{ "t": 0, "pose": { "lat": 45.104167, "lng": -123.330556, "headingDeg": 41.3, "pitchDeg": 14.85, "fovDeg": 33.4 } }] },
  "tags": ["interpretation"],
  "timeline": { "keyframes": [], "order": [], "groups": [] },
  "interpretation": {
    "title": "A model on a thread under the line",
    "bodies": [{
      "id": "model",
      "explains": ["ufo-1"],
      "model": { "id": "disc" },
      "track": [
        { "t": 0, "eastM": -52, "northM": 118, "altitudeAboveGroundM": 7.5,
          "sizeM": { "widthM": 0.3, "lengthM": 0.3, "heightM": 0.1 } }
      ]
    }]
  }
}

Le lecteur liste les observateurs du dossier d'après les événements sans interpretationOf et propose chaque lecture à côté du compte rendu qu'elle désigne, une à la fois (le bouton ◌ la mesure contre le compte rendu). Un enregistrement seul n'a d'autre lecture que son propre interpretation. L'ancienne forme, un événement de type interpretation qui désigne l'enregistrement dans sighting avec ses corps sur place ou dans un fichier à url, est encore lue. L'éditeur ouvre un dossier : son sélecteur au-dessus du rendu liste les comptes rendus et les lectures, chacun s'ouvrant comme l'enregistrement qu'il est, avec un bouton pour ajouter une lecture (un nouvel enregistrement qui partage le lieu, l'heure et la pose du compte rendu, et un événement pour lui), un pour la supprimer, et un pour exporter le dossier et chaque enregistrement ajouté ou modifié en zip. Essayez avec case-mcminnville.json (le jouer, l'éditer).

La météo, et ses nuages#

Un point weather énonce l'état du ciel à un instant de l'horloge de l'enregistrement ; entre deux points chaque nombre est interpolé, le type de précipitation et l'orage sont maintenus. Il porte :

Chaque couche de cloudLayers est une nappe de nuages à une hauteur réelle, et reste elle-même d'un point à l'autre :

Un nuage individuel dans instances est un nuage de sa couche que le fichier place exactement, parce que le récit le fait : celui derrière lequel le phénomène est passé, celui qui était là et nulle part ailleurs. Il est dessiné comme un nuage de sa couche — même texture, même seuil — et ne se distingue de ses voisins que par sa position et sa taille ; il est là même quand la coverage de la couche est nulle. Il suit le vent de la couche comme les autres, et il masque un phénomène devant lequel il passe.

{
  "weather": {
    "cloudLayers": [
      {
        "id": "low", "type": "cumulus",
        "baseM": 1500, "thicknessM": 800,
        "coverage": 0.55, "sizeM": 1400, "density": 1, "darkness": 0.15,
        "instances": [
          { "id": "the-one", "eastM": 0, "northM": 4200,
            "baseM": 1500, "thicknessM": 800,
            "widthM": 1900, "depthM": 1300, "rotationDeg": 12, "density": 1 }
        ]
      },
      { "id": "high", "type": "cirrus", "baseM": 8000, "thicknessM": 400,
        "coverage": 0.2, "sizeM": 2200, "density": 0.35, "iceCrystalAlignment": 0.65 }
    ],
    "precipitationType": "none", "precipitationIntensity": 0,
    "windDirectionDeg": 90, "windSpeed": 5, "storm": false
  }
}

Un enregistrement dont la météo a été relevée (il a un weatherSource) garde la réponse du relevé, pas un lien vers lui : ERA5 donne les bandes basse, moyenne et haute en trois couches nommées record-low, record-mid et record-high, la base basse estimée depuis l'écart entre température et point de rosée, les deux autres à 3 500 m et 8 000 m. Leur type est unknown (cirrus pour la haute), leur taille et leur densité sont des hypothèses de dessin : une réanalyse sait quelle part de chaque bande était couverte, pas à quoi les nuages ressemblaient. Redemandez le relevé depuis l'éditeur et les couches sont réécrites ; modifiez une couche à la main et l'enregistrement devient celui de l'auteur, la source retirée.

D'où vient chaque valeur#

Toute valeur d'un enregistrement peut s'écrire nue, ou enveloppée de sa provenance :

{
  "durationSeconds": {
    "value": 15,
    "basis": "derived",
    "rationale": "13 à 18 s dans la synthèse de l'enquêteur ; le milieu retenu"
  }
}

basis vaut stated (l'observateur l'a dit, et c'est ce que signifie une valeur nue), derived (déduit de ce qu'il a dit et de quelque chose de vérifiable : la largeur d'une route, une carte, un dessin mesuré ; rationale donne le calcul) ou assumed (choisi pour que la reconstitution ait une valeur, sur rien que l'observateur ait dit). La liste des valeurs assumed est la liste de ce qu'il faut retourner demander à l'observateur ou au dossier : c'est pourquoi elle vaut d'être écrite même quand rien d'autre ne l'est.

Vérifier un fichier#

Le format est aussi publié en JSON Schema, engendré depuis les mêmes types que le lecteur : toutes les clés qu'il connaît, ce que chacune peut contenir, et les mots qu'accepte une liste fermée. Une clé mal orthographiée ou une valeur inconnue y échoue. Il ne dit rien de ce qui peut être omis, question de sens à laquelle répond cette page. Pour voir le résultat, ouvrez le fichier dans le lecteur, depuis un lien, ou depuis votre disque avec les images et modèles qu'il nomme. Le lecteur le vérifie de la même façon au chargement, et dit derrière un ⚠ sur l'image ce qu'il n'a pas pu jouer comme écrit : une clé que rien ne lit, un mot hors de sa liste, et ce qu'il a dû inventer parce que la première keyframe d'une forme l'omettait (un champ tenu depuis la keyframe précédente relève de la règle ci-dessus, pas d'un problème).

Un fichier entier#

Le plus petit enregistrement qui énonce encore quelque chose — un ovale silencieux traversant le ciel en douze secondes, à une date réelle et en un lieu réel. Tout le reste du format est facultatif, et tout ce qui suit sert à quelque chose :

{
  "version": 1,
  "description": "The smallest recording that still states something: one silent orange oval, a degree and a half wide, crossing the south-western sky from left to right over twelve seconds.",
  "time": { "year": 2024, "month": 8, "day": 12, "hour": 22, "minute": 30 },
  "durationSeconds": 12,
  "utcOffsetHours": 2,
  "place": [{ "lat": 45.19, "lng": 5.72, "name": "Grenoble, Isère, France" }],
  "timeline": {
    "keyframes": [
      {
        "t": 0,
        "shapes": [
          {
            "sourceId": "ufo-1",
            "shape": {
              "kind": "oval",
              "bounds": { "x": 150, "y": 150, "width": 10, "height": 3 },
              "angular": { "widthDeg": 1.6, "heightDeg": 0.5 },
              "color": "#ff8c1a",
              "angle": 0,
              "transparency": 0,
              "haloScale": 1.2,
              "selected": false
            }
          }
        ]
      },
      {
        "t": 12000,
        "shapes": [
          {
            "sourceId": "ufo-1",
            "shape": {
              "kind": "oval",
              "bounds": { "x": 480, "y": 130, "width": 10, "height": 3 },
              "angular": { "widthDeg": 1.6, "heightDeg": 0.5 },
              "color": "#ff8c1a",
              "angle": 0,
              "transparency": 0,
              "haloScale": 1.2,
              "selected": false
            }
          }
        ]
      }
    ]
  },
  "observerTrack": {
    "keyframes": [
      {
        "t": 0,
        "pose": { "lat": 45.19, "lng": 5.72, "elevationM": 0, "headingDeg": 215, "pitchDeg": 20, "fovDeg": 60 }
      }
    ]
  },
  "soundTrack": { "keyframes": [{ "t": 0, "sound": { "kind": "none", "volume": 0, "pitchHz": 100 } }] }
}

Pour le modifier et le voir jouer, collez-le dans l'éditeur, qui complète sur chaque clé du format, propose les mots que chacune accepte, et dit ce que le modèle en dit.

C'est /demo-data/example-minimal.json sur ce site : vous pouvez le récupérer, et le jouer avant d'y toucher. Remarquez que angular et bounds y figurent tous deux : l'angle est ce que le fichier SIGNIFIE, et les pixels en sont redérivés au chargement — écrivez l'angle, et laissez corriger une mauvaise estimation des pixels.

De plus gros, à lire#

Chaque démo de ce site est un simple fichier que vous pouvez ouvrir. Ces quatre-là valent la lecture pour voir comment un vrai enregistrement est bâti :

Quatre règles qui décident du sens d'un fichier#

• Les champs discrets sont tenus, les continus sont interpolés. Une forme absente d'un keyframe ultérieur reste dans son état, et de même tout champ qu'un keyframe omet dans une forme qu'il énonce : un keyframe qui ne donne qu'un nouvel aim déplace la forme et garde tout le reste (énoncer bounds sans aim ni angular est lu comme la déplacer par ses pixels) ; une forme dont le premier keyframe est à cinq secondes est déjà peinte, dans cet état, dès zéro. Pour qu'une chose cesse d'être visible, posez-lui un keyframe à transparency: 1.
• Des angles, rien d'autre. Aucune taille ni distance réelle n'est stockée où que ce soit. Les mètres sont déduits, en inégalités, de ce que le phénomène a été déclaré passer derrière ou devant (decor[].occludesSourceIds).
• L'énoncé l'emporte sur le déduit. occludesSourceIds contient des affirmations de l'observateur. Rien dans ce format ne peut les déduire : il décrit une apparence dans un champ de vision, pas une position dans l'espace.
• Absent n'est pas zéro. Pas de piste sonore signifie que personne n'a posé la question ; kind: "none" signifie que l'observateur a déclaré n'avoir rien entendu. La même distinction traverse la météo et les nuages de glace.

Cette page est la référence du format. Le raisonnement derrière chaque champ est dans les commentaires de documentation de son type, que les extraits ci-dessus proposent à la complétion, et dans le code source.