API Documentation¶
TODO: Module Import Instructions
Standard Blender Access: Configs, properties, operators, and panels can be accessed through bpy like other Blender add-ons:
- bpy.context.scene.traitblender_config
- bpy.ops.traitblender.setup_scene()
- etc.
TraitBlender-Specific Functions: Helper functions and internal modules must be imported using Blender's non-standard import path (instructions to be added here).
For Developers: When working within the TraitBlender codebase itself, standard Python imports work normally.
Museum Setup
Operators¶
bpy.ops.traitblender.setup_scene()
Load the TraitBlender museum scene for morphological imaging
Description: Load the pre-configured museum scene with lighting and camera setup
Returns:
- {'FINISHED'} on success
- {'CANCELLED'} on error
Note: Shows confirmation dialog if scene has unsaved changes
bpy.ops.traitblender.clear_scene()
Clear all objects and data from the current scene
Description: Remove all objects, materials, and data from the current scene
Returns:
- {'FINISHED'} on success
- {'CANCELLED'} on error
Note: Shows confirmation dialog before clearing
bpy.ops.traitblender.configure_scene(filepath="")
Configure TraitBlender scene from YAML file
Description: Load and apply configuration from YAML file
Parameters:
- filepath (str, optional): Path to the YAML configuration file. If not provided, uses context.scene.traitblender_setup.config_file. If neither is set, opens file browser.
Returns:
- {'FINISHED'} on success
- {'CANCELLED'} on error
Note: Requires museum scene to be loaded first (via setup_scene())
bpy.ops.traitblender.show_configuration()
Show current TraitBlender configuration in YAML format
Description: Display current configuration in YAML format
Returns: {'FINISHED'}
Note: Opens a dialog window displaying the current configuration
bpy.ops.traitblender.export_config(filepath="")
Export current TraitBlender configuration to a YAML file
Description: Export the current configuration to a YAML file
Parameters:
- filepath (str): Path to export YAML file (opens file browser if not provided)
Returns:
- {'FINISHED'} on success
- {'CANCELLED'} on error
Properties¶
bpy.context.scene.traitblender_setup
Property group for TraitBlender setup configuration.
Attributes:
- config_file (str): Path to YAML configuration file
- available_morphospaces (EnumProperty): List of available morphospace modules (read-only, auto-populated)
Example:
Configuration
Accessing Configuration¶
bpy.context.scene.traitblender_config
Main configuration object containing all TraitBlender settings.
Example:
config = bpy.context.scene.traitblender_config
# Access config sections
world = config.world
camera = config.camera
lamp = config.lamp
Getting and Setting Properties¶
Configuration properties automatically sync with Blender objects. Access them directly:
config = bpy.context.scene.traitblender_config
# Get property values
world_color = config.world.color
camera_location = config.camera.location
lamp_power = config.lamp.power
# Set property values
config.world.color = (0.1, 0.1, 0.1, 1.0)
config.camera.location = (0.0, 0.0, 1.0)
config.lamp.power = 5.0
Note: Properties use dynamic getters/setters that check for required Blender objects. If objects don't exist, getters return default values and setters do nothing (with warnings).
Serialization¶
to_dict()¶
Convert the configuration to a nested dictionary.
Returns: dict - Dictionary representation of the configuration
Example:
config = bpy.context.scene.traitblender_config
config_dict = config.to_dict()
# Returns: {'world': {'color': [0.0, 0.0, 0.0, 1.0], 'strength': 1.0}, ...}
from_dict(data_dict)¶
Load configuration values from a dictionary.
Parameters:
- data_dict (dict): Dictionary containing configuration values. Can contain nested dictionaries for nested config sections.
Example:
config = bpy.context.scene.traitblender_config
config_data = {
'world': {'color': [0.1, 0.1, 0.1, 1.0], 'strength': 2.0},
'camera': {'location': [0.0, 0.0, 1.5], 'focal_length': 50.0}
}
config.from_dict(config_data)
__str__() / YAML Export¶
Convert the configuration to YAML format.
Returns: str - YAML string representation
Example:
config = bpy.context.scene.traitblender_config
yaml_string = str(config)
print(yaml_string)
# Output:
# ---
# world:
# color: [0.0, 0.0, 0.0, 1.0]
# strength: 1.0
# camera:
# location: [0.0, 0.0, 0.0]
# ...
Config Sections¶
get_config_sections()¶
Get all nested config sections.
Returns: dict - Dictionary mapping section names to their config objects
Example:
config = bpy.context.scene.traitblender_config
sections = config.get_config_sections()
# Returns: {'world': <WorldConfig>, 'camera': <CameraConfig>, ...}
for section_name, section_obj in sections.items():
print(f"Section: {section_name}")
Common Operations¶
Export Configuration to File¶
import yaml
config = bpy.context.scene.traitblender_config
config_dict = config.to_dict()
with open('my_config.yaml', 'w') as f:
yaml.dump(config_dict, f)
Import Configuration from File¶
import yaml
with open('my_config.yaml', 'r') as f:
config_data = yaml.safe_load(f)
config = bpy.context.scene.traitblender_config
config.from_dict(config_data)
Access Nested Properties¶
config = bpy.context.scene.traitblender_config
# Direct access
world_color = config.world.color
# Using getattr for dynamic access
section = getattr(config, 'world')
color = getattr(section, 'color')
# Using getattr for safe access
if hasattr(config, 'world') and hasattr(config.world, 'color'):
color = config.world.color
Available Config Sections¶
The following sections are available in traitblender_config:
world- World background color and strengthcamera- Camera location, rotation, focal length, resolution, etc.lamp- Lamp location, rotation, color, power, etc.mat- Specimen mat propertiesrender- Render engine settingsoutput- Output format and directorymetadata- Image metadata/stamp settingsorientations- Specimen orientation settingstransforms- Transform pipeline configuration
Each section can be accessed as config.section_name and contains properties specific to that section.
Morphospaces
Operators¶
bpy.ops.traitblender.generate_morphospace_sample()
Generate a 3D specimen from the selected morphospace and dataset row.
Description: Creates a 3D mesh object in Blender using the selected morphospace model and parameters from the currently selected dataset sample.
Returns:
- {'FINISHED'} on success
- {'CANCELLED'} on error
Requirements:
- A morphospace must be selected (via traitblender_setup.available_morphospaces)
- A dataset sample must be selected (via traitblender_dataset.sample)
- Dataset must be loaded with data
Note: The generated object is automatically positioned at the center of the table (tb_coords = (0, 0, 0)) and named after the selected sample.
Example:
# Select morphospace and dataset sample first
setup = bpy.context.scene.traitblender_setup
dataset = bpy.context.scene.traitblender_dataset
setup.available_morphospaces = "CO_Raup"
dataset.sample = "SpeciesName"
# Generate the specimen
bpy.ops.traitblender.generate_morphospace_sample()
Properties¶
bpy.context.scene.traitblender_setup.available_morphospaces
Enum property for selecting the active morphospace module.
Type: EnumProperty (read-only, auto-populated)
Description: Lists all available morphospace modules found in assets/morphospace_modules/. The value is the morphospace folder name.
Example:
setup = bpy.context.scene.traitblender_setup
# Get current selection
current_morphospace = setup.available_morphospaces
print(f"Selected morphospace: {current_morphospace}")
# Set morphospace (if "CO_Raup" is available)
setup.available_morphospaces = "CO_Raup"
Note: The enum items are dynamically generated by scanning the morphospace modules directory. Only morphospaces with a valid __init__.py file are included.
Workflow¶
Complete Morphospace Generation Workflow¶
# 1. Load museum scene
bpy.ops.traitblender.setup_scene()
# 2. Import dataset
dataset = bpy.context.scene.traitblender_dataset
dataset.filepath = "/path/to/dataset.csv"
# 3. Select morphospace
setup = bpy.context.scene.traitblender_setup
setup.available_morphospaces = "CO_Raup"
# 4. Select a sample from the dataset
dataset.sample = "MySpecies"
# 5. Generate the specimen
bpy.ops.traitblender.generate_morphospace_sample()
# The generated object is now in the scene at the table center
obj = bpy.data.objects.get("MySpecies")
Datasets
Accessing Dataset¶
bpy.context.scene.traitblender_dataset
Main dataset object for managing morphological data.
Example:
Operators¶
bpy.ops.traitblender.import_dataset()
Import dataset from file and convert to CSV string.
Description: Imports a dataset from CSV, TSV, or Excel file. Requires dataset.filepath to be set first.
Returns:
- {'FINISHED'} on success
- {'CANCELLED'} on error
Supported Formats: CSV, TSV (.tsv), Excel (.xlsx, .xls)
Example:
dataset = bpy.context.scene.traitblender_dataset
dataset.filepath = "/path/to/dataset.csv"
bpy.ops.traitblender.import_dataset()
Note: Setting dataset.filepath automatically imports the dataset, so calling this operator is usually not necessary.
bpy.ops.traitblender.edit_dataset()
Open CSV editor to edit the dataset.
Description: Opens a DearPyGui-based CSV viewer/editor for viewing and editing dataset values.
Returns:
- {'FINISHED'} on success
- {'CANCELLED'} on error
Note: Requires a dataset to be loaded first. Changes are saved back to the dataset when the editor is closed.
Example:
dataset = bpy.context.scene.traitblender_dataset
if dataset.csv: # Check if dataset is loaded
bpy.ops.traitblender.edit_dataset()
Properties¶
filepath
Path to the dataset file. Automatically imports the dataset when set.
Type: StringProperty (FILE_PATH)
Supported Formats: CSV, TSV, Excel (.xlsx, .xls)
Example:
dataset = bpy.context.scene.traitblender_dataset
dataset.filepath = "/path/to/dataset.csv"
# Dataset is automatically imported
sample
Enum property for selecting a sample (species/specimen) from the dataset.
Type: EnumProperty (read-only, auto-populated from dataset)
Description: Lists all samples in the dataset. The value is the species/specimen name (from the first column).
Example:
dataset = bpy.context.scene.traitblender_dataset
# Get current selection
current_sample = dataset.sample
print(f"Selected sample: {current_sample}")
# Set sample (use actual name from your dataset)
dataset.sample = "SpeciesName"
Data Access Methods¶
loc(species_name) or loc(species_name, column_name)
Access rows and columns by label (pandas-like loc accessor).
Parameters:
- species_name (str): Species/specimen name (row index)
- column_name (str, optional): Column name. If omitted, returns the entire row.
Returns:
- pandas.Series if accessing a row
- Value if accessing a specific cell
Example:
dataset = bpy.context.scene.traitblender_dataset
# Get entire row for a species
row = dataset.loc("SpeciesName")
print(row)
# Get specific column value
value = dataset.loc("SpeciesName", "column_name")
print(value)
iloc(row_index) or iloc(row_index, column_index)
Access rows and columns by integer position (pandas-like iloc accessor).
Parameters:
- row_index (int): Row index (0-based)
- column_index (int, optional): Column index. If omitted, returns the entire row.
Returns:
- pandas.Series if accessing a row
- Value if accessing a specific cell
Example:
dataset = bpy.context.scene.traitblender_dataset
# Get first row
first_row = dataset.iloc(0)
# Get value at row 0, column 1
value = dataset.iloc(0, 1)
head(n=5)
Return the first n rows of the dataset.
Parameters:
- n (int, optional): Number of rows to return (default: 5)
Returns: pandas.DataFrame - First n rows
Example:
tail(n=5)
Return the last n rows of the dataset.
Parameters:
- n (int, optional): Number of rows to return (default: 5)
Returns: pandas.DataFrame - Last n rows
Example:
Dataset Properties¶
colnames
List of column names in the dataset.
Type: property (returns list)
Example:
dataset = bpy.context.scene.traitblender_dataset
columns = dataset.colnames
print(f"Columns: {columns}")
# Output: ['species', 'b', 'd', 'z', 'a', ...]
rownames
List of row names (species/specimen names) in the dataset.
Type: property (returns list)
Example:
dataset = bpy.context.scene.traitblender_dataset
species_list = dataset.rownames
print(f"Species: {species_list[:5]}") # First 5 species
shape
Shape of the dataset as (rows, columns) tuple.
Type: property (returns tuple)
Example:
dataset = bpy.context.scene.traitblender_dataset
rows, cols = dataset.shape
print(f"Dataset has {rows} rows and {cols} columns")
Special Methods¶
len(dataset)
Get the number of rows in the dataset.
Example:
dataset = bpy.context.scene.traitblender_dataset
num_rows = len(dataset)
print(f"Dataset has {num_rows} rows")
str(dataset)
Get a string representation of the dataset.
Example:
iter(dataset)
Iterate over column names.
Example:
Common Operations¶
Import and Inspect Dataset¶
dataset = bpy.context.scene.traitblender_dataset
# Import dataset
dataset.filepath = "/path/to/dataset.csv"
# Inspect dataset
print(f"Shape: {dataset.shape}")
print(f"Columns: {dataset.colnames}")
print(f"First 5 species: {dataset.rownames[:5]}")
# View first few rows
print(dataset.head(5))
Get Row Data for a Species¶
dataset = bpy.context.scene.traitblender_dataset
# Get all data for a species
row = dataset.loc("SpeciesName")
print(row)
# Get specific parameter value
param_value = dataset.loc("SpeciesName", "parameter_name")
print(f"Parameter value: {param_value}")
Iterate Over All Species¶
dataset = bpy.context.scene.traitblender_dataset
for species_name in dataset.rownames:
row_data = dataset.loc(species_name)
print(f"Processing {species_name}: {row_data}")
# Use row_data for morphospace generation, etc.
Dataset Format Requirements¶
Datasets should have:
- First column: Species/specimen names (automatically detected from: species, label, tips, name, id, etc.)
- Remaining columns: Morphological traits/parameters that map to morphospace parameters
TraitBlender automatically: - Detects the species column (case-insensitive) - Moves the species column to the first position - Uses the species column as the row index
Supported File Formats: CSV, TSV, Excel (.xlsx, .xls)
Orientations
Operators¶
bpy.ops.traitblender.sample_origin_shift()
Shift the sample object's origin to (0,0,0) in table coordinates along specified axes.
Description: Repositions a specimen object so that its calculated origin (based on orientation settings) is at (0,0,0) in table coordinates.
Returns:
- {'FINISHED'} on success
- {'CANCELLED'} on error
Requirements:
- A dataset sample must be selected (via traitblender_dataset.sample)
- The sample object must exist in the scene
- Orientation settings must be configured
Example:
dataset = bpy.context.scene.traitblender_dataset
dataset.sample = "SpeciesName"
# Configure orientation settings
config = bpy.context.scene.traitblender_config
config.orientations.object_location_origin = "GEOM_BOUNDS"
config.orientations.location_shift_axes = "XYZ"
# Shift the origin
bpy.ops.traitblender.sample_origin_shift()
Configuration Properties¶
bpy.context.scene.traitblender_config.orientations
Configuration object for orientation settings.
Properties:
- object_location_origin (EnumProperty): Origin type for object positioning (e.g., 'GEOM_BOUNDS', 'MEAN', 'MEDIAN', 'OBJECT')
- object_rotation_origin (EnumProperty): Origin type for object rotation
- location_shift_axes (EnumProperty): Which axes to apply location shifts to ('X', 'Y', 'Z', 'XY', 'XZ', 'YZ', 'XYZ')
Example:
config = bpy.context.scene.traitblender_config
orientations = config.orientations
# Set origin type
orientations.object_location_origin = "GEOM_BOUNDS"
orientations.object_rotation_origin = "MEAN"
# Set which axes to shift
orientations.location_shift_axes = "XYZ"
Object Properties¶
bpy.data.objects["ObjectName"].tb_coords
Table coordinates property for positioning objects relative to the table surface.
Type: FloatVectorProperty (3D vector)
Description: Position relative to Table's top face center in table's local coordinate system. The origin (0,0,0) is at the center of the table top.
Example:
obj = bpy.data.objects["MySpecimen"]
# Get current table coordinates
coords = obj.tb_coords
print(f"Table coordinates: {coords}")
# Set position at table center
obj.tb_coords = (0.0, 0.0, 0.0)
# Move 1 meter along X axis
obj.tb_coords = (1.0, 0.0, 0.0)
bpy.data.objects["ObjectName"].tb_rotation
Table rotation property for rotating objects relative to the table.
Type: FloatVectorProperty (3D vector, Euler angles)
Description: Rotation relative to the table's coordinate system (in radians).
Example:
obj = bpy.data.objects["MySpecimen"]
# Get current rotation
rotation = obj.tb_rotation
print(f"Table rotation: {rotation}")
# Set rotation
obj.tb_rotation = (0.0, 0.0, 0.0)
Common Operations¶
Position Specimen at Table Center¶
obj = bpy.data.objects["MySpecimen"]
obj.tb_coords = (0.0, 0.0, 0.0)
obj.tb_rotation = (0.0, 0.0, 0.0)
Shift Specimen Origin¶
# Configure orientation
config = bpy.context.scene.traitblender_config
config.orientations.object_location_origin = "GEOM_BOUNDS"
config.orientations.location_shift_axes = "XY" # Only shift X and Y
# Shift the origin
dataset = bpy.context.scene.traitblender_dataset
dataset.sample = "SpeciesName"
bpy.ops.traitblender.sample_origin_shift()
Transforms
Operators¶
bpy.ops.traitblender.run_pipeline()
Execute all transforms in the pipeline.
Description: Runs all transforms in the transform pipeline in sequence, applying statistical variations to scene properties.
Returns:
- {'FINISHED'} on success
- {'CANCELLED'} on error
Example:
# Build pipeline first (see Configuration section)
config = bpy.context.scene.traitblender_config
config.transforms.add_transform("camera.focal_length", "uniform", {"low": 30, "high": 100})
# Run the pipeline
bpy.ops.traitblender.run_pipeline()
bpy.ops.traitblender.undo_pipeline()
Undo all transforms in the pipeline.
Description: Reverts all transforms in reverse order, restoring original property values.
Returns:
- {'FINISHED'} on success
- {'CANCELLED'} on error
Example:
Configuration Methods¶
bpy.context.scene.traitblender_config.transforms
Transform pipeline configuration object.
add_transform(property_path, sampler_name, params=None)¶
Add a transform to the pipeline.
Parameters:
- property_path (str): Relative property path (e.g., 'world.color', 'camera.focal_length')
- sampler_name (str): Name of the sampler function (e.g., 'uniform', 'normal', 'beta')
- params (dict, optional): Parameters for the sampler function
Returns: TransformPipelineConfig - Self for method chaining
Example:
config = bpy.context.scene.traitblender_config
transforms = config.transforms
# Add a uniform transform
transforms.add_transform("camera.focal_length", "uniform", {"low": 30, "high": 100})
# Add a normal distribution transform
transforms.add_transform("camera.location", "normal", {"mu": 0, "sigma": 1, "n": 3})
# Add a color transform (dirichlet for vectors)
transforms.add_transform("world.color", "dirichlet", {"alphas": [0.3, 0.3, 0.3, 1]})
run()¶
Execute all transforms in the pipeline.
Returns: list - List of results from each transform execution
Example:
config = bpy.context.scene.traitblender_config
results = config.transforms.run()
print(f"Applied {len(results)} transforms")
undo()¶
Undo all transforms in reverse order.
Returns: list - List of results from each undo operation
Example:
config = bpy.context.scene.traitblender_config
results = config.transforms.undo()
print(f"Undid {len(results)} transforms")
clear()¶
Clear all transforms from the pipeline.
Returns: TransformPipelineConfig - Self for method chaining
Example:
remove_transform(index)¶
Remove a transform from the pipeline by index.
Parameters:
- index (int): Zero-based index of the transform to remove
Returns: bool - True if successful, False otherwise
Example:
config = bpy.context.scene.traitblender_config
# Remove the first transform (index 0)
config.transforms.remove_transform(0)
Pipeline Properties¶
len(transforms)
Get the number of transforms in the pipeline.
Example:
config = bpy.context.scene.traitblender_config
num_transforms = len(config.transforms)
print(f"Pipeline has {num_transforms} transforms")
transforms[index]
Access a transform by index.
Example:
config = bpy.context.scene.traitblender_config
first_transform = config.transforms[0]
print(first_transform)
Common Operations¶
Build and Run a Transform Pipeline¶
config = bpy.context.scene.traitblender_config
transforms = config.transforms
# Clear any existing transforms
transforms.clear()
# Add transforms
transforms.add_transform("camera.focal_length", "uniform", {"low": 50, "high": 100})
transforms.add_transform("world.color", "dirichlet", {"alphas": [0.2, 0.2, 0.2, 1]})
transforms.add_transform("lamp.power", "normal", {"mu": 5.0, "sigma": 1.0})
# Run the pipeline
transforms.run()
# Later, undo if needed
transforms.undo()
Available Samplers¶
The following sampler functions are available:
uniform- Uniform distribution between low and highnormal- Normal (Gaussian) distributionbeta- Beta distributiongamma- Gamma distributiondirichlet- Dirichlet distribution (for color vectors)multivariate_normal- Multivariate normal distributionpoisson- Poisson distributionexponential- Exponential distributioncauchy- Cauchy distributiondiscrete_uniform- Discrete uniform distribution
Each sampler has specific parameter requirements. See the transform system documentation for details.
Imaging
Operators¶
bpy.ops.traitblender.imaging_pipeline()
Run the imaging pipeline to render specimens.
Description: Iterates through the dataset and renders images for each specimen. Applies any configured transforms before rendering.
Returns:
- {'FINISHED'} on success
- {'CANCELLED'} on error
Note: This operator is currently under development. Functionality may be limited.
Example:
# Configure output settings first
config = bpy.context.scene.traitblender_config
config.output.output_directory = "/path/to/output"
config.output.file_format = "PNG"
# Run the imaging pipeline
bpy.ops.traitblender.imaging_pipeline()
Configuration¶
Imaging uses settings from the output and render config sections:
bpy.context.scene.traitblender_config.output
output_directory(str): Directory to save rendered imagesfile_format(EnumProperty): Image format (PNG, JPEG, etc.)
bpy.context.scene.traitblender_config.render
- Render engine settings (Cycles, Eevee, etc.)
- Resolution and quality settings
Example:
config = bpy.context.scene.traitblender_config
# Set output directory
config.output.output_directory = "/path/to/output/images"
# Set file format
config.output.file_format = "PNG"
# Configure render settings
config.render.resolution_x = 1920
config.render.resolution_y = 1080
Workflow¶
Basic Rendering Workflow¶
# 1. Setup scene and load dataset
bpy.ops.traitblender.setup_scene()
dataset = bpy.context.scene.traitblender_dataset
dataset.filepath = "/path/to/dataset.csv"
# 2. Configure output
config = bpy.context.scene.traitblender_config
config.output.output_directory = "/path/to/output"
config.output.file_format = "PNG"
# 3. (Optional) Configure transforms for data augmentation
config.transforms.add_transform("camera.focal_length", "uniform", {"low": 50, "high": 100})
# 4. Run imaging pipeline
bpy.ops.traitblender.imaging_pipeline()
Manual Rendering¶
You can also render manually using Blender's standard rendering: