Tempusxr English
Menu
  1. Documentation
  2. À propos de Tempusxr

Format de scène v1

Une scène est un fichier JSON qui décrit toute une expérience de RA : quelles images trouver, quoi montrer dessus, et ce qui se passe quand on regarde ou qu'on touche. Le Viewer et le Studio lisent et écrivent ce format, et le SDK le chargera avec loadScene(). Le paquet @tempusxr/scene le vérifie. C'est de la donnée pure : il ne connaît ni les caméras, ni Three.js, ni A-Frame.

Un exemple

{
  "version": 1,
  "id": "poster-chair",
  "tracker": { "kind": "image", "targets": [{ "id": "poster", "file": "poster.txr" }] },
  "assets": [
    { "id": "chair", "type": "model", "src": "chair.glb" },
    { "id": "promo", "type": "video", "src": "promo.mp4", "loop": true }
  ],
  "nodes": [
    { "id": "chair-node", "asset": "chair", "anchor": "poster", "position": [0, 0, 0.1] },
    { "id": "video-node", "asset": "promo", "anchor": "poster", "fit": "image" }
  ],
  "behaviors": [
    { "on": "found", "target": "poster", "do": "play", "node": "video-node" },
    { "on": "tap", "node": "chair-node", "do": "openUrl", "url": "https://example.com/chair" }
  ]
}

Les parties

PartieCe qu'elle contient
trackerComment le contenu est ancré. kind: "image" : un fichier .txr par image (le compilateur d'images les fabrique), et maxTrack, combien sont suivies en même temps. kind: "world" : sans image, voir le suivi du monde.
assetsCe qu'on peut montrer : model (GLB, avec un compression: ["meshopt"] facultatif), image (avec "projection": "equirect" pour une photo 360), video, audio, text et portal (une porte vers un autre monde, voir le guide du portail).
nodesCe qui est posé sur une cible : un asset, une position, une rotation, une échelle. Un nœud sans asset est un groupe, et d'autres nœuds le nomment comme parent.
behaviorsCe qui se passe : found, lost, tap ou load, puis play, pause, show, hide ou openUrl. Un tap nomme le nœud touché avec from (ou node), et le nœud visé avec node. openUrl ne marche qu'avec tap ou press. cover nomme un bouton virtuel (ci-dessous), enter et exit nomment un nœud portail avec from (suivi du monde seulement), et forward et reverse jouent une animation jusqu'à sa fin ou jusqu'à son début.
buttons (dans une cible)Boutons virtuels : des zones imprimées sur l'image, { id, rect: [x, y, largeur, hauteur], sensitivity }, le rectangle en fractions de l'image depuis son coin en haut à gauche. Un comportement cover se déclenche quand un doigt couvre la zone : un poster peut avoir des boutons Éclater et Normal imprimés. La zone demande un motif imprimé pour être bien lue. Une zone compte comme couverte quand environ la moitié est cachée (sensitivity déplace ce seuil). Une seule zone d'une cible est pressée à la fois : une main au-dessus de deux zones presse celle qu'elle couvre le plus. Une zone ne peut pas être pressée pendant ses 0,7 premières secondes après la détection de la cible, ni pendant que la cible bouge vite.
controlsBoutons de l'expérience (type: "button" et un label). Un comportement press en nomme un.
metaUn espace libre pour un titre, une description et la marque du Viewer.

Unités

Les positions et tailles sont en largeurs d'image : 1 est la largeur de l'image cible, et +Z sort de l'image vers vous. Avec un tracker world, elles sont en mètres (+Y vers le haut). Les rotations sont en degrés. Le fichier ne contient aucune matrice.

Adresses

Un src ou un file est un chemin relatif au fichier de scène, ou une adresse https. Tout autre type d'adresse est refusé. Un bouton peut ouvrir des liens https, mailto ou tel.

Vérifier une scène

import { parseScene } from '@tempusxr/scene';

const result = parseScene(json);
if (result.ok) console.log(result.scene.nodes.length);
else for (const issue of result.issues) console.log(issue.code, issue.path, issue.message);

parseScene migre d'abord une scène plus ancienne, puis vérifie la forme, puis les liens entre les identifiants. Elle renvoie tous les problèmes d'un coup et ne lève jamais d'erreur. Chaque problème a un code stable (par exemple unknown-asset, duplicate-id, unsafe-url), un path comme nodes[0].asset, et un message en anglais. Le Studio affiche son propre texte français ou anglais pour chaque code.

Versions

Le fichier dit "version": 1. Quand le format change, la version monte et une migration transforme les anciennes scènes vers la nouvelle version : les scènes faites aujourd'hui continueront de se charger. Une scène d'une version plus récente que celle que connaît le logiciel est refusée avec version-too-new, sans deviner.