Skip to content

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, custom Euler orientations, and how many images
  • meshes – mesh export options during simulation

The Datasets panel sample controls (specimen location / rotation) are UI-only. A bare sample: key in YAML is ignored on load and is not written on export. See Unit Tests to verify a loaded file against the live scene.

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 | Eevee (BLENDER_EEVEE / BLENDER_EEVEE_NEXT; both accepted) | BLENDER_WORKBENCH
  • cycles (used when engine is CYCLES; written on export only for Cycles):
    • use_adaptive_sampling, adaptive_threshold, samples, adaptive_min_samples, time_limit, use_denoising — final render sampling
    • use_preview_adaptive_sampling, preview_adaptive_threshold, preview_samples, preview_adaptive_min_samples, use_preview_denoising — viewport sampling
  • eevee (used when engine is Eevee; written on export only for Eevee):
    • use_raytracing: boolean
    • taa_render_samples: integer (Samples)
  • Legacy flat eevee_use_raytracing is still accepted on load

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 (built-in and/or custom orientation names to include in the pipeline)
  • custom_orientations: optional map of name → [rx, ry, rz] Euler angles in radians. Each custom orientation runs the morphospace Default, then applies the Euler in the specimen's local frame (relative to the post-Default pose, before bake), then recenters at geometry bounds. Available for all morphospaces. Names must be unique identifiers (letters, digits, _, - only) and must not collide with built-ins or other customs; invalid YAML entries are skipped on load.
  • images_per_orientation: integer, ≥ 1

meshes

  • save_meshes: boolean
  • orient_before_export: boolean (default true). When saving meshes in the imaging pipeline, apply the morphospace Default orientation before export. Set to false to export the generated mesh as-is (recommended for MorphoWeave, where the SSM already provides a consistent PCA-aligned frame). Imaging orientations are still applied afterward for renders.
  • file_export_type: obj or ply

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  # or CYCLES / BLENDER_EEVEE_NEXT
  eevee:
    use_raytracing: false
    taa_render_samples: 64
  # When using Cycles, use a cycles: block instead, for example:
  # engine: CYCLES
  # cycles:
  #   use_adaptive_sampling: true
  #   adaptive_threshold: 0.01
  #   samples: 4096
  #   adaptive_min_samples: 0
  #   time_limit: 0.0

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
  # Optional named Euler orientations (radians), usable by any morphospace:
  # custom_orientations:
  #   Side: [1.5708, 0.0, 0.0]
  #   Dorsal: [0.0, 1.5708, 0.0]

meshes:
  file_export_type: obj
  save_meshes: false
  orient_before_export: true
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
  # MorphoWeave: keep SSM/PCA frame (skip Default table placement before export)
  # orient_before_export: false
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:
  engine: CYCLES
  cycles:
    use_adaptive_sampling: true
    adaptive_threshold: 0.01
    samples: 4096
    adaptive_min_samples: 0
    time_limit: 0.0

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', 'Side']
  custom_orientations:
    Side: [1.5708, 0.0, 0.0]
  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

  1. Export a YAML from the GUI (Export Config as YAML), or edit one by hand using the schema above.
  2. In Museum Setup, set Config File (or leave it empty and pick a file when prompted) and click Configure Scene.
  3. After a successful load, the chosen path is stored on traitblender_setup.config_file so the field and unit tests stay in sync.

Custom orientations in YAML

Under imaging.custom_orientations, map a unique name to Euler angles [rx, ry, rz] in radians. Built-in morphospace orientation names always win on collision. Customs are available for every morphospace: they run Default, apply the Euler in the specimen’s local frame (relative to the post-Default pose, before bake), then recenter at geometry bounds. List those names in orientation_names to include them in the imaging pipeline.

Names must be simple identifiers: letters, digits, underscores, and hyphens only (e.g. Side, Left-view). Spaces, quotes, and other special characters are rejected in the UI, and names must not collide with another custom or a built-in orientation. Invalid entries in YAML are skipped on load.

Mesh export in the imaging pipeline

When meshes.save_meshes is true, the simulation pipeline writes one mesh per specimen under rendering_directory/meshes/<specimen>/ before imaging orientations and transform randomization run for that specimen’s renders.

meshes.orient_before_export (default true) controls the pose of that file:

Value Mesh file contents
true (default) Morphospace Default applied first (table placement). Same behavior as earlier TraitBlender releases.
false Export the mesh as generated, with no Default/table orientation. Prefer this for MorphoWeave, where the SSM already lives in a shared PCA-aligned frame. Imaging orientations still apply afterward for rendered images only. 
meshes:
  file_export_type: obj   # or ply
  save_meshes: true
  orient_before_export: false

Verifying a load

After Configure Scene, run config_matches_scene (see Unit Tests) to confirm the YAML still matches the live scene—including Cycles/Eevee render vs viewport sampling keys.