Home / Usage

Usage

Launch the program, understand the command-line options, the headless rendering mode, and the full JSON scene file format.

Command line

./raytracer [OPTIONS] [SCENE_FILE]

The SCENE_FILE is optional: without it, a blank default scene is loaded. Arguments are parsed by the Options struct (srcs/config/Options.hpp).

Command examples

# Graphical interface on an example scene
./raytracer tests/configs/subject.json

# Direct render to a PNG (no interface)
./raytracer -r output.png tests/configs/subject.json

# Headless render with the default output name (render.png)
./raytracer --render tests/configs/cube.json

# Interface + cluster server on port 8080
./raytracer --server 8080 tests/configs/subject.json

# Interface + connection to a cluster server
./raytracer --connect 127.0.0.1 8080 tests/configs/subject.json

Headless mode (PNG render)

The -r / --render mode does not load the interface: it builds the scene, computes the image, exports it as a PNG, then exits. Ideal for scripts and continuous integration.

./raytracer -r output.png tests/configs/cube.json
# Expected console output:
#   Loaded 2 renderer plugin(s)
#    - Viewport
#    - Default
#   Finished rendering scene! Saving to file..
#   Render has been saved to file 'output.png'

Scene file format

A scene is a JSON file (the .json extension is required) read by SceneParser. The camera and objects sections are required; environment and materials are optional. Unknown keys are simply ignored.

General skeleton

{
  "environment": { "ambient": 0.4, "diffuse": 0.6 },
  "camera": {
    "resolution": [1920, 1080],
    "position":   [0.0, -100.0, 20.0],
    "rotation":   [0.0, 0.0, 0.0],
    "fieldOfView": 72.0,
    "samplesPerPixel": 128
  },
  "objects": [
    { "name": "Sphere A", "type": "sphere", "position": [60, 5, 40], "radius": 25, "material": "Material A" }
  ],
  "materials": [
    { "name": "Material A", "model": "pbr", "base_color": [230, 60, 60], "roughness": 0.5 }
  ]
}

The environment section

Optional. Controls the global lighting.

The camera section

Required. Defines the viewpoint and render quality.

The objects section

Required. A list of primitives, lights, and groups. Every object has a type (required) and a name (optional). Primitives may reference a material by name. The SceneParser only reads keys relevant to the type; unknown keys are ignored. Available types:

Colors and vectors

• A vector is an array of 3 numbers [x, y, z] (position, rotation in degrees, scale, direction…).
• A color is an array of 3 integer components [r, g, b], each between 0 and 255.

The materials section

Optional. Every material has a name (referenced by objects through material) and a model ("phong" or "pbr"). The fields read by parseMaterial:

{
  "name": "GoldMetal",
  "model": "pbr",
  "base_color": [255, 198, 92],
  "metallic": 0.9,
  "roughness": 0.22,
  "clearcoat": 0.0,
  "transmission": 0.0,
  "ior": 1.5
}

Full annotated example

A faithful excerpt of 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"       // referenced 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 recognized key is "model" (phong | pbr); "base_color" is [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] }
  ]
}

Importing an .obj mesh

An object of type mesh loads an .obj file through the file key. Example files are in tests/obj/ (cube.obj, poly.obj, slt.obj).

{
  "name": "Polished Metal",
  "type": "mesh",
  "file": "tests/obj/slt.obj",
  "position": [34.0, 4.0, 6.0],
  "rotation": [0.0, 0.0, -18.0],
  "scale": [110.0, 110.0, 110.0],
  "material": "GoldMetal"
}

A mesh can also be defined inline (without an external file) through vertices, faces, and normals, or carry per-vertex edits with vertex_overrides (a list of entries { "index": n, "position": [x,y,z] }) — see Vertex editing.

Saving a scene

From the interface, a scene can be re-exported to JSON: SceneRegister serializes the camera (resolution, position, rotation, fieldOfView, samplesPerPixel), the objects (with their local transforms, and for meshes their vertices/faces/normals or vertex_overrides), and the materials. The load → edit → save → reload round-trip restores the scene faithfully.