Configuration Files¶

TraitBlender config files are YAML files that store the settings you see in the Configuration panel (camera, lighting, world, materials, output, etc.). You can export a YAML to reuse the same setup later.

Basic structure

Config files are organized into top-level sections. Each section controls one part of the scene or pipeline:

morphospace – which morphospace is active and its hyperparameters
dataset – the external dataset file path (CSV/TSV/XLSX)
world – background color and strength
camera – position, rotation, resolution, lens
lamp – light position, color, power, shadows
mat – specimen mat position, scale, color, roughness
render – render engine and Eevee ray tracing
output – where simulation results are written and in what format
metadata – stamp text in the rendered images
ruler – ruler location / visibility
transforms – optional random variation on config values
imaging – which orientations to render and how many images
meshes – mesh export options during simulation

Allowed values and ranges (quick reference)

world

color: 4 floats (RGBA), each in 0.0–1.0
strength: float, ≥ 0.0

dataset

filepath: string path to a CSV/TSV/XLSX dataset file

camera

location, rotation: 3 floats each
camera_type: PERSP | ORTHO | PANO
focal_length: float, ≥ 0.0
resolution_x, resolution_y: integers
resolution_percentage: integer in 0–100
aspect_x, aspect_y: floats
shift_x, shift_y: floats
lens_unit: MILLIMETERS | FOV

lamp

location, rotation, scale: 3 floats each
color: 3 floats (RGB), each in 0.0–1.0
power: float, ≥ 0.0
use_soft_falloff, shadow: booleans
beam_size: float in 0.0–10.0
beam_blend: float, ≥ 0.0
diffuse: float, ≥ 0.0

mat

tb_location, tb_rotation, scale: 3 floats each
color: 4 floats (RGBA), each in 0.0–1.0
roughness: float in 0.0–1.0

render

engine: CYCLES | BLENDER_EEVEE_NEXT | BLENDER_WORKBENCH
eevee_use_raytracing: boolean

output

rendering_directory, output_directory: directory paths (strings)
output_type: image | video
image_format: PNG | JPEG
images_per_view: integer, ≥ 1

metadata

All use_stamp_*: booleans
stamp_note_text: string

ruler

tb_location, tb_rotation: 3 floats each
hide: boolean

imaging

include_images: boolean
orientation_names: list of strings (orientation names from the selected morphospace)
images_per_orientation: integer, ≥ 1

meshes

save_meshes: boolean
file_export_type: currently obj

morphospace

name: morphospace display name (e.g. Shell (Default))
hyperparams: mapping of morphospace-specific keys to values (keys differ by morphospace)

transforms

sampler_name: currently normal
- params.mu: float
- params.sigma: float (use > 0 for meaningful variation)
property_path: supported scalar paths such as:
- world.color.r|g|b|a, world.strength
- camera.location.x|y|z, camera.rotation.x|y|z
- camera.focal_length, camera.shift_x, camera.shift_y
- lamp.location.x|y|z, lamp.rotation.x|y|z
- lamp.color.r|g|b, lamp.power
- mat.tb_location.x|y|z, mat.tb_rotation.x|y|z
- mat.color.r|g|b|a, mat.roughness
- sample.tb_location.x|y|z, sample.tb_rotation.x|y|z

Example 1: Minimal “museum image” config

This is a good starting point if you want a stable, repeatable setup with no augmentation.

morphospace:
  name: Shell (Default)
  hyperparams: {}

world:
  color: [0.0, 0.0, 0.0, 1.0]
  strength: 1.0

camera:
  location: [0.0, 0.0, 1.0]
  rotation: [0.0, 0.0, 0.0]
  camera_type: PERSP
  focal_length: 60.0
  resolution_x: 1920
  resolution_y: 1920
  resolution_percentage: 100
  aspect_x: 1.0
  aspect_y: 1.0
  shift_x: 0.0
  shift_y: 0.0
  lens_unit: MILLIMETERS

lamp:
  location: [0.0, 0.0, 1.0]
  rotation: [0.0, 0.0, 0.0]
  scale: [1.0, 1.0, 1.0]
  color: [1.0, 1.0, 1.0]
  power: 10.0
  use_soft_falloff: true
  beam_size: 1.0
  beam_blend: 0.0
  shadow: true
  diffuse: 1.0

mat:
  tb_location: [0.0, 0.0, 0.59]
  tb_rotation: [0.0, 0.0, 0.0]
  scale: [0.125, 0.125, 1.0]
  color: [0.0, 0.0, 0.0, 1.0]
  roughness: 1.0

render:
  engine: BLENDER_EEVEE_NEXT
  eevee_use_raytracing: false

output:
  rendering_directory: ""   # The directory where simulation output will be written
  output_type: image
  image_format: PNG
  output_directory: ""
  images_per_view: 1

metadata:
  use_stamp_date: true
  use_stamp_time: true
  use_stamp_render_time: true
  use_stamp_frame: true
  use_stamp_frame_range: false
  use_stamp_memory: false
  use_stamp_hostname: false
  use_stamp_camera: true
  use_stamp_lens: false
  use_stamp_scene: true
  use_stamp_marker: false
  use_stamp_filename: true
  use_stamp_sequencer_strip: false
  use_stamp_note: false
  stamp_note_text: ""

ruler:
  tb_location: [0.0, -0.1, 0.0]
  tb_rotation: [0.0, 0.0, 0.0]
  hide: false

transforms: []

imaging:
  include_images: true
  orientation_names: []
  images_per_orientation: 1

meshes:
  file_export_type: obj
  save_meshes: false

Example 2: Simulation that saves meshes (and skips images)

If you only want meshes during simulation (no rendered images), these are the important toggles:

output:
  rendering_directory: "C:/path/to/simulation-output"

imaging:
  include_images: false

meshes:
  file_export_type: obj
  save_meshes: true

Example 3: Morphospace hyperparameters (non-empty)

Hyperparameters are **morphospace-specific** (they are not part of the dataset). Here is a real example for **Shell (Default)**:

morphospace:
  name: Shell (Default)
  hyperparams:
    n_vertices_aperture: 24
    time_step: 0.03
    use_inner_surface: true

Example 4: Transforms (non-empty)

Transforms apply **random variation** during rendering/simulation. Each transform has: - `property_path`: which setting to change - `sampler_name`: how to sample the change - `params`: parameters for the sampler

transforms:
  - property_path: lamp.power
    sampler_name: normal
    params:
      mu: 0.0
      sigma: 2.0

  - property_path: camera.location.z
    sampler_name: normal
    params:
      mu: 0.0
      sigma: 0.05

  - property_path: world.strength
    sampler_name: normal
    params:
      mu: 0.0
      sigma: 0.2

Example 5: Modern “Circle Grid + CYCLES” config

This example shows a modern YAML config structure you can load via `Configure Scene`. Sections omitted from the YAML fall back to the current Blender default values for those settings. It renders the `Circle Grid` morphospace using `CYCLES`, with transforms empty.

morphospace:
  name: Circle Grid
  hyperparams:
    {}

dataset:
  filepath: "/home/calebc22/projects/tbd/datasets/circle_grid_50sp_32tr_mu5sd1.csv"

world:
  color: [1.0, 1.0, 1.0, 1.0]
  strength: 1.0

camera:
  location: [0.0, 0.0, 1.1]
  aspect_x: 1.0
  aspect_y: 1.0
  camera_type: PERSP
  focal_length: 60.0
  lens_unit: MILLIMETERS
  resolution_percentage: 100
  resolution_x: 220
  resolution_y: 220
  rotation: [0.0, 0.0, 0.0]
  shift_x: 0.0
  shift_y: 0.0

lamp:
  location: [0.0, 0.0, 1.0]
  beam_blend: 0.0
  beam_size: 1.0
  color: [1.0, 1.0, 1.0]
  diffuse: 1.0
  power: 0.0
  rotation: [0.0, 0.0, 0.0]
  scale: [1.0, 1.0, 1.0]
  shadow: true
  use_soft_falloff: true

ruler:
  tb_location: [0.0, -0.1, 0.0]
  tb_rotation: [0.0, 0.0, 0.0]
  hide: true

mat:
  color: [0.0, 0.0, 0.0, 1.0]
  tb_location: [0.0, 0.0, 0.0]
  tb_rotation: [0.0, 0.0, 0.0]
  roughness: 1.0
  scale: [0.15, 0.15, 1.0]

render:
  eevee_use_raytracing: false
  engine: CYCLES

output:
  image_format: PNG
  images_per_view: 1
  rendering_directory: "/home/calebc22/projects/tbd/simulations/shell_test_1"
  output_type: image

imaging:
  include_images: true
  orientation_names: ['Default']
  images_per_orientation: 1

metadata:
  stamp_note_text: ""
  use_stamp_camera: true
  use_stamp_date: true
  use_stamp_filename: true
  use_stamp_frame: true
  use_stamp_frame_range: false
  use_stamp_hostname: false
  use_stamp_lens: false
  use_stamp_marker: false
  use_stamp_memory: false
  use_stamp_note: false
  use_stamp_render_time: true
  use_stamp_scene: true
  use_stamp_sequencer_strip: false
  use_stamp_time: true

transforms: []

Using config files¶

Use the GUI to export a YAML (recommended), then reuse it later by loading it back into the Configuration panel workflow.