Estendere UFO@home con moduli

Cosa porta un modulo#

Fonti di dati (immagini aeree, rilievo del suolo, meteo, traffico aereo…) e modelli 3D, ognuno con il credito che la sua licenza chiede. Si aggiungono a quelli di UFO@home: nei selettori dell'editor, dopo di essi, e nella scena ovunque una registrazione citi uno dei suoi modelli.

Il manifesto#

Un file JSON, ufoathome-module.json per convenzione, leggibile da altri siti (CORS). I suoi indirizzi relativi si leggono dal suo.

Il manifesto qui sotto è in sola lettura e conosce il suo formato: metti il cursore dentro un oggetto e premi Ctrl+Spazio (⌥+I su Mac) per elencare tutte le chiavi che potrebbero andarci, con ciò che significa ciascuna.

{
  "format": 1,
  "id": "acme",
  "name": "ACME surveys",
  "credit": "© ACME",
  "creditUrl": "https://acme.example",
  "contributes": {
    "imagery": [
      {
        "id": "acme-ortho",
        "name": "ACME ortho",
        "credit": "© ACME",
        "creditUrl": "https://acme.example/licence",
        "tiles": "https://tiles.acme.example/ortho/{z}/{x}/{y}.jpg"
      }
    ],
    "elevation": [
      {
        "id": "acme-relief",
        "name": "ACME relief",
        "credit": "© ACME",
        "creditUrl": "https://acme.example/licence",
        "tiles": "relief/{z}/{x}/{y}.png"
      }
    ],
    "models": [
      {
        "id": "acme-weather-balloon",
        "kind": "entity",
        "name": "Weather balloon",
        "file": "models/balloon.glb",
        "sizeM": {
          "widthM": 2,
          "lengthM": 2,
          "heightM": 2
        },
        "credit": {
          "title": "Weather balloon",
          "author": "ACME",
          "license": "CC BY 4.0",
          "sourceUrl": "https://acme.example/models"
        }
      }
    ]
  },
  "script": "module.js"
}

• imagery: tasselli di immagini comuni, con {z}, {x} e {y} nell'indirizzo nell'ordine che il servizio dà loro.
• elevation: tasselli di rilievo codificati in PNG Terrarium (altezza = R × 256 + G + B / 256 − 32768 m).
• models: file glTF o GLB, ognuno con il suo tipo (vehicle, aircraft, building, entity…), la sua misura e il suo credito, come nel catalogo di UFO@home.
• Un id che un altro modulo o UFO@home dà già nello stesso punto è rifiutato, per tutto il modulo: dai ai tuoi un prefisso tuo.

Quando serve codice#

Un servizio le cui risposte hanno una forma propria richiede codice: script cita un modulo ES il cui export predefinito restituisce implementazioni delle interfacce di src/modules.

// module.js: its default export returns more implementations, at any point.
export default ({ manifestUrl }) => ({
  weather: [{
    id: "acme-weather", name: "ACME weather", credit: "© ACME", creditUrl: "https://acme.example",
    create: () => ({ /* the methods of WeatherProvider */ })
  }]
})

I punti a cui un modulo può aggiungere: weather, place, timeZone, narrative, assessment, lightPollution, aircraft, upperAir, elevation, imagery, surroundings, decorModels, skyEvents, interpretations, perception.

Uno script viene eseguito con tutti i diritti della pagina. Viene eseguito solo per un modulo che la persona ha aggiunto, mai per uno che una registrazione cita.

Simulare un tipo di evento del cielo#

Un tipo di evento del cielo (un fulmine, un razzo, un bengala…) è ciò che una registrazione dichiara sotto skyEvents.<chiave>, disegnato nella scena e modificato in una parte propria del gruppo Cielo. La sua simulation dà alla scena un oggetto three.js e lo colloca a ogni immagine, secondo l'istante e il quadro in cui si trova la scena (dov'è l'occhio, l'aria, il suolo, il vento); non disegna mai da sé. Il quadro dice anche dove si trova davvero il testimone, l'istante reale, la magnitudine più debole visibile, ciò che le nubi e l'aria lasciano passare, e le permette di illuminare il suolo (lightFrom) e di abbagliare l'occhio (glareFrom). Costruiscila con il three che lo script riceve, mai con una copia tua. I lanci, i fasci e i bolidi di UFO@home sono scritti così, in src/modules/sky-events.

// A kind of event of the sky: stated in recordings under skyEvents.ballLightning.
export default ({ three }) => ({
  skyEvents: [{
    id: "ballLightning", name: "Ball lightning", credit: "© ACME", creditUrl: "https://acme.example",
    create: () => ({
      key: "ballLightning",
      title: { en: "Ball lightning", fr: "Foudre en boule" },
      simulation: async () => () => {
        const object = new three.Group()
        return {
          object,
          drawnCount: 0,
          // Places and lights the events at t (ms), from frame.eye; draws nothing itself.
          update(events, t, frame) { /* … */ },
          dispose() { object.removeFromParent() }
        }
      },
      // Optional: the part of the Sky group that edits them.
      editor: async () => (container, host, language) => ({ sync() {}, refresh() {}, setTime(t) {}, async setLanguage(l) {} })
    })
  }]
})

Un tipo di interpretazione#

Una lettura di un resoconto che pochi parametri dichiarano, calcolata in corpi quando viene mostrata (lanterne volanti lasciate da un giardino, bengala esca sganciati da un aereo): dichiarata sotto interpretation.<chiave>, data a interpretations con una key, un title, bodiesOf(item) che restituisce i corpi che è, e un editor facoltativo. Non un fatto del cielo: ciò che qualcuno afferma che il resoconto abbia visto.

Aggiungerne uno nell'editor#

Nel gruppo File, la voce Moduli: scrivi l'indirizzo del manifesto e premi Aggiungi. I tuoi moduli sono conservati in questo browser, possono essere disattivati o rimossi, e salvati in un file (Salva i miei moduli) che li carica altrove (Carica moduli).

Una registrazione che ne ha bisogno#

Una registrazione che disegna un modello di un modulo lo cita, perché chi la apre veda la stessa cosa: l'editor scrive il suo indirizzo nel file appena uno dei suoi modelli viene usato, relativo alla registrazione quando entrambi sono sullo stesso sito, e Citato da questa registrazione lo toglie. Un lettore che non ha aggiunto il modulo riceve ciò che il suo manifesto dichiara, senza il suo script.

{
  "modules": ["https://acme.example/ufo/ufoathome-module.json"]
}

In UFO@home stesso#

Un'implementazione può anche entrare in UFO@home: ogni tipo ha la sua cartella in src/modules, il cui README dice cosa scrivere e dove registrarlo. Una pull request è benvenuta.