API Reference¶
This reference focuses on the user-facing operators and properties you will use in normal TraitBlender workflows.
1. Museum Setup
bpy.ops.traitblender.setup_scene()
Load the pre-configured museum scene with the camera, lighting, and table objects needed for morphospace work.
bpy.ops.traitblender.clear_scene()
Remove the current scene contents so you can start from a clean state.
bpy.ops.traitblender.add_ruler()
Append a ruler object from the museum scene and apply ruler configuration (location, rotation, visibility). Each invocation adds another ruler; Blender handles duplicate naming.
2. Configuration
bpy.context.scene.traitblender_config
The main configuration PropertyGroup containing all scene settings.
bpy.context.scene.traitblender_setup.config_file
Path to the YAML used by Configure Scene and by the config_matches_scene unit test. After a successful configure (including via the file browser), this property is updated to the absolute path that was loaded.
bpy.ops.traitblender.configure_scene(filepath="")
Load a YAML config and apply it to the scene. If filepath is empty and config_file is unset, opens a file browser. Persists the chosen path on traitblender_setup.config_file.
bpy.ops.traitblender.show_configuration()
Print the current configuration as YAML for inspection or copying.
bpy.ops.traitblender.export_config(filepath="")
Export the current configuration to a YAML file.
bpy.ops.traitblender.run_unit_test(test_name="help")
Run an in-addon unit test by name. Use test_name="help" to list tests. See Unit Tests.
3. Morphospaces
bpy.context.scene.traitblender_setup.available_morphospaces
Select the active morphospace. Changing it can alter the available parameters, orientations, and default dataset.
bpy.context.scene.traitblender_dataset.sample
Select the current specimen or sample name from the active dataset.
bpy.ops.traitblender.generate_morphospace_sample()
Generate a morphospace sample object using the selected sample and morphospace settings.
bpy.ops.traitblender.apply_orientation(orientation="")
Apply a named orientation to the current sample by name (built-in or custom). Pass orientation explicitly (recommended for scripts/pipeline); if empty, uses the Orientations panel selection. Imaging folders and logs should use the same name string that was applied.
bpy.context.scene.traitblender_config.imaging.custom_orientations
Named custom Euler orientations (name, rotation as [rx, ry, rz] radians). For every morphospace: run Default → apply Euler in the specimen's local frame (relative to the post-Default pose, before bake) → recenter at geometry bounds. Merged with built-ins for Apply and imaging; built-in names win on collision. YAML: imaging.custom_orientations.
bpy.ops.traitblender.add_custom_orientation() / bpy.ops.traitblender.remove_custom_orientation()
Add or remove a custom orientation entry in the Orientations panel (also reflected in Imaging checkboxes and YAML export).
4. Datasets
bpy.context.scene.traitblender_dataset.filepath
Path to the dataset file on disk.
bpy.context.scene.traitblender_dataset.sync_sample_with_active_object
When True (default), automatically set sample to match the active object name when that name is a row in the dataset.
bpy.ops.traitblender.import_dataset()
Import CSV, TSV, or Excel data into the in-memory dataset.
bpy.ops.traitblender.edit_dataset()
Open the dataset editor and modify the current dataset interactively.
bpy.ops.traitblender.export_dataset()
Export the current dataset to a CSV file.
5. Transforms
bpy.context.scene.traitblender_config.transforms
Transform pipeline settings and state.
bpy.ops.traitblender.run_pipeline()
Run the transform pipeline on the current specimen.
bpy.ops.traitblender.undo_pipeline()
Undo the last transform step.
bpy.ops.traitblender.reset_pipeline()
Reset the pipeline back to its initial state.
6. Meshes
bpy.context.scene.traitblender_config.meshes.file_export_type
Choose the mesh export format used by the mesh exporter and simulation pipeline.
bpy.context.scene.traitblender_config.meshes.save_meshes
If enabled, save a mesh export during simulation.
bpy.context.scene.traitblender_config.meshes.orient_before_export
If True (default), apply Default orientation before pipeline mesh export (backward compatible). If False, export the generated mesh as-is—recommended for MorphoWeave PCA-aligned meshes. Does not affect imaging orientations used for renders. See Configuration Files.
bpy.ops.traitblender.export_mesh()
Export the current sample as a mesh file using the selected format.
7. Imaging and Simulation
bpy.context.scene.traitblender_config.imaging
Controls for the imaging pipeline, including whether to render images during simulation.
bpy.context.scene.traitblender_config.output.rendering_directory
Root directory used for simulation output.
bpy.ops.traitblender.imaging_pipeline()
Run the full simulation pipeline for the current dataset.
User-facing properties
bpy.context.scene.traitblender_config
Main configuration object for all TraitBlender settings.
bpy.context.scene.traitblender_setup
Setup state for morphospace selection, config_file, and related UI.
bpy.context.scene.traitblender_dataset
The current dataset and its editable CSV contents.
bpy.context.scene.traitblender_orientation
The currently selected orientation.
bpy.context.scene.traitblender_sample
The current sample object.
Notes¶
- The Python tooltip in Blender is usually enough to discover the matching API call for a given button or property.
- TraitBlender assumes a single active scene (and view layer). Config, operators, imaging sync, and orientations all use that context—multi-scene setups are not supported.
- Custom orientation names must be unique identifiers (letters, digits,
_,-only) and must not collide with built-ins; see Configuration Files.