Skip to content

The TraitBlender API

Jump to bottom
Caleb P. Charpentier edited this page Sep 27, 2023 · 15 revisions

This documentation provides comprehensive details on various aspects of the TraitBlender API, including functions, classes, and operators for controlling lights, backgrounds, and more. Refer to the table of contents for easy navigation.

Table of Contents

The TraitBlender API

Structure of TraitBlender

TraitBlender is designed to streamline the process of 3D model generation and manipulation. Below is an overview of its various components.

Mesh Generation

Mesh generation is the foundation of TraitBlender. This section describes how TraitBlender generates the 3D meshes for models.

World Background

TraitBlender offers various options for setting the world background in your 3D scene. This section covers those features.

Lights

SunControls

Property group for controlling sun related attributes in Blender.

Attributes:
    strength (FloatProperty): The strength of the sun light.
Example
# In Progress

HideSunsOperator

This operator hides or unhides sun objects in the Blender scene.

Attributes:
    bl_idname (str): Blender's internal name for this operator.
    bl_label (str): The label for this operator.
    bl_options (set): Options for this operator.
    sun_names (StringProperty): Comma-separated names of sun objects to be hidden or unhidden.
Example
# In Progress

ToggleSunsOperator

This operator toggles the presence of sun objects in the Blender scene.

Attributes:
    bl_idname (str): Blender's internal name for this operator.
    bl_label (str): The label for this operator.
    bl_options (set): Options for this operator.
    distance (FloatProperty): Distance from the active object to place the suns.
Example
# In Progress

UpdateSunStrengthOperator

This operator updates the strength of sun objects in the Blender scene.

Attributes:
    bl_idname (str): Blender's internal name for this operator.
    bl_label (str): The label for this operator.
    bl_options (set): Options for this operator.
Example
# In Progress

SunControlsPanel

This panel provides controls for managing sun objects in Blender's UI.

Attributes:
    bl_label (str): The label for this panel.
    bl_idname (str): Blender's internal name for this panel.
    bl_space_type (str): The space where this panel appears.
    bl_region_type (str): The region where this panel appears.
    bl_category (str): The category where this panel appears.
    bl_context (str): The context in which this panel appears.
    bl_options (set): Options for this panel.
Example
# In Progress

execute

Executes the operator, updating the strength of specified sun objects.

    Parameters:
        context: Blender's context object.

    Returns:
        dict: A dictionary indicating the execution status.
Example
# In Progress

draw

Draws the UI elements for this panel.

    Parameters:
        context: Blender's context object.
Example
# In Progress

Lighting is crucial for bringing out the details in your 3D models. This section explains how TraitBlender handles lighting.

Camera

Camera settings are vital for capturing the right views of your 3D models. This section discusses the camera options available in TraitBlender.

3D Export

TraitBlender supports multiple formats for exporting your 3D models. This section outlines how to export your projects.

Segmentation / Vertex Groups

This section provides details on how TraitBlender handles segmentation and vertex groups in your 3D models.

Other

This section covers any additional features or settings in TraitBlender not covered in the previous sections.

Background

mesh_menu_func

Function to add the CreateBackgroundImageMeshOperator to the Blender mesh menu.

This function extends the mesh menu in Blender's UI to include an option for
creating a background image mesh. It adds an icon and the operator to the layout.

Parameters:
    self: The current instance of the Blender layout.
    context: The current Blender context, containing references to the active object and scene.
Example
# In Progress

update_background_plane_distance

Update the distance of background planes relative to the active object.

This function adjusts the location of background planes to maintain a specified
distance from the active object in the Blender scene. It also rotates the planes
to face the active object.

Parameters:
    self: The object that owns the function, typically an operator or a property group.
    context: The current Blender context, which contains references to the active object and scene.
    
Returns:
    None
Example
# In Progress

BackgroundControls

Blender Property Group for controlling background plane settings.

This class defines properties related to the positioning and scaling 
of background planes in Blender. It provides controls for expanding or 
collapsing the background settings UI, setting the distance of the 
background planes from the active object, and scaling the background 
planes along the X, Y, and Z axes.

Attributes:
    expanded (BoolProperty): Expand or collapse the background controls UI.
    plane_distance (FloatProperty): Distance of the background planes from the active object.
    plane_scale_x (FloatProperty): Scale of the background planes on the X axis.
    plane_scale_y (FloatProperty): Scale of the background planes on the Y axis.
    plane_scale_z (FloatProperty): Scale of the background planes on the Z axis.
Example
# In Progress

CallUpdateBackgroundPlaneDistanceOperator

Operator to trigger the update of background plane distances.

This class defines an operator that, when executed, calls the 
'update_background_plane_distance' function to adjust the location 
and orientation of background planes based on the active object in Blender.

Attributes:
    bl_idname (str): Blender identifier for the operator.
    bl_label (str): Label displayed in the Blender UI.
    bl_options (set): Operator options defining its behavior in Blender.
Example
# In Progress

CreateBackgroundImageMeshOperator

Operator to create a background image mesh.

This class defines an operator that, when executed, creates a plane mesh
and assigns a specified background image as its texture. The plane's position
and orientation are also adjusted based on the active object in the Blender scene.

Attributes:
    bl_idname (str): Blender identifier for the operator.
    bl_label (str): Label displayed in the Blender UI.
    bl_options (set): Operator options defining its behavior in Blender.
Example
# In Progress

HideBackgroundPlanesOperator

Operator to toggle the visibility of background planes.

This class defines an operator that, when executed, either hides or shows
the background planes in the Blender scene depending on their current state.

Attributes:
    bl_idname (str): Blender identifier for the operator.
    bl_label (str): Label displayed in the Blender UI.
    bl_options (set): Operator options defining its behavior in Blender.
Example
# In Progress

ImportBackgroundImageOperator

Operator to import a background image into the Blender scene.

This class defines an operator that, when executed, imports a background 
image from a file and stores its reference in the scene properties for 
future use.

Attributes:
    bl_idname (str): Blender identifier for the operator.
    bl_label (str): Label displayed in the Blender UI.
    bl_options (set): Operator options defining its behavior in Blender.
    filepath (StringProperty): Filepath for the image to be imported.
Example
# In Progress

ScaleBackgroundPlanesOperator

Operator to scale the background planes in the Blender scene.

This class defines an operator that, when executed, scales the background 
planes based on the specified X, Y, and Z scaling factors stored in the 
scene's background_controls property group.

Attributes:
    bl_idname (str): Blender identifier for the operator.
    bl_label (str): Label displayed in the Blender UI.
    bl_options (set): Operator options defining its behavior in Blender.
Example
# In Progress

ToggleBackgroundPlanesOperator

Operator to toggle the visibility of background planes in the Blender scene.

This class defines an operator that, when executed, either creates or 
removes background planes at specified distances from the active object. 
These planes are textured with a background image if available.

Attributes:
    bl_idname (str): Blender identifier for the operator.
    bl_label (str): Label displayed in the Blender UI.
    bl_options (set): Operator options defining its behavior in Blender.
    distance (FloatProperty): The distance from the active object at which 
                              the background planes will be created or removed.
Example
# In Progress

execute

Execute the operator.

    This method is called when the operator is run. It scales the background 
    planes based on the X, Y, and Z scaling factors specified in the scene's 
    background_controls property group.
    
    Parameters:
        context: The current Blender context, containing references to the active object and scene.
    
    Returns:
        dict: A dictionary indicating the operator's status. Returns {'FINISHED'} if successful, or {'CANCELLED'} if an error occurs.
Example
# In Progress

invoke

Invoke the operator.

    This method is called to initialize the operator. It sets the distance
    property based on the scene's background_plane_distance.
    
    Parameters:
        context: The current Blender context.
        event: The event that triggered the operator.
    
    Returns:
        dict: The status of the execute method.
Example
# In Progress

Package Information

Maintainer: [email protected]

TraitBlender was created with the help and support of members of the Imageomics Institute.

Clone this wiki locally