Home / Scene format

Scene format

Exhaustive reference for the JSON schema read by SceneParser. Every key documented here comes straight from the parser (srcs/core/scene/SceneParser.cpp) : nothing is invented. Keys not listed on this page are silently ignored.

File structure

A scene is a .json file (the extension is checked : any other suffix throws INVALID_FILE_EXTENSION). The root document is an object that may contain four 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": "Red", "model": "phong", "base_color": [255,64,64] } ]
}

The environment section

Optional. Controls the global lighting coefficients. Both keys must be numbers ; any non-numeric value is ignored and the default is kept.

The camera section

Required. Parsed by parseCamera. Four keys are required ; their absence (or an invalid shape) throws an exception that aborts scene loading.

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

The objects section

Required : an array (otherwise "objects must be a list"). Each element is an object with a type key (string, required) that selects the primitive, light or group to build. General shape of an object :

{
  "type": "sphere",           // required — selects the object type
  "name": "My sphere",        // optional — label shown in the interface
  "position": [60, 5, 40],    // type-specific properties (see table below)
  "radius": 25,
  "material": "Red"           // optional — name of a "materials" entry
}

The parser applies a handler table : for each object it walks the known keys and only assigns those present. A key not listed for that type (or entirely unknown) is ignored. If a present key has a malformed value, the object is dropped (error on stderr) but the rest of the scene keeps loading.

Object types and recognized keys

Accepted values for type and keys read by the parser for each. The keys position, rotation, scale, name and material are accepted generically ; the columns below list the specific keys each type actually uses.

Additional generic keys recognized by the handler table : direction, power, threshold, intensity, iterations, vertices, faces, normals, vertex_overrides. Each vertex_overrides entry is an object { "index": n, "position": [x,y,z] } ; an entry without index or position throws an error.

Value conventions

The materials section and referencing by name

Optional : an array of materials (otherwise "materials must be a list"). Each entry must have a name (without it : "Missing material name") and usually a model ("phong" or "pbr"). An object references a material through its material key, which must match exactly the name of a materials entry.

Full commented example

Faithful excerpt from tests/configs/subject.json (two spheres, a plane and a light) :

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

  "camera": {
    "resolution": [1920, 1080],      // width x height in pixels (required)
    "position":   [0.0, -100.0, 20.0],
    "rotation":   [0.0, 0.0, 0.0],   // degrees (required)
    "fieldOfView": 72.0,             // degrees (required)
    "samplesPerPixel": 128           // anti-aliasing (default 5)
  },

  "objects": [
    {
      "name": "Sphere A",
      "type": "sphere",
      "position": [60.0, 5.0, 40.0],
      "radius": 25,
      "material": "Material A"        // reference by name
    },
    {
      "name": "Plane",
      "type": "plane",
      "axis": "z",                    // "x" | "y" | "z" — NOT "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": [
    // The model is read from "model" (phong | pbr) ; "base_color" in [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] }
  ]
}

Parser error messages

Fatal errors abort loading (a LoadingSceneException). Per-object errors are written to stderr and the offending object is simply skipped.