Accueil / Format de scène

Format de scène

Référence exhaustive du schéma JSON lu par SceneParser. Chaque clé documentée ici provient directement du parseur (srcs/core/scene/SceneParser.cpp) : rien n'est inventé. Les clés absentes de cette page sont ignorées silencieusement.

Structure d'un fichier

Une scène est un fichier .json (l'extension est vérifiée : tout autre suffixe lève INVALID_FILE_EXTENSION). Le document racine est un objet qui peut contenir quatre sections :

{
  "environment": { "ambient": 0.4, "diffuse": 0.6 },
  "camera":   { "resolution": [1920, 1080], "position": [0,-100,20], "rotation": [0,0,0], "fieldOfView": 72.0 },
  "objects":  [ { "type": "sphere", "position": [60,5,40], "radius": 25 } ],
  "materials": [ { "name": "Rouge", "model": "phong", "base_color": [255,64,64] } ]
}

Section environment

Facultative. Contrôle les coefficients d'éclairage global. Les deux clés doivent être des nombres ; toute valeur non numérique est ignorée et la valeur par défaut est conservée.

Section camera

Obligatoire. Analysée par parseCamera. Quatre clés sont obligatoires ; leur absence (ou une forme invalide) lève une exception qui interrompt le chargement de la scène.

"camera": {
  "resolution": [1920, 1080],
  "position":   [0.0, -100.0, 20.0],
  "rotation":   [0.0, 0.0, 0.0],
  "fieldOfView": 72.0,
  "samplesPerPixel": 128
}

Section objects

Obligatoire : un tableau (sinon « objects must be a list »). Chaque élément est un objet doté d'une clé type (chaîne, obligatoire) qui détermine la primitive, la lumière ou le groupe à construire. Forme générale d'un objet :

{
  "type": "sphere",           // obligatoire — sélectionne le type d'objet
  "name": "Ma sphère",        // facultatif — libellé affiché dans l'interface
  "position": [60, 5, 40],    // propriétés propres au type (voir tableau ci-dessous)
  "radius": 25,
  "material": "Rouge"         // facultatif — nom d'une entrée de "materials"
}

Le parseur applique une table de gestionnaires : pour chaque objet, il parcourt les clés reconnues et n'assigne que celles présentes. Une clé non listée pour ce type (ou totalement inconnue) est ignorée. Si une clé présente a une valeur malformée, l'objet est abandonné (message d'erreur sur stderr) mais le reste de la scène continue de se charger.

Types d'objets et clés reconnues

Valeurs acceptées pour type et clés lues par le parseur pour chacune. Les clés position, rotation, scale, name et material sont acceptées de façon générique ; les colonnes ci-dessous listent les clés spécifiques que chaque type exploite réellement.

Clés génériques additionnelles reconnues par la table de gestionnaires : direction, power, threshold, intensity, iterations, vertices, faces, normals, vertex_overrides. Chaque entrée de vertex_overrides est un objet { "index": n, "position": [x,y,z] } ; une entrée sans index ou sans position lève une erreur.

Conventions de valeurs

Section materials et référence par nom

Facultative : un tableau de matériaux (sinon « materials must be a list »). Chaque entrée doit posséder un name (sans lui : « Missing material name ») et, en général, un model ("phong" ou "pbr"). Un objet réfère un matériau par sa clé material, qui doit correspondre exactement au name d'une entrée de materials.

Exemple complet commenté

Extrait fidèle de tests/configs/subject.json (deux sphères, un plan et une lumière) :

{
  "environment": { "ambient": 0.4, "diffuse": 0.6 },

  "camera": {
    "resolution": [1920, 1080],      // largeur x hauteur en pixels (obligatoire)
    "position":   [0.0, -100.0, 20.0],
    "rotation":   [0.0, 0.0, 0.0],   // degrés (obligatoire)
    "fieldOfView": 72.0,             // degrés (obligatoire)
    "samplesPerPixel": 128           // anti-aliasing (défaut 5)
  },

  "objects": [
    {
      "name": "Sphere A",
      "type": "sphere",
      "position": [60.0, 5.0, 40.0],
      "radius": 25,
      "material": "Material A"        // référence par nom
    },
    {
      "name": "Plane",
      "type": "plane",
      "axis": "z",                    // "x" | "y" | "z" — PAS "normal"/"origin"
      "position": [0.0, 0.0, -20.0],
      "material": "Material C"
    },
    {
      "name": "Point light",
      "type": "point_light",
      "intensity": 1000000.0,
      "position": [400.0, 100.0, 500.0]
    }
  ],

  "materials": [
    // Le modèle est lu depuis "model" (phong | pbr) ; "base_color" en [r,g,b] 0-255.
    { "name": "Material A", "model": "phong", "base_color": [255, 64, 64] },
    { "name": "Material C", "model": "phong", "base_color": [64, 64, 255] }
  ]
}

Messages d'erreur du parseur

Les erreurs fatales interrompent le chargement (exception LoadingSceneException). Les erreurs par objet sont écrites sur stderr et l'objet fautif est simplement omis.