El archivo de avistamiento

Una grabación es un simple archivo JSON. Nada en ella es un blob binario, un identificador de una base de datos ni una referencia a este sitio — puedes escribir una a mano, generarla desde tu propio archivo, o comparar dos en una revisión de código.

Cada extracto de abajo es de solo lectura, y cada uno conoce el formato: sitúa el cursor dentro de un objeto y pulsa Ctrl+Espacio (⌥+I en un Mac) para listar todas las claves que podrían ir allí, con lo que el modelo dice de cada una.

La observación#

Varios observadores: el caso#

Cada observador tiene su propia grabación, y una grabación no dice a qué caso pertenece: un relato se sostiene por sí solo. Lo que los muestra juntos es el caso, que los nombra: el case.json de un expediente de RR0, que indica el título, la fecha y la clasificación del caso, y enumera todo lo que ocurrió en él como events. Sus eventos de tipo sighting son sus relatos, cada uno apuntando a la grabación de un observador:

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

Dáselo a <rr0-sighting src> o al reproductor, y cada observador podrá elegirse de una lista. Una grabación puede darse directamente, sin caso, pero un caso con un solo avistamiento funciona igual y nombra lo que muestra. Pruébalo con case-chiles-whitted.json (reproducirlo).

Decirlo en más de un idioma#

Una grabación pasa de un lector a otro, así que cada campo que escribe un autor puede contener una cadena por idioma en lugar de una sola: description, el title de una forma o de un elemento del decorado, y el label y la note de un hito.

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

Las claves son etiquetas de idioma tal como las da un navegador (fr, en, pt-BR), y ninguna es obligatoria. Una cadena simple sigue siendo perfectamente válida y significa “en el idioma en que se escribiera” — lo que es toda grabación hecha antes de esto. Un lector cuyos idiomas no son ninguno de los presentes recibe lo que el archivo SÍ tiene en lugar de un campo vacío: una traducción que falta nunca debe convertir algo que el observador dijo en algo que no dijo.

El idioma que recibe un lector es el de su navegador, salvo que la página diga otra cosa: un lang en el propio elemento, o en cualquier cosa a su alrededor, se toma primero — un artículo que declara su propio idioma ya ha dicho en qué idioma lo está leyendo su lector. La lista del navegador viene después, así que declarar uno fuerza una elección sin descartar los demás.

El editor muestra un idioma, el del lector, y al escribir solo toca ese — así que abrir un archivo en el otro idioma y escribir es como se añade una traducción, y un autor no puede borrar la de otro.

Lo que se vio#

timeline.keyframes es una lista de { t, shapes }, con t en milisegundos desde el inicio. Cada forma lleva un sourceId — varias formas pueden compartir una línea de tiempo (el fenómeno, una llama que lo sigue, una segunda luz) — y una 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": "el fenómeno",
  "angular": { "widthDeg": 1.2, "heightDeg": 0.4 },
  "aim": { "azimuthDeg": 353.6, "altitudeDeg": 0.6 }
}

aim lo sitúa, angular lo dimensiona. bounds es la proyección de ambos sobre el lienzo fijo de 640×360 con el rumbo y el campo de visión de la pose, a través del propio instrumento de la grabación; se vuelve a derivar al cargar, así que un archivo sobrevive a un cambio de lienzo, de campo de visión, de instrumento, o de hacia dónde miraba el observador. Si los píxeles y los ángulos llegan a discrepar, ganan los ángulos: mover bounds en un archivo no hace nada mientras aim esté ahí. Un archivo escrito a mano puede omitir bounds por completo.

timeline.order es el orden de pintado de atrás hacia delante, timeline.groups los identificadores de fuente agrupados. Ambos opcionales.

Todo lo que lo rodea#

Un elemento del decorado se expresa en metros, como todo lo que no es el fenómeno:

Lo que era: interpretaciones#

Una grabación expresa ángulos, y un cuerpo en metros nunca forma parte de lo que se vio. Es una afirmación sobre ello, y se pone a prueba colocándola en la escena y mirándola desde donde estaba el observador: proyecta su sombra, el suelo puede ocultarla, y su contorno se mide en cada instante frente a lo que dijo el observador. Una interpretación se muestra sola, como el mundo que afirma; si se pide comparar (el botón ◌, o compare-account en <rr0-sighting>), el reproductor dibuja a su lado todo lo que vio el observador como contornos discontinuos e indica cuánto se desvía la dirección y cuántas veces más ancho y más alto parece cada cuerpo, en rojo cuando un observador no podría haberse equivocado tanto.

La lectura del propio observador va en la grabación, como interpretation. La de otro no está en el relato: es otra observación, listada en el caso (véase abajo). Un relato cuyo observador dijo lo que era se dibuja en volumen, como lo dijo; uno que no dice nada en metros se dibuja como los ángulos que expresa. El reproductor lo ofrece, junto con la interpretación de cada analista, una cada vez.

{
  "interpretation": {
    "title": "Una nave posada sobre sus patas",
    "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 }
      ]
    }]
  }
}

Otra lectura: una interpretación es otra observación#

La lectura que otro hace de un relato (la de un analista, de un investigador, una comparación hecha para ponerla a prueba) no forma parte del relato: es otra observación, la que ocurrió tal como la sostiene su autor. Por eso se lista en el caso como el original, como un evento de tipo sighting, marcado como lectura con interpretationOf, y tiene una grabación propia en 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" }
  ]
}

La grabación en url es una grabación como las demás. Comparte el lugar, la hora y la pose del observador del relato que lee, de modo que un cuerpo situado desde el observador, o en metros desde donde estaba, significa lo mismo en ambas; no dibuja ninguna forma (una timeline vacía); y guarda los cuerpos en su propia interpretation, descrita arriba. El explains de un cuerpo nombra las formas del relato.

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

El reproductor lista los observadores del caso a partir de los eventos sin interpretationOf y ofrece cada lectura junto al relato que nombra, una cada vez (el botón ◌ la mide contra el relato). Una grabación sola no tiene más lectura que su propia interpretation. La forma antigua, un evento de tipo interpretation que nombra la grabación en sighting con sus cuerpos en línea o en un archivo en url, se sigue leyendo. El editor abre un caso: su selector sobre el render lista los relatos y las lecturas, cada uno abriéndose como la grabación que es, con un botón para añadir una lectura (una grabación nueva que comparte el lugar, la hora y la pose del relato, y un evento para ella), otro para eliminarla, y otro para exportar el caso y cada grabación añadida o modificada en un zip. Pruébalo con case-mcminnville.json (reproducirlo, editarlo).

El tiempo, y sus nubes#

Un fotograma clave weather expresa las condiciones del cielo en un momento del reloj de la grabación; entre dos fotogramas clave cada número se interpola, y el tipo de precipitación y la tormenta se mantienen. Contiene:

Cada capa de cloudLayers es un manto de nubes a una altura real, y sigue siendo ella misma de un fotograma clave al siguiente:

Una nube individual en instances es una nube de su capa que el archivo sitúa con exactitud, porque el relato lo hizo: aquella tras la que pasó el fenómeno, la que estaba allí y en ningún otro sitio. Se dibuja como una más de su capa — la misma textura, el mismo umbral —, sin distinguirse de sus vecinas más que por dónde está y lo grande que es, y está ahí incluso cuando la coverage de la capa es nula. Se desplaza con el viento de la capa como las demás, y oculta un fenómeno ante el que pasa.

{
  "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
  }
}

Una grabación cuyo tiempo fue consultado (tiene un weatherSource) guarda la respuesta del registro, no un enlace a él: ERA5 da las bandas baja, media y alta como tres capas llamadas record-low, record-mid y record-high, la base baja estimada a partir de la diferencia entre temperatura y punto de rocío, las otras dos a 3 500 m y 8 000 m. Su tipo es unknown (cirro para la alta), su tamaño y su densidad son supuestos de dibujo: un reanálisis sabe qué parte de cada banda estaba cubierta, no qué aspecto tenían las nubes. Vuelve a pedir el registro desde el editor y las capas se reescriben; edita una capa a mano y la grabación pasa a ser del autor, y la fuente se elimina.

De dónde viene cada valor#

Cualquier valor de una grabación puede escribirse tal cual, o envuelto con su procedencia:

{
  "durationSeconds": {
    "value": 15,
    "basis": "derived",
    "rationale": "De 13 a 18 s en la síntesis del investigador; se toma el punto medio"
  }
}

basis es stated (lo dijo el observador, y es lo que significa un valor sin envolver), derived (deducido de lo que dijo más algo comprobable: la anchura de una carretera, un mapa, un dibujo medido; rationale da el razonamiento) o assumed (elegido para que la reconstrucción tenga un valor, sin base en nada de lo que dijo el observador). La lista de valores assumed es la lista de lo que hay que volver a preguntar al observador o buscar en el expediente, y por eso vale la pena escribirla incluso cuando no se escribe nada más.

Comprobar un archivo#

El formato se publica también como JSON Schema, generado a partir de los mismos tipos que el reproductor: todas las claves que conoce, lo que puede contener cada una, y las palabras que acepta una lista cerrada. Una clave mal escrita o un valor desconocido no lo superan. No dice nada de lo que puede omitirse, que es una cuestión de sentido que responde esta página. Para ver el resultado, abre el archivo en el reproductor, desde un enlace, o desde tu disco con las imágenes y los modelos que nombra. El reproductor lo comprueba del mismo modo al cargar, e indica tras un ⚠ sobre la imagen lo que no pudo reproducir tal como está escrito: una clave que nada lee, una palabra fuera de su lista, y lo que tuvo que inventar porque el primer fotograma clave de una forma lo omitía (un campo mantenido desde el fotograma clave anterior es la regla de arriba, no un problema).

Un archivo completo#

La grabación más pequeña que aún expresa algo — un óvalo silencioso que cruza el cielo en doce segundos, en una fecha real y en un lugar real. Todo lo demás del formato es opcional, y todo lo que sigue cumple una función:

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

Para modificarlo y verlo reproducirse, pégalo en el editor, que completa cada clave que tiene el formato, ofrece las palabras que acepta cada una, y dice lo que el modelo dice de ella.

Es /demo-data/example-minimal.json en este sitio, así que puedes descargarlo, y reproducirlo antes de cambiar nada. Observa que aparecen tanto angular como bounds: el ángulo es lo que el archivo SIGNIFICA, y los píxeles se vuelven a derivar de él al cargar — escribe el ángulo, y deja que se te corrija una estimación errónea de los píxeles.

Otros más grandes para leer#

Cada demo de este sitio es un simple archivo que puedes abrir. Estos cuatro son los que vale la pena leer para ver cómo se construye una grabación real:

Cuatro reglas que deciden lo que significa un archivo#

• Los campos discretos se mantienen, los continuos se interpolan. Una forma omitida en un fotograma clave posterior se queda como estaba, y lo mismo cualquier campo que un fotograma clave omita en una forma que sí vuelve a indicar: un fotograma clave que solo da un nuevo aim mueve la forma y conserva todo lo demás (volver a indicar bounds sin aim ni angular se entiende como moverla por sus píxeles); una cuyo primer fotograma clave está a los cinco segundos ya está pintada, en ese estado, desde cero. Para que algo deje de ser visible, ponle un fotograma clave con transparency: 1.
• Solo ángulos. No se guarda en ninguna parte ningún tamaño real ni ninguna distancia real. Los metros se deducen, como desigualdades, de aquello por detrás o por delante de lo cual se dijo que pasó el fenómeno (decor[].occludesSourceIds).
• Lo declarado prevalece sobre lo deducido. occludesSourceIds registra afirmaciones del observador. Nada en este formato puede deducirlas: describe una apariencia en un campo de visión, no una posición en el espacio.
• Ausente no es cero. Que no haya pista de sonido significa que nadie preguntó; kind: "none" significa que el observador declaró no haber oído nada. La misma distinción recorre el tiempo y la nube de hielo.

Esta página es la referencia del formato. El razonamiento detrás de cada campo está en los comentarios de documentación de su tipo, con los que completan los extractos de arriba, y en el código fuente.