Blender Integration

Blender-specific modules for UI and scene integration.

Note: These modules require Blender to run and are not available in standalone Python environments.

Operators

User actions and commands.

Blender Operators for importing robot models.

This module implements the user-facing operators that handle the import of robot descriptions into the Blender environment.

class linkforge.blender.operators.import_ops.LINKFORGE_OT_import_robot_model(*args, **kwargs)

Bases: Operator, ImportHelper

Import robot from URDF or XACRO file.

This operator opens a file browser to select a robot description file, auto-detects the format (URDF or XACRO), validates the model structure, and initiates an asynchronous import process into the Blender scene.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.import_robot_model'

bl_label = 'Import Robot Model'

bl_description = 'Import robot from supported formats (URDF, XACRO, etc.)'

filepath: bpy.props.StringProperty

filter_glob: bpy.props.StringProperty

check(_context)

Check if the operator can update its properties.

Parameters:

_context (Context) – The current Blender context (unused, required by API).

Return type:

Any

Returns:

True to indicate the properties have changed and the UI needs update.

execute(context)

Execute the robot import process.

Parameters:

context (Context) – The execution context.

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

Returns:

Set containing the execution state (e.g., {‘FINISHED’} or {‘CANCELLED’}).

linkforge.blender.operators.import_ops.register()

Register operators.

Return type:

None

linkforge.blender.operators.import_ops.unregister()

Unregister operators.

Return type:

None

Blender Operators for exporting robot models.

This module implements the user-facing operators that handle the export of robot models from Blender to supported description formats.

linkforge.blender.operators.export_ops.working_directory(path)

Context manager for temporarily changing the working directory.

Parameters:

path (Path)

Return type:

Iterator[Path]

class linkforge.blender.operators.export_ops.LINKFORGE_OT_export_robot_model(*args, **kwargs)

Bases: Operator, ExportHelper

Export robot to robot model file

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.export_robot_model'

bl_label = 'Export Robot Model'

bl_description = 'Export robot to supported description formats'

filepath: bpy.props.StringProperty

filter_glob: bpy.props.StringProperty

check(context)

Verify if export can proceed based on current scene state.

Parameters:

context (Context)

Return type:

Any

invoke(context, event)

Invoked before the file browser opens.

Parameters:

• context (Context)

• event (Event)

Return type:

Any

execute(context)

Execute the export.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.export_ops.LINKFORGE_OT_validate_robot(*args, **kwargs)

Bases: Operator

Validate robot structure

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.validate_robot'

bl_label = 'Validate Robot'

bl_description = 'Validate the robot structure for errors'

execute(context)

Execute validation.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

linkforge.blender.operators.export_ops.register()

Register operators.

Return type:

None

linkforge.blender.operators.export_ops.unregister()

Unregister operators.

Return type:

None

Operators for managing robot links.

linkforge.blender.operators.link_ops.schedule_collision_preview_update(obj)

Debounce timer callback to update collision preview.

Registers execute_collision_preview_update as a timer if not already registered.

Parameters:

obj (Object)

Return type:

None

linkforge.blender.operators.link_ops.execute_collision_preview_update()

Timer callback for collision preview debounce.

Return type:

float | None

Returns:

Remaining delay to wait, or None to unregister the timer.

linkforge.blender.operators.link_ops.calculate_inertia_for_link(link_obj)

Calculate inertia tensor for a link.

Parameters:

link_obj (Object) – The link object (Empty)

Return type:

bool

Returns:

True if successful, False otherwise

class linkforge.blender.operators.link_ops.LINKFORGE_OT_add_empty_link(*args, **kwargs)

Bases: Operator

Add a new robot link frame (virtual link) at the 3D cursor.

This operator creates a new Blender Empty object configured as a LinkForge Robot Link at the current cursor position, initializing standard visual axes and link property defaults.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.add_empty_link'

bl_label = 'Add Empty Link'

bl_description = 'Create a new empty link frame at the 3D cursor position'

bl_options = {'REGISTER', 'UNDO'}

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_create_link_from_mesh(*args, **kwargs)

Bases: Operator

Create a robot link from a selected mesh object.

This operator converts a standard Blender mesh into a LinkForge Robot Link by creating a parent Empty frame and establishing the required hierarchy and naming conventions for robot model export.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.create_link_from_mesh'

bl_label = 'Create Link from Mesh'

bl_description = 'Convert selected mesh to a robot link (auto-creates Empty parent and proper naming)'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_generate_collision(*args, **kwargs)

Bases: Operator

Generate collision geometry from visual geometry for the active link.

This operator analyzes the visual mesh(es) of the selected link and automatically generates simplified collision geometry (primitive or mesh) based on the specified collision type.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.generate_collision'

bl_label = 'Generate Collision'

bl_description = 'Auto-generate collision geometry from visual mesh. Requires at least one child mesh with _visual suffix.'

bl_options = {'REGISTER', 'UNDO'}

collision_type: bpy.props.EnumProperty

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_generate_collision_all(*args, **kwargs)

Bases: Operator

Generate collision geometry for all robot links in the scene.

This operator performs a batch collision generation for every object marked as a LinkForge Robot Link, using each link’s stored collision type preferences.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.generate_collision_all'

bl_label = 'Generate All Collisions'

bl_description = 'Generate collision geometry for all robot links in the scene'

bl_options = {'REGISTER', 'UNDO'}

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_toggle_collision_visibility(*args, **kwargs)

Bases: Operator

Toggle collision geometry visibility in the 3D viewport.

This operator recursively toggles the visibility state of all collision mesh children for the selected robot link(s).

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.toggle_collision_visibility'

bl_label = 'Toggle Collision Visibility'

bl_description = 'Show/hide collision geometry in the viewport'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_calculate_inertia(*args, **kwargs)

Bases: Operator

Calculate the inertia tensor from link geometry and mass.

This operator utilizes the Core inertia calculator to derive the moment of inertia and center of mass for the selected link based on its visual and collision volumes.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.calculate_inertia'

bl_label = 'Calculate Inertia'

bl_description = 'Auto-calculate inertia tensor from object geometry and mass'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_calculate_inertia_all(*args, **kwargs)

Bases: Operator

Calculate the inertia tensor for all robot links in the scene.

This operator performs a batch inertia calculation for every LinkForge Robot Link, updating their mass and inertial properties based on their active geometry.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.calculate_inertia_all'

bl_label = 'Calculate All Inertias'

bl_description = 'Auto-calculate inertia tensor for all robot links in the scene'

bl_options = {'REGISTER', 'UNDO'}

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_assign_as_visual(*args, **kwargs)

Bases: Operator

Parent selected mesh(es) to the active link as visual geometry.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.assign_as_visual'

bl_label = 'Assign Selected as Visual'

bl_description = 'Parent selected mesh(es) to the active link as visual geometry'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_assign_as_collision(*args, **kwargs)

Bases: Operator

Parent selected mesh(es) to the active link as collision geometry.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.assign_as_collision'

bl_label = 'Assign Selected as Collision'

bl_description = 'Parent selected mesh(es) to the active link as collision geometry'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_set_active_geometry(*args, **kwargs)

Bases: Operator

Set the active geometry index and select it.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.set_active_geometry'

bl_label = 'Set Active Geometry'

bl_description = 'Set this geometry as active and select it in the viewport'

bl_options = {'REGISTER', 'UNDO'}

geometry_type: bpy.props.EnumProperty

index: bpy.props.IntProperty

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_remove_visual(*args, **kwargs)

Bases: Operator

Remove the active visual mesh from the link.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.remove_visual'

bl_label = 'Remove Visual'

bl_description = 'Remove the active visual mesh from the link'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_remove_collision(*args, **kwargs)

Bases: Operator

Remove the active collision mesh from the link.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.remove_collision'

bl_label = 'Remove Collision'

bl_description = 'Remove the active collision mesh from the link'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_remove_link(*args, **kwargs)

Bases: Operator

Remove link properties and revert to standard mesh

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.remove_link'

bl_label = 'Remove Link'

bl_description = 'Revert this link back to a standard mesh (deletes collision geometry)'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.link_ops.LINKFORGE_OT_add_material_slot(*args, **kwargs)

Bases: Operator

Add a material slot to the visual mesh of a link

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.add_material_slot'

bl_label = 'Add Material Slot'

bl_description = 'Add a material slot to the visual mesh so a material can be assigned'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

linkforge.blender.operators.link_ops.update_collision_quality_realtime(obj, collision_obj)

Update collision quality ratio in realtime via Decimate modifier.

Parameters:

• obj (Object) – The main link object.

• collision_obj (Object) – The generated collision object.

Return type:

None

linkforge.blender.operators.link_ops.register()

Register operators.

Return type:

None

linkforge.blender.operators.link_ops.unregister()

Unregister operators.

Return type:

None

Operators for managing robot joints.

class linkforge.blender.operators.joint_ops.LINKFORGE_OT_create_joint(*args, **kwargs)

Bases: Operator

Create a new robot joint at selected link’s location.

This operator initializes a joint (Blender Empty with colored axes) at the world location of the currently selected link object, setting up default joint properties and hierarchy hints.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.create_joint'

bl_label = 'Create Joint'

bl_description = "Create a new robot joint at the selected link's location and orientation"

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.joint_ops.LINKFORGE_OT_delete_joint(*args, **kwargs)

Bases: Operator

Delete the selected joint Empty.

This operator removes the selected joint object from the scene and cleans up any associated references in the ROS 2 control system to maintain architectural consistency.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.delete_joint'

bl_label = 'Remove Joint'

bl_description = 'Remove the selected joint from the robot structure'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.joint_ops.LINKFORGE_OT_auto_detect_parent_child(*args, **kwargs)

Bases: Operator

Auto-detect parent and child links based on hierarchy.

This operator uses proximity heuristics and world transform analysis to automatically assign parent and child link references to the currently selected joint.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.auto_detect_parent_child'

bl_label = 'Auto-Detect Links'

bl_description = 'Automatically detect parent and child links from object hierarchy'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

linkforge.blender.operators.joint_ops.register()

Register operators.

Return type:

None

linkforge.blender.operators.joint_ops.unregister()

Unregister operators.

Return type:

None

Operators for managing robot sensors.

class linkforge.blender.operators.sensor_ops.LINKFORGE_OT_create_sensor(*args, **kwargs)

Bases: Operator

Create a new robot sensor at selected link’s location.

This operator initializes a sensor (Blender Empty with a sphere display) at the world origin of the currently selected link object, setting up parent-child relationships and default sensor properties.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.create_sensor'

bl_label = 'Create Sensor'

bl_description = "Create a new robot sensor at the selected link's location and orientation"

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.sensor_ops.LINKFORGE_OT_delete_sensor(*args, **kwargs)

Bases: Operator

Delete the selected sensor Empty.

This operator removes the selected sensor object from the scene and cleans up its references in the LinkForge hierarchy.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.delete_sensor'

bl_label = 'Remove Sensor'

bl_description = 'Remove the selected sensor from the robot'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the operator.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

linkforge.blender.operators.sensor_ops.register()

Register operators.

Return type:

None

linkforge.blender.operators.sensor_ops.unregister()

Unregister operators.

Return type:

None

Add a joint to the ros2_control system.

This operator allows users to select a joint from the robot’s kinematic tree and include it in the ROS 2 control configuration, setting up default command and state interfaces.

class linkforge.blender.operators.control_ops.LINKFORGE_OT_add_ros2_control_joint(*args, **kwargs)

Bases: Operator

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.add_ros2_control_joint'

bl_label = 'Add Joint'

bl_description = "Add a joint from the robot's kinematic tree to the control system"

bl_options = {'REGISTER', 'UNDO'}

joint_name: bpy.props.StringProperty

classmethod poll(context)

Check if operators can run.

Parameters:

context (Context) – The current Blender context.

Return type:

bool

Returns:

True if the scene has LinkForge properties initialized.

execute(context)

Execute the operator.

Parameters:

context (Context) – The execution context.

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

Returns:

Set containing the execution state (e.g., {‘FINISHED’}).

class linkforge.blender.operators.control_ops.LINKFORGE_OT_remove_ros2_control_joint(*args, **kwargs)

Bases: Operator

Remove a joint from the ros2_control system.

This operator removes the currently selected joint from the ROS 2 control configuration list.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.remove_ros2_control_joint'

bl_label = 'Remove Joint'

bl_description = 'Remove the selected joint from the control system'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operators can run.

Parameters:

context (Context) – The current Blender context.

Return type:

bool

Returns:

True if there are joints in the control system.

execute(context)

Execute the operator.

Parameters:

context (Context) – The execution context.

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

Returns:

Set containing the execution state.

class linkforge.blender.operators.control_ops.LINKFORGE_OT_move_ros2_control_joint(*args, **kwargs)

Bases: Operator

Move a joint up or down in the control interface list.

This is a UI helper operator to reorder how joints appear in the LinkForge control panel.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.move_ros2_control_joint'

bl_label = 'Move Joint'

bl_description = 'Move joint up or down in the list (cosmetic only)'

bl_options = {'REGISTER', 'UNDO'}

direction: bpy.props.StringProperty

classmethod poll(context)

Check if operators can run.

Parameters:

context (Context) – The current Blender context.

Return type:

bool

Returns:

True if there are multiple joints to move.

execute(context)

Execute the operator.

Parameters:

context (Context) – The execution context.

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

Returns:

Set containing the execution state.

class linkforge.blender.operators.control_ops.LINKFORGE_OT_add_ros2_control_parameter(*args, **kwargs)

Bases: Operator

Add a parameter to ros2_control (global or joint).

This operator adds a new key-value pair to either the global hardware parameters or the parameters of the currently selected joint.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.add_ros2_control_parameter'

bl_label = 'Add Parameter'

bl_description = 'Add a key-value parameter to the control system'

bl_options = {'REGISTER', 'UNDO'}

target: bpy.props.StringProperty

classmethod poll(context)

Check if the operator can be executed.

Parameters:

context (Context) – The current Blender context.

Return type:

bool

Returns:

True if LinkForge properties are initialized in the scene.

execute(context)

Execute the addition of a parameter.

Parameters:

context (Context) – The execution context.

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

Returns:

Set containing the execution state.

class linkforge.blender.operators.control_ops.LINKFORGE_OT_remove_ros2_control_parameter(*args, **kwargs)

Bases: Operator

Remove a parameter from ros2_control.

This operator deletes a key-value pair from either the global hardware parameters or a specific joint’s parameter list.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.remove_ros2_control_parameter'

bl_label = 'Remove Parameter'

bl_description = 'Remove a hardware or joint parameter'

bl_options = {'REGISTER', 'UNDO'}

target: bpy.props.StringProperty

index: bpy.props.IntProperty

classmethod poll(context)

Check if the operator can be executed.

Parameters:

context (Context) – The current Blender context.

Return type:

bool

Returns:

True if LinkForge properties are initialized.

execute(context)

Execute the removal of a parameter.

Parameters:

context (Context) – The execution context.

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

Returns:

Set containing the execution state.

class linkforge.blender.operators.control_ops.LINKFORGE_OT_purge_ros2_control_data(*args, **kwargs)

Bases: Operator

Clear all joints and parameters from the ros2_control configuration.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.purge_ros2_control_data'

bl_label = 'Purge Control Data'

bl_description = 'Clear all joints and parameters from the control system'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operators can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the purge.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.control_ops.LINKFORGE_OT_prune_ros2_control_joints(*args, **kwargs)

Bases: Operator

Remove joints from ros2_control that no longer exist in the scene.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.prune_ros2_control_joints'

bl_label = 'Prune Missing Joints'

bl_description = 'Remove joints from the control system that no longer exist in the scene'

bl_options = {'REGISTER', 'UNDO'}

classmethod poll(context)

Check if operator can run.

Parameters:

context (Context)

Return type:

bool

execute(context)

Execute the pruning of orphaned joints.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

linkforge.blender.operators.control_ops.register()

Register operators.

Return type:

None

linkforge.blender.operators.control_ops.unregister()

Unregister operators.

Return type:

None

Operators for viewport selection and tree navigation.

class linkforge.blender.operators.selection_ops.LINKFORGE_OT_select_tree_object(*args, **kwargs)

Bases: Operator

Select object from kinematic tree.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.select_tree_object'

bl_label = 'Select Object'

bl_description = 'Select this object in the 3D viewport'

bl_options = {'REGISTER', 'UNDO'}

object_name: bpy.props.StringProperty

object_type: bpy.props.StringProperty

execute(context)

Execute the operator.

Parameters:

context (Context) – The execution context.

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

Returns:

Set containing the execution state (e.g., {‘FINISHED’} or {‘CANCELLED’}).

class linkforge.blender.operators.selection_ops.LINKFORGE_OT_select_root_link(*args, **kwargs)

Bases: Operator

Select the root link of the robot.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.select_root_link'

bl_label = 'Select Root Link'

bl_description = 'Select the root link of the robot in the 3D viewport'

bl_options = {'REGISTER', 'UNDO'}

execute(context)

Execute the operator.

Parameters:

context (Context) – The execution context.

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

Returns:

Set containing the execution state (e.g., {‘FINISHED’} or {‘CANCELLED’}).

linkforge.blender.operators.selection_ops.register()

Register operators.

Return type:

None

linkforge.blender.operators.selection_ops.unregister()

Unregister operators.

Return type:

None

Operators for viewport display, gizmo fitting, and visibility toggles.

class linkforge.blender.operators.display_ops.LINKFORGE_OT_auto_fit_gizmo_sizes(*args, **kwargs)

Bases: Operator

Automatically fit gizmo and empty display sizes to the current robot’s physical bounds.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.auto_fit_gizmo_sizes'

bl_label = 'Fit Gizmos to Robot'

bl_description = 'Auto-scale joint, link, sensor, and inertia display markers to match robot size'

bl_options = {'REGISTER', 'UNDO'}

execute(context)

Execute the auto-fit calculation and update preferences.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

class linkforge.blender.operators.display_ops.LINKFORGE_OT_toggle_collisions(*args, **kwargs)

Bases: Operator

Toggle viewport visibility for all collision meshes in the robot.

Parameters:

• args (Any)

• kwargs (Any)

bl_idname = 'linkforge.toggle_collisions'

bl_label = 'Toggle Collisions'

bl_description = 'Show or hide all collision meshes in the 3D viewport'

bl_options = {'REGISTER', 'UNDO'}

execute(context)

Toggle the scene show_collisions property.

Parameters:

context (Context)

Return type:

set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]

linkforge.blender.operators.display_ops.register()

Register display operators.

Return type:

None

linkforge.blender.operators.display_ops.unregister()

Unregister display operators.

Return type:

None

Panels

UI Panels for managing robot data.

Main UI Panel for LinkForge.

This module defines the parent panel ‘LINKFORGE_PT_forge’ that other panels attach to. It must be registered BEFORE any child panels.

class linkforge.blender.panels.forge_panel.LINKFORGE_PT_forge(*args, **kwargs)

Bases: Panel

Parent panel for building robot structure.

Parameters:

• args (Any)

• kwargs (Any)

bl_label = 'Forge'

bl_description = 'Step 1: Create robot structure with links and joints'

bl_idname = 'LINKFORGE_PT_forge'

bl_space_type = 'VIEW_3D'

bl_region_type = 'UI'

bl_category = 'LinkForge'

bl_order = 0

draw(context)

Draw the panel.

Parameters:

context (Context) – The current Blender context.

Return type:

None

linkforge.blender.panels.forge_panel.register()

Register panel.

Return type:

None

linkforge.blender.panels.forge_panel.unregister()

Unregister panel.

Return type:

None

UI Panel for managing robot links.

class linkforge.blender.panels.link_panel.LINKFORGE_PT_links(*args, **kwargs)

Bases: Panel

Panel for robot link properties in 3D Viewport sidebar.

Parameters:

• args (Any)

• kwargs (Any)

bl_label = 'Links'

bl_idname = 'LINKFORGE_PT_links'

bl_space_type = 'VIEW_3D'

bl_region_type = 'UI'

bl_category = 'LinkForge'

bl_parent_id = 'LINKFORGE_PT_forge'

bl_order = 1

draw(context)

Draw the panel.

Parameters:

context (Context)

Return type:

None

linkforge.blender.panels.link_panel.register()

Register panel.

Return type:

None

linkforge.blender.panels.link_panel.unregister()

Unregister panel.

Return type:

None

UI Panel for managing robot joints.

class linkforge.blender.panels.joint_panel.LINKFORGE_PT_joints(*args, **kwargs)

Bases: Panel

Panel for robot joint properties in 3D Viewport sidebar.

Parameters:

• args (Any)

• kwargs (Any)

bl_label = 'Joints'

bl_idname = 'LINKFORGE_PT_joints'

bl_space_type = 'VIEW_3D'

bl_region_type = 'UI'

bl_category = 'LinkForge'

bl_parent_id = 'LINKFORGE_PT_forge'

bl_order = 2

draw(context)

Draw the panel.

Parameters:

context (Context)

Return type:

None

linkforge.blender.panels.joint_panel.register()

Register panel.

Return type:

None

linkforge.blender.panels.joint_panel.unregister()

Unregister panel.

Return type:

None

UI Panel for managing robot sensors.

class linkforge.blender.panels.sensor_panel.LINKFORGE_PT_perceive(*args, **kwargs)

Bases: Panel

Panel for adding sensors to perceive the environment.

Parameters:

• args (Any)

• kwargs (Any)

bl_label = 'Perceive'

bl_description = 'Step 2: Add sensors for perception (cameras, LiDAR, IMU, GPS)'

bl_idname = 'LINKFORGE_PT_perceive'

bl_space_type = 'VIEW_3D'

bl_region_type = 'UI'

bl_category = 'LinkForge'

bl_order = 1

bl_options = {'DEFAULT_CLOSED'}

draw(context)

Draw the panel.

Parameters:

context (Context) – The current Blender context.

Return type:

None

linkforge.blender.panels.sensor_panel.register()

Register panel.

Return type:

None

linkforge.blender.panels.sensor_panel.unregister()

Unregister panel.

Return type:

None

UI Panel for managing centralized ROS 2 robot control.

class linkforge.blender.panels.control_panel.LINKFORGE_UL_ros2_control_joints(*args, **kwargs)

Bases: UIList

UI List representation for ROS 2 control joints.

This class defines how individual joints are displayed in the centralized control interface, including status indicators for command interfaces.

Parameters:

• args (Any)

• kwargs (Any)

draw_item(_context, layout, _data, item, _icon, _active_data, _active_propname, _index=0, _flt_flag=0)

Draw an item in the list.

Parameters:

• _context (Context) – The current Blender context (unused, required by API).

• layout (UILayout) – The current UILayout.

• _data (Any) – The property group being displayed (unused, required by API).

• item (Any) – The current list item.

• _icon (int | None) – The icon for the item (unused, required by API).

• _active_data (Any) – Required by Blender API (pointing to the collection owner).

• _active_propname (str | None) – Required by Blender API (name of the active property).

• _index (int | None) – Current item index (unused, required by API).

• _flt_flag (int | None) – Filter flag (unused, required by API).

Return type:

None

class linkforge.blender.panels.control_panel.LINKFORGE_PT_control(*args, **kwargs)

Bases: Panel

Panel for configuring motor control and centralized ros2_control.

Parameters:

• args (Any)

• kwargs (Any)

bl_label = 'Control'

bl_description = 'Step 3: Configure centralized ros2_control system and interfaces'

bl_idname = 'LINKFORGE_PT_control'

bl_space_type = 'VIEW_3D'

bl_region_type = 'UI'

bl_category = 'LinkForge'

bl_order = 2

bl_options = {'DEFAULT_CLOSED'}

draw_joint_details(layout, props, joint_item)

Draw the detailed interface settings for a single joint.

This helper method renders the command and state interface toggles, as well as joint-specific ROS 2 parameters, in a localized box.

Parameters:

• layout (UILayout) – The parent UILayout to draw into.

• props (Any) – The global LinkForge scene property group.

• joint_item (Any) – The specific joint property item being configured.

Return type:

None

draw(context)

Draw the panel.

Parameters:

context (Context)

Return type:

None

class linkforge.blender.panels.control_panel.LINKFORGE_MT_add_control_joint(*args, **kwargs)

Bases: Menu

Menu to add joints from the scene to ros2_control.

Parameters:

• args (Any)

• kwargs (Any)

bl_label = 'Add Joint'

draw(context)

Parameters:

context (Context)

Return type:

None

linkforge.blender.panels.control_panel.register()

Register panel.

Return type:

None

linkforge.blender.panels.control_panel.unregister()

Unregister panel.

Return type:

None

UI Panel for robot validation and export.

class linkforge.blender.panels.export_panel.LINKFORGE_PT_export_panel(*args, **kwargs)

Bases: Panel

Validate & Export panel - robot configuration, validation, and export settings.

Parameters:

• args (Any)

• kwargs (Any)

bl_label = 'Validate & Export'

bl_description = 'Step 4: Validate robot structure and export to robot model file'

bl_idname = 'LINKFORGE_PT_export_panel'

bl_space_type = 'VIEW_3D'

bl_region_type = 'UI'

bl_category = 'LinkForge'

bl_order = 3

bl_options = {'DEFAULT_CLOSED'}

draw(context)

Draw the panel.

Parameters:

context (Context)

Return type:

None

linkforge.blender.panels.export_panel.register()

Register panel.

Return type:

None

linkforge.blender.panels.export_panel.unregister()

Unregister panel.

Return type:

None

Properties

Blender scene properties for storing robot data.

Per-mesh geometry properties for visual and collision objects.

linkforge.blender.properties.geom_props.on_collision_quality_update(self, _context)

Trigger real-time collision mesh update when geometry properties change.

Parameters:

• self (GeomPropertyGroup)

• _context (Context)

Return type:

None

linkforge.blender.properties.geom_props.on_geometry_type_update(self, _context)

Trigger real-time collision mesh update when geometry properties change.

Parameters:

• self (GeomPropertyGroup)

• _context (Context)

Return type:

None

class linkforge.blender.properties.geom_props.GeomPropertyGroup(*args, **kwargs)

Bases: PropertyGroup

Properties stored directly on each visual/collision mesh object.

Parameters:

• args (Any)

• kwargs (Any)

geom_role: bpy.props.EnumProperty

geometry_type: bpy.props.EnumProperty

collision_quality: bpy.props.FloatProperty

linkforge.blender.properties.geom_props.register()

Register property group.

Return type:

None

linkforge.blender.properties.geom_props.unregister()

Unregister property group.

Return type:

None

Blender Property Groups for robot-level configuration.

This module defines the property groups used to store robot-level metadata and export settings directly within the Blender Scene. These properties drive the UI panels and provide the configuration parameters for the URDF and XACRO generators, including:

• Robot Metadata: Name and global settings.

• Export Configuration: Target formats (URDF/XACRO) and validation toggles.

• Advanced XACRO Settings: Toggles for property extraction, macro generation, and modular file splitting.

linkforge.blender.properties.robot_props.update_collision_visibility(self, context)

Update visibility of all collision meshes in the scene.

Parameters:

• self (RobotPropertyGroup)

• context (Context)

Return type:

None

class linkforge.blender.properties.robot_props.RobotPropertyGroup(*args, **kwargs)

Bases: PropertyGroup

Global robot properties stored on the Scene.

Parameters:

• args (Any)

• kwargs (Any)

robot_name: bpy.props.StringProperty

export_format: bpy.props.EnumProperty

use_ros2_control: bpy.props.BoolProperty

ros2_control_name: bpy.props.StringProperty

ros2_control_type: bpy.props.EnumProperty

hardware_plugin: bpy.props.StringProperty

gazebo_plugin_name: bpy.props.StringProperty

controllers_yaml_path: bpy.props.StringProperty

ros2_control_joints: bpy.props.CollectionProperty

ros2_control_active_joint_index: bpy.props.IntProperty

ros2_control_parameters: bpy.props.CollectionProperty

show_ros2_control_parameters: bpy.props.BoolProperty

export_meshes: bpy.props.BoolProperty

mesh_format: bpy.props.EnumProperty

mesh_directory_name: bpy.props.StringProperty

validate_before_export: bpy.props.BoolProperty

strict_mode: bpy.props.BoolProperty

xacro_advanced_mode: bpy.props.BoolProperty

xacro_extract_materials: bpy.props.BoolProperty

xacro_extract_dimensions: bpy.props.BoolProperty

xacro_generate_macros: bpy.props.BoolProperty

xacro_split_files: bpy.props.BoolProperty

show_collisions: bpy.props.BoolProperty

is_importing: bpy.props.BoolProperty

abort_import: bpy.props.BoolProperty

import_status: bpy.props.StringProperty

linkforge.blender.properties.robot_props.register()

Register property group.

Return type:

None

linkforge.blender.properties.robot_props.unregister()

Unregister property group.

Return type:

None

Blender Property Groups for robot links.

These properties are stored on Blender objects and define link characteristics.

class linkforge.blender.properties.link_props.LinkPropertyGroup(*args, **kwargs)

Bases: PropertyGroup

Properties for a robot link stored on a Blender object.

Parameters:

• args (Any)

• kwargs (Any)

is_robot_link: bpy.props.BoolProperty

source_name_stored: bpy.props.StringProperty

link_name: bpy.props.StringProperty

use_auto_inertia: bpy.props.BoolProperty

mass: bpy.props.FloatProperty

inertia_ixx: bpy.props.FloatProperty

inertia_ixy: bpy.props.FloatProperty

inertia_ixz: bpy.props.FloatProperty

inertia_iyy: bpy.props.FloatProperty

inertia_iyz: bpy.props.FloatProperty

inertia_izz: bpy.props.FloatProperty

inertia_origin_xyz: bpy.props.FloatVectorProperty

inertia_origin_rpy: bpy.props.FloatVectorProperty

use_simulation_props: bpy.props.BoolProperty

self_collide: bpy.props.BoolProperty

gravity: bpy.props.BoolProperty

mu: bpy.props.FloatProperty

mu2: bpy.props.FloatProperty

kp: bpy.props.FloatProperty

kp_ui: bpy.props.StringProperty

kd: bpy.props.FloatProperty

kd_ui: bpy.props.StringProperty

active_visual_index: bpy.props.IntProperty

active_collision_index: bpy.props.IntProperty

use_material: bpy.props.BoolProperty

linkforge.blender.properties.link_props.register()

Register property group.

Return type:

None

linkforge.blender.properties.link_props.unregister()

Unregister property group.

Return type:

None

linkforge.blender.properties.link_props.sanitize_name(name, allow_hyphen=True)

Sanitize a name for robot model and Python identifier compatibility.

Replaces invalid characters with underscores and ensures it doesn’t start with a digit.

Parameters:

• name (str | None) – Original name

• allow_hyphen (bool) – Whether to allow hyphens (valid in many formats like URDF/SDF, invalid in Python)

Return type:

str

Returns:

Sanitized name

Blender Property Groups for robot joints.

These properties are stored on Empty objects and define joint characteristics.

linkforge.blender.properties.joint_props.get_joint_name(self)

Getter for joint_name - returns the persistent source identity.

Parameters:

self (JointPropertyGroup) – The JointPropertyGroup instance.

Return type:

str

Returns:

The sanitized robot model name.

linkforge.blender.properties.joint_props.set_joint_name(self, value)

Setter for joint_name - updates persistent identity and object name.

Parameters:

• self (JointPropertyGroup) – The JointPropertyGroup instance.

• value (str) – The new name value to set.

Return type:

None

linkforge.blender.properties.joint_props.update_joint_hierarchy(self, context)

Update Blender object hierarchy when parent/child links change.

Establishes hierarchy: parent_link → joint → child_link This matches import behavior and shows kinematic tree in outliner.

Parameters:

• self (JointPropertyGroup)

• context (Context)

Return type:

None

linkforge.blender.properties.joint_props.poll_robot_link(_self, obj)

Filter to only allow robot link objects in pointer selection.

Parameters:

• _self (JointPropertyGroup)

• obj (Object)

Return type:

bool

linkforge.blender.properties.joint_props.poll_robot_joint(self, obj)

Filter to only allow other robot joint objects in pointer selection.

Parameters:

• self (JointPropertyGroup)

• obj (Object)

Return type:

bool

class linkforge.blender.properties.joint_props.JointPropertyGroup(*args, **kwargs)

Bases: PropertyGroup

Properties for a robot joint stored on an Empty object.

Parameters:

• args (Any)

• kwargs (Any)

is_robot_joint: bpy.props.BoolProperty

source_name_stored: bpy.props.StringProperty

joint_name: bpy.props.StringProperty

joint_type: bpy.props.EnumProperty

parent_link: bpy.props.PointerProperty

child_link: bpy.props.PointerProperty

axis: bpy.props.EnumProperty

custom_axis_x: bpy.props.FloatProperty

custom_axis_y: bpy.props.FloatProperty

custom_axis_z: bpy.props.FloatProperty

use_limits: bpy.props.BoolProperty

limit_lower: bpy.props.FloatProperty

limit_upper: bpy.props.FloatProperty

limit_effort: bpy.props.FloatProperty

limit_velocity: bpy.props.FloatProperty

use_dynamics: bpy.props.BoolProperty

dynamics_damping: bpy.props.FloatProperty

dynamics_friction: bpy.props.FloatProperty

use_mimic: bpy.props.BoolProperty

mimic_joint: bpy.props.PointerProperty

mimic_multiplier: bpy.props.FloatProperty

mimic_offset: bpy.props.FloatProperty

use_safety_controller: bpy.props.BoolProperty

safety_soft_lower_limit: bpy.props.FloatProperty

safety_soft_upper_limit: bpy.props.FloatProperty

safety_k_position: bpy.props.FloatProperty

safety_k_velocity: bpy.props.FloatProperty

use_calibration: bpy.props.BoolProperty

calibration_rising: bpy.props.FloatProperty

use_calibration_rising: bpy.props.BoolProperty

calibration_falling: bpy.props.FloatProperty

use_calibration_falling: bpy.props.BoolProperty

linkforge.blender.properties.joint_props.register()

Register property group.

Return type:

None

linkforge.blender.properties.joint_props.unregister()

Unregister property group.

Return type:

None

Blender Property Groups for robot sensors.

These properties are stored on Empty objects and define sensor characteristics.

linkforge.blender.properties.sensor_props.get_sensor_name(self)

Getter for sensor_name - returns the persistent robot model identity.

Parameters:

self (SensorPropertyGroup) – The SensorPropertyGroup instance.

Return type:

str

Returns:

The sanitized robot model name.

linkforge.blender.properties.sensor_props.set_sensor_name(self, value)

Setter for sensor_name - updates persistent identity and object name.

Parameters:

• self (SensorPropertyGroup) – The SensorPropertyGroup instance.

• value (str) – The new name value to set.

Return type:

None

linkforge.blender.properties.sensor_props.update_sensor_hierarchy(self, context)

Update Blender object hierarchy when attached link changes.

Automatically reparents sensor to new link and moves to link’s collection. This ensures visual hierarchy matches logical structure.

Parameters:

• self (SensorPropertyGroup)

• context (Context)

Return type:

None

linkforge.blender.properties.sensor_props.poll_robot_link(_self, obj)

Filter to only allow robot link objects in pointer selection.

Parameters:

• _self (SensorPropertyGroup)

• obj (Object)

Return type:

bool

class linkforge.blender.properties.sensor_props.SensorPropertyGroup(*args, **kwargs)

Bases: PropertyGroup

Properties for a robot sensor stored on an Empty object.

Parameters:

• args (Any)

• kwargs (Any)

is_robot_sensor: bpy.props.BoolProperty

source_name_stored: bpy.props.StringProperty

sensor_name: bpy.props.StringProperty

sensor_type: bpy.props.EnumProperty

attached_link: bpy.props.PointerProperty

update_rate: bpy.props.FloatProperty

always_on: bpy.props.BoolProperty

visualize: bpy.props.BoolProperty

topic_name: bpy.props.StringProperty

camera_horizontal_fov: bpy.props.FloatProperty

camera_width: bpy.props.IntProperty

camera_height: bpy.props.IntProperty

camera_near_clip: bpy.props.FloatProperty

camera_far_clip: bpy.props.FloatProperty

camera_format: bpy.props.EnumProperty

lidar_horizontal_samples: bpy.props.IntProperty

lidar_horizontal_min_angle: bpy.props.FloatProperty

lidar_horizontal_max_angle: bpy.props.FloatProperty

lidar_vertical_samples: bpy.props.IntProperty

lidar_vertical_min_angle: bpy.props.FloatProperty

lidar_vertical_max_angle: bpy.props.FloatProperty

lidar_range_min: bpy.props.FloatProperty

lidar_range_max: bpy.props.FloatProperty

lidar_range_resolution: bpy.props.FloatProperty

contact_collision: bpy.props.StringProperty

use_noise: bpy.props.BoolProperty

noise_type: bpy.props.EnumProperty

noise_mean: bpy.props.FloatProperty

noise_stddev: bpy.props.FloatProperty

use_gazebo_plugin: bpy.props.BoolProperty

plugin_filename: bpy.props.StringProperty

plugin_raw_xml: bpy.props.StringProperty

linkforge.blender.properties.sensor_props.register()

Register property group.

Return type:

None

linkforge.blender.properties.sensor_props.unregister()

Unregister property group.

Return type:

None

Blender Property Groups for centralized ros2_control configuration.

These properties are stored on the Scene and define the mapping between robot joints and ros2_control interfaces (command and state).

class linkforge.blender.properties.control_props.Ros2ControlParameterProperty(*args, **kwargs)

Bases: PropertyGroup

Key-value pair for ros2_control parameters.

Parameters:

• args (Any)

• kwargs (Any)

name: bpy.props.StringProperty

value: bpy.props.StringProperty

class linkforge.blender.properties.control_props.Ros2ControlInterfaceProperty(*args, **kwargs)

Bases: PropertyGroup

Property group for a single ros2_control interface.

Parameters:

• args (Any)

• kwargs (Any)

name: bpy.props.EnumProperty

parameters: bpy.props.CollectionProperty

class linkforge.blender.properties.control_props.Ros2ControlJointProperty(*args, **kwargs)

Bases: PropertyGroup

Property group for a joint’s ros2_control mapping.

Parameters:

• args (Any)

• kwargs (Any)

name: bpy.props.StringProperty

joint_obj: bpy.props.PointerProperty

cmd_position: bpy.props.BoolProperty

cmd_velocity: bpy.props.BoolProperty

cmd_effort: bpy.props.BoolProperty

state_position: bpy.props.BoolProperty

state_velocity: bpy.props.BoolProperty

state_effort: bpy.props.BoolProperty

show_parameters: bpy.props.BoolProperty

parameters: bpy.props.CollectionProperty

linkforge.blender.properties.control_props.register()

Register property groups.

Return type:

None

linkforge.blender.properties.control_props.unregister()

Unregister property groups.

Return type:

None

Blender Property Groups for validation results.

These properties store the last validation result for display in the UI.

class linkforge.blender.properties.validation_props.ValidationIssueProperty(*args, **kwargs)

Bases: PropertyGroup

A single validation issue (error or warning).

Parameters:

• args (Any)

• kwargs (Any)

title: bpy.props.StringProperty

message: bpy.props.StringProperty

suggestion: bpy.props.StringProperty

affected_objects: bpy.props.StringProperty

error_code: bpy.props.StringProperty

property has_suggestion: bool

Check if this issue has a suggestion.

property has_objects: bool

Check if this issue has affected objects.

property objects_str: str

Get affected objects as a formatted string.

property affected_object_list: list[str]

Get list of individual affected object names.

property message_lines: list[str]

Split message into lines for display (max 55 chars per line).

property suggestion_lines: list[str]

Split suggestion into lines for display (max 55 chars per line).

class linkforge.blender.properties.validation_props.ValidationResultProperty(*args, **kwargs)

Bases: PropertyGroup

Validation result stored in window manager.

Parameters:

• args (Any)

• kwargs (Any)

has_results: bpy.props.BoolProperty

is_valid: bpy.props.BoolProperty

error_count: bpy.props.IntProperty

warning_count: bpy.props.IntProperty

link_count: bpy.props.IntProperty

joint_count: bpy.props.IntProperty

dof_count: bpy.props.IntProperty

errors: bpy.props.CollectionProperty

warnings: bpy.props.CollectionProperty

show_errors: bpy.props.BoolProperty

show_warnings: bpy.props.BoolProperty

clear()

Clear all validation results.

Return type:

None

get_error(index)

Get error by index.

Parameters:

index (int)

Return type:

ValidationIssueProperty

get_warning(index)

Get warning by index.

Parameters:

index (int)

Return type:

ValidationIssueProperty

linkforge.blender.properties.validation_props.register()

Register property groups.

Return type:

None

linkforge.blender.properties.validation_props.unregister()

Unregister property groups.

Return type:

None

Adapters

Conversion between Blender and core models.

Converters between Blender properties and Core models.

These functions bridge the gap between Blender’s property system and LinkForge’s core data models.

class linkforge.blender.adapters.blender_to_core.SceneToRobotTranslator(context, meshes_dir=None, dry_run=False, depsgraph=None)

Bases: object

Orchestrates the conversion of a Blender scene to a Core Robot model.

This class follows the SOLID principles by encapsulating the translation logic and leveraging the RobotBuilder (Composer) API for structural integrity.

Parameters:

• context (IBlenderContext)

• meshes_dir (Path | None)

• dry_run (bool)

• depsgraph (Any | None)

__init__(context, meshes_dir=None, dry_run=False, depsgraph=None)

Parameters:

• context (IBlenderContext)

• meshes_dir (Path | None)

• dry_run (bool)

• depsgraph (Any | None)

translate(raise_on_error=True)

Perform the translation and return the built Robot model.

Parameters:

raise_on_error (bool)

Return type:

tuple[Robot, ValidationResult]

linkforge.blender.adapters.blender_to_core.scene_to_robot(context, meshes_dir=None, dry_run=False, raise_on_error=True)

Convert entire Blender scene to Core Robot using the Translator orchestrator.

Parameters:

• context (IBlenderContext | bpy.types.Context)

• meshes_dir (Path | None)

• dry_run (bool)

• raise_on_error (bool)

Return type:

tuple[Robot, ValidationResult]

Scene Builder utilities for creating Blender objects from generic Robot models.

linkforge.blender.adapters.core_to_blender.create_material_from_color(context, color, name)

Create Blender material from Color model.

Parameters:

• context (IBlenderContext) – Blender context adapter

• color (Color) – Color model

• name (str) – Material name

Return type:

bpy.types.Material | None

Returns:

Blender Material or None

linkforge.blender.adapters.core_to_blender.create_primitive_mesh(context, geometry, name)

Create a Blender mesh object from primitive geometry.

This function generates native Blender mesh primitives (Cube, Cylinder, Sphere) based on the Core geometry model and applies the correct dimensions and format-specific metadata tags.

Parameters:

• context (IBlenderContext) – Blender context adapter

• geometry (Box | Cylinder | Sphere) – One of Box, Cylinder, or Sphere models.

• name (str) – Name to assign to the created Blender object.

Return type:

bpy.types.Object | None

Returns:

The created Blender Object or None if creation failed.

linkforge.blender.adapters.core_to_blender.import_mesh_file(context, mesh_path, name)

Import an external mesh file into the Blender scene.

Supported formats include STL, OBJ, and GLB. This function utilizes modern Blender WM operators for improved performance and stability.

Parameters:

• context (IBlenderContext) – Blender context adapter

• mesh_path (Path) – Absolute path to the mesh file.

• name (str) – Name to assign to the imported object.

Return type:

bpy.types.Object | None

Returns:

The imported Blender Object or None if import failed.

linkforge.blender.adapters.core_to_blender.normalize_and_consolidate_imported_objects(context, objects, name)

Consolidation logic that processes all supplied objects (meshes → join, others → delete).

Parameters:

• context (IBlenderContext)

• objects (typing.Iterable[bpy.types.Object])

• name (str)

Return type:

bpy.types.Object | None

linkforge.blender.adapters.core_to_blender.create_link_object(context, link, robot, source_directory, collection=None)

Create Blender object from Link model with support for multiple visual/collision elements.

Parameters:

• context (IBlenderContext) – Blender context adapter

• link (Link) – Link model

• robot (Robot) – Robot model (for resolving resources)

• source_directory (Path) – Directory containing source file (for resolving relative paths)

• collection (bpy.types.Collection | None) – Blender Collection to add object to

Return type:

bpy.types.Object | None

Returns:

Blender Object or None (returns the link Empty object with properties)

linkforge.blender.adapters.core_to_blender.create_joint_object(context, joint, link_objects, collection=None)

Create Empty object from Joint model.

Parameters:

• context (IBlenderContext) – Blender context adapter

• joint (Joint) – Joint model

• link_objects (dict[str, bpy.types.Object]) – Dictionary mapping link names to Blender objects

• collection (bpy.types.Collection | None) – Blender Collection to add object to

Return type:

bpy.types.Object | None

Returns:

Blender Empty object or None

linkforge.blender.adapters.core_to_blender.create_sensor_object(context, sensor, link_objects, collection=None)

Create Empty object from Sensor model.

Parameters:

• context (IBlenderContext) – Blender context adapter

• sensor (typing.Any) – Sensor model from core

• link_objects (dict[str, bpy.types.Object]) – Dictionary mapping link names to Blender objects

• collection (bpy.types.Collection | None) – Blender Collection to add object to

Return type:

bpy.types.Object | None

Returns:

Blender Empty object or None

linkforge.blender.adapters.core_to_blender.setup_scene_for_robot(context, robot)

Initialize scene properties for a robot model.

This populates the Centralized Control Dashboard, Gazebo settings, and metadata based on the robot model.

Parameters:

• context (IBlenderContext) – Blender context adapter

• robot (Robot) – Robot model to extract settings from

Return type:

None

linkforge.blender.adapters.core_to_blender.import_robot_to_scene(robot, source_path, context)

Import Robot model to Blender scene.

Parameters:

• robot (Robot) – Robot model

• source_path (Path) – Path to source file

• context (IBlenderContext | bpy.types.Context) – Blender context (real or adapter)

Return type:

bool

Geometry and material extraction from Blender objects to LinkForge core models.

This module provides focused utilities to extract primitive shapes, triangle mesh data, and materials from Blender objects without coupling to scene translation.

linkforge.blender.adapters.geometry_extractor.detect_primitive_type(obj)

Detect if a Blender mesh object matches a standard primitive shape.

Analyzes topology and dimensions to determine if the object can be exported as a URDF primitive (BOX, CYLINDER, or SPHERE). This function is critical for optimizing exports and ensuring compatibility with physics simulators.

Parameters:

obj (bpy.types.Object | None) – The Blender mesh object to analyze.

Return type:

str | None

Returns:

“box”, “cylinder”, or “sphere” if a match is detected, else None.

linkforge.blender.adapters.geometry_extractor.get_object_geometry(obj, link_name=None, geom_purpose='visual', meshes_dir=None, mesh_format='STL', simplify=False, decimation_ratio=0.5, dry_run=False, suffix='', depsgraph=None)

Extract geometry from Blender object.

Parameters:

• obj (bpy.types.Object | None) – Blender Object

• link_name (str | None) – Name of the link (for mesh filename)

• geom_purpose (str) – “visual” or “collision” (use PURPOSE_VISUAL, PURPOSE_COLLISION)

• meshes_dir (Path | None) – Directory to export mesh files to

• mesh_format (str) – “STL”, “OBJ”, or “GLB” (use FORMAT_STL, etc.)

• simplify (bool) – Whether to simplify mesh (for collision)

• decimation_ratio (float) – Simplification ratio if simplify=True

• dry_run (bool) – If True, generate mesh paths but don’t write files

• suffix (str) – Optional unique suffix (e.g., index or name)

• depsgraph (Any | None) – Optional dependency graph for evaluation

Return type:

tuple[Geometry | None, Matrix]

Returns:

tuple of (Core Geometry or None, geometry_world_matrix)

linkforge.blender.adapters.geometry_extractor.extract_mesh_triangles(obj, depsgraph=None, as_numpy=False)

Extract triangle mesh data from Blender object.

Parameters:

• obj (bpy.types.Object | None) – Blender mesh object

• depsgraph (Any | None) – Optional evaluated dependency graph

• as_numpy (bool) – If True, return NumPy arrays instead of Python lists

Returns:

• vertices: List of (x, y, z) coordinates or (N, 3) NumPy array

• triangles: List of (v0, v1, v2) vertex indices or (M, 3) NumPy array

Return type:

tuple[Any, Any] | None

linkforge.blender.adapters.geometry_extractor.get_object_material(obj, props)

Extract material from Blender object.

Parameters:

• obj (Any) – Blender Object

• props (Any) – LinkPropertyGroup with material settings

Return type:

Material | None

Returns:

Core Material or None

Mesh export utilities for LinkForge.

Export Blender mesh objects to STL, OBJ, and GLB files for URDF.

linkforge.blender.adapters.mesh_io.export_mesh_stl(obj, filepath)

Export a Blender object to an STL file.

This function utilizes the modern Blender WM STL exporter, ensuring correct axis orientations (Y-forward, Z-up) for ROS 2 compatibility.

Parameters:

• obj (Any) – The Blender mesh object to export.

• filepath (Path) – Target filesystem path for the STL file.

Return type:

bool

Returns:

True if the export completed successfully, False otherwise.

linkforge.blender.adapters.mesh_io.export_mesh_obj(obj, filepath)

Export a Blender object to an OBJ file with associated MTL materials.

This function ensures that materials are correctly exported alongside the geometry, maintaining visual fidelity in the target URDF.

Parameters:

• obj (Any) – The Blender mesh object to export.

• filepath (Path) – Target filesystem path for the OBJ file.

Return type:

bool

Returns:

True if the export completed successfully, False otherwise.

linkforge.blender.adapters.mesh_io.create_simplified_mesh(obj, decimation_ratio)

Create a simplified mesh copy using Blender’s Decimate modifier.

This function is primarily used to generate lightweight collision geometry from high-fidelity visual meshes, reducing physics computation overhead.

Parameters:

• obj (Any) – The source Blender mesh object.

• decimation_ratio (float) – The target triangle count ratio (0.0 to 1.0).

Return type:

Any | None

Returns:

A new Blender object with the simplified mesh, or None if failed.

linkforge.blender.adapters.mesh_io.get_mesh_filename(link_name, geometry_type, mesh_format, suffix='')

Generate mesh filename based on link and geometry type.

Parameters:

• link_name (str) – Name of the robot link

• geometry_type (str) – “visual” or “collision” (use PURPOSE_VISUAL, PURPOSE_COLLISION)

• mesh_format (str) – “STL”, “OBJ”, or “GLB” (use FORMAT_STL, etc.)

• suffix (str) – Optional unique suffix (e.g., index or name)

Return type:

str

Returns:

Filename string (e.g., “base_link_visual_0.stl”).

linkforge.blender.adapters.mesh_io.export_mesh_glb(obj, filepath)

Export Blender object to GLB (glTF Binary) file.

Parameters:

• obj (Any) – Blender Object to export

• filepath (Path) – Path where GLB file should be saved

Return type:

bool

Returns:

True if export succeeded, False otherwise

linkforge.blender.adapters.mesh_io.export_link_mesh(obj, link_name, geometry_type, mesh_format, meshes_dir, simplify=False, decimation_ratio=0.5, dry_run=False, suffix='', depsgraph=None)

Export mesh for a robot link.

CRITICAL: Exports mesh geometry centered at origin (0,0,0) with no transforms. The visual origin in URDF will handle all positioning. This prevents double-offset issues when the mesh is re-imported.

Parameters:

• obj (Any) – Blender Object to export

• link_name (str) – Name of the robot link

• geometry_type (str) – “visual” or “collision” (PURPOSE_VISUAL, PURPOSE_COLLISION)

• mesh_format (str) – “STL”, “OBJ”, or “GLB” (FORMAT_STL, etc.)

• meshes_dir (Path) – Directory where mesh files should be saved

• simplify (bool) – Whether to simplify mesh (for collision)

• decimation_ratio (float) – Simplification ratio if simplify=True

• dry_run (bool) – If True, return expected path without exporting

• suffix (str)

• depsgraph (Any | None)

Return type:

tuple[Path | None, Matrix]

Returns:

tuple of (Path to exported mesh file or None, geometric_offset)

Logic

Internal domain logic for asynchronous model building and collision synthesis.

Asynchronous Robot Builder for Blender.

This module provides an asynchronous task runner for importing robot models into Blender without blocking the UI. It uses bpy.app.timers to process the robot structure in chunks, allowing for a responsive UI and progress updates.

class linkforge.blender.logic.asynchronous_builder.AsynchronousRobotBuilder(robot, source_path, context, chunk_size=50)

Bases: object

Task runner for asynchronous robot import.

Parameters:

• robot (Robot)

• source_path (Path)

• context (IBlenderContext)

• chunk_size (int)

__init__(robot, source_path, context, chunk_size=50)

Parameters:

• robot (Robot)

• source_path (Path)

• context (IBlenderContext)

• chunk_size (int)

start()

Register the timer and start processing.

Return type:

None

process_next_chunk()

Process a chunk of tasks. Return interval or None to stop.

Return type:

float | None

finish()

Clean up and finalize.

Return type:

None

Procedural collision geometry and mesh generation logic for robot links.

This module provides functions for detecting, generating, and updating collision geometry (both primitives and compound decimated convex hulls) from visual meshes.

linkforge.blender.logic.collision_builder.regenerate_collision_mesh(link_obj, collision_type, context)

Helper to regenerate collision mesh for a link from its visuals.

Parameters:

• link_obj (Object) – The link object (Empty)

• collision_type (str) – Type of collision (“auto”, “box”, “sphere”, “cylinder”, “mesh”)

• context (Context) – Blender context

Return type:

None

linkforge.blender.logic.collision_builder.create_collision_for_link(link_obj, collision_type, context)

Create collision geometry for a link.

For links with multiple visual children, this creates a compound collision by merging all visuals into a single collision mesh (industry best practice).

Parameters:

• link_obj (bpy.types.Object) – The link object (Empty)

• collision_type (str) – Type of collision (“auto”, “box”, “sphere”, “cylinder”, “mesh”)

• context (Context) – Blender context

Return type:

bpy.types.Object | None

Returns:

The created collision object, or None if failed

Utilities

Blender-specific helpers.

Decorators for LinkForge Blender operators.

linkforge.blender.utils.decorators.safe_execute(func)

Decorator to wrap operator execute methods with robust error handling.

This ensures that unhandled exceptions are caught, logged with full tracebacks, and reported to the user as clean error messages instead of crashing Blender.

Example

>>> @safe_execute
>>> def execute(self, context):
>>>     ...

Parameters:

func (Callable[..., set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]])

Return type:

Callable[..., set[Literal['RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH', 'INTERFACE']]]

Kinematics utilities for the Blender platform.

linkforge.blender.utils.joint_utils.resolve_mimic_joints(joints, joint_objects)

Resolve mimic joint pointers after all joint objects have been created.

Parameters:

• joints (list[Joint]) – List of joint models

• joint_objects (dict[str, Object]) – Dictionary mapping joint names to Blender objects

Return type:

None

linkforge.blender.utils.joint_utils.is_control_joint_missing(item, scene)

Check if the physical joint object for a ros2_control joint is missing from the scene.

Parameters:

• item (bpy.types.PropertyGroup) – Ros2ControlJointProperty instance

• scene (bpy.types.Scene | None) – Active Blender scene

Returns:

True if the joint object no longer exists in the active scene.

Return type:

bool

linkforge.blender.utils.joint_utils.get_connected_joints_for_link(link_obj, scene=None)

Return incoming parent joint and outgoing child joints for a given link object.

Parameters:

• link_obj (bpy.types.Object | None) – The link object in Blender.

• scene (bpy.types.Scene | None) – Optional active scene. If not provided, uses bpy.context.scene.

Returns:

(parent_joint, list_of_child_joints)

Return type:

tuple[bpy.types.Object | None, list[bpy.types.Object]]

Utilities for managing Blender execution context and modes.

linkforge.blender.utils.mode_guard.context_and_mode_guard(context)

Context manager to ensure safe execution of Blender operators.

This handles two critical mission-critical scenarios:

1. Mode Switching: If the user is in Edit Mode, it switches to Object Mode and restores Edit Mode afterwards.

2. Context Overriding: If operators are called from non-UI contexts (timers, background threads), it provides a valid 3D View context.

Parameters:

context (Context)

Return type:

Iterator[dict[str, Any]]

Helper utilities for Blender property groups.

This module provides optimized helper functions for property update callbacks.

linkforge.blender.utils.property_helpers.find_property_owner(context, property_group, property_attr)

Find the Blender object that owns a given property group instance.

This is an optimized helper for property update callbacks that need to find their owning object. It tries multiple strategies from fastest to slowest: 1. Check id_data (most reliable and fastest) 2. Check context.object (active object) first 3. Check context.selected_objects 4. Fall back to full scene search as last resort

Parameters:

• context (Context) – Blender context

• property_group (Any) – The property group instance (self in update callback)

• property_attr (str) – The attribute name on objects (e.g., “linkforge_sensor”)

Return type:

Any | None

Returns:

The object that owns this property group, or None if not found

linkforge.blender.utils.property_helpers.get_link_props(obj)

Type-safe access to LinkForge link properties on a Blender object.

Parameters:

obj (bpy.types.Object | None)

Return type:

LinkPropertyGroup | None

linkforge.blender.utils.property_helpers.get_joint_props(obj)

Type-safe access to LinkForge joint properties on a Blender object.

Parameters:

obj (bpy.types.Object | None)

Return type:

JointPropertyGroup | None

linkforge.blender.utils.property_helpers.get_sensor_props(obj)

Type-safe access to LinkForge sensor properties on a Blender object.

Parameters:

obj (bpy.types.Object | None)

Return type:

SensorPropertyGroup | None

linkforge.blender.utils.property_helpers.get_robot_props(scene)

Type-safe access to LinkForge robot properties on a Blender scene.

Parameters:

scene (bpy.types.Scene | None)

Return type:

RobotPropertyGroup | None

linkforge.blender.utils.property_helpers.flush_deferred_renames()

Execute all pending datablock renames in the queue.

Used primarily in background mode or during tests to ensure synchronization is complete after depsgraph evaluation.

Return type:

None

linkforge.blender.utils.property_helpers.safe_set_id_name(id_data, sanitized_name)

Safely update a Blender datablock’s name, deferring if RNA is locked.

During property updates or depsgraph evaluation, writing directly to ID datablocks can raise RuntimeError or AttributeError. In GUI mode, updates are deferred via bpy.app.timers. In background mode (or headless environments where timers do not run), updates are queued into PENDING_RENAMES and flushed on depsgraph updates.

Note

Blender automatically handles duplicate object name collisions by appending numeric suffixes (e.g. ‘.001’, ‘.002’). The LinkForge model identity is preserved in source_name_stored.

Parameters:

• id_data (Any)

• sanitized_name (str)

Return type:

None

linkforge.blender.utils.property_helpers.should_rename_child(child_name, parent_old_name)

Check if a child object was auto-named by LinkForge and should be synced.

Only renames if the child follows the exact [parent_old_name]_visual or [parent_old_name]_collision convention. Custom names are preserved.

Parameters:

• child_name (str) – Current name of the child object.

• parent_old_name (str) – The previous name of the parent link before the current rename.

Return type:

bool

Returns:

True if the child is a standard LinkForge visual/collision object that should be renamed.

General Blender utility functions for object and collection management.

linkforge.blender.utils.scene_utils.is_robot_link(obj)

Check if blender obj is a robot_link.

Parameters:

obj (Any) – Blender object to be checked

Return type:

bool

Returns:

True if object has linkforge properties and is marked as robot_link

linkforge.blender.utils.scene_utils.is_robot_joint(obj)

Check if blender obj is a robot_joint.

Parameters:

obj (Any) – Blender object to be checked

Return type:

bool

Returns:

True if object is EMPTY with linkforge_joint properties marked as robot_joint

linkforge.blender.utils.scene_utils.is_robot_sensor(obj)

Check if blender obj is a robot_sensor.

Parameters:

obj (Any) – Blender object to check

Return type:

bool

Returns:

True if object is EMPTY with linkforge_sensor properties marked as robot_sensor

class linkforge.blender.utils.scene_utils.RobotSceneStatistics(num_links, total_mass, total_dof, link_objects, joint_objects, sensor_objects, root_link, joints_map=<factory>, geometry_stats=<factory>, manual_inertia_objects=<factory>)

Bases: object

Statistics/Properties about robot components within a scene.

Variables:

• num_links – Total number of robot_link objects in scene

• total_mass – Sum of all robot_link masses (kg)

• total_dof – Total degrees of freedom from all robot_joint objects in scene

• link_objects – Mapping of robot_link names to their corresponding blender objects

• joint_objects – List of all robot_joint objects in scene

• sensor_objects – List of all robot_sensor objects in scene

• root_link – Tuple of (link_name, object) for root link, or None if not found

Parameters:

• num_links (int)

• total_mass (float)

• total_dof (int)

• link_objects (dict[str, Any])

• joint_objects (list[Any])

• sensor_objects (list[Any])

• root_link (tuple[str, Any] | None)

• joints_map (dict[str, tuple[str, Any]])

• geometry_stats (dict[str, tuple[Any, str, bool]])

• manual_inertia_objects (list[Any])

num_links: int

total_mass: float

total_dof: int

link_objects: dict[str, Any]

joint_objects: list[Any]

sensor_objects: list[Any]

root_link: tuple[str, Any] | None

joints_map: dict[str, tuple[str, Any]]

geometry_stats: dict[str, tuple[Any, str, bool]]

manual_inertia_objects: list[Any]

__init__(num_links, total_mass, total_dof, link_objects, joint_objects, sensor_objects, root_link, joints_map=<factory>, geometry_stats=<factory>, manual_inertia_objects=<factory>)

Parameters:

• num_links (int)

• total_mass (float)

• total_dof (int)

• link_objects (dict[str, Any])

• joint_objects (list[Any])

• sensor_objects (list[Any])

• root_link (tuple[str, Any] | None)

• joints_map (dict[str, tuple[str, Any]])

• geometry_stats (dict[str, tuple[Any, str, bool]])

• manual_inertia_objects (list[Any])

linkforge.blender.utils.scene_utils.clear_stats_cache(_self=None, _context=None)

Clear the global scene statistics cache.

Parameters:

• _self (Any)

• _context (Any)

Return type:

None

linkforge.blender.utils.scene_utils.get_robot_statistics(scene, force_refresh=False)

Analyze scene and setup robot statistics/properties.

Categorizes all robot components (links, joints, sensors) and calculates total link mass and DOFs from all joints found. Uses frame-level caching to ensure the scene is scanned only once per frame.

Parameters:

• scene (Any) – Blender scene to be analyzed

• force_refresh (bool) – If True, ignore cache and perform a full scan.

Return type:

RobotSceneStatistics

Returns:

RobotSceneStatistics with all pre-calculated properties.

linkforge.blender.utils.scene_utils.build_tree_from_stats(stats)

Build kinematic tree from precomputed RobotSceneStatistics.

Returns: (tree, root_link_name, joints_dict, links_dict) - tree: parent -> list of (child_name, joint_name, joint_type) - root_link_name: name of root link or None - joints_dict: mapping (parent, child) -> joint object - links_dict: mapping link_name -> link object

Parameters:

stats (RobotSceneStatistics)

Return type:

tuple[dict[str, list[tuple[str, str, str]]], str | None, dict[tuple[str, str], Any], dict[str, Any]]

linkforge.blender.utils.scene_utils.move_to_collection(obj, collection)

Safely move an object to a specific collection.

This unlinks the object from all existing collections and links it to

the target collection.

Parameters:

• obj (bpy.types.Object | None) – Blender object to move

• collection (bpy.types.Collection | None) – Target Blender collection

Return type:

None

linkforge.blender.utils.scene_utils.sync_object_collections(target_obj, source_obj)

Synchronize a target object’s collection membership with a source object.

This ensures that secondary components (collisions, sensors, etc.) always stay in the same Outliner collections as their parent Link or Robot frame, preventing “leaks” to the scene root.

Parameters:

• target_obj (bpy.types.Object | None) – The object to be moved/linked.

• source_obj (bpy.types.Object | None) – The reference object whose collections should be matched.

Return type:

None

linkforge.blender.utils.scene_utils.calculate_robot_bounds(scene)

Calculate the 3D bounding box and diagonal size of all robot components in the scene.

Iterates through all detected robot links and their visual/collision mesh children to find the world-space bounding box extents.

Parameters:

scene (Any) – Blender Scene containing robot components.

Return type:

tuple[Vector, Vector, float] | None

Returns:

Tuple of (min_corner, max_corner, diagonal_length) or None if no components found.

linkforge.blender.utils.scene_utils.auto_fit_robot_gizmos(scene, context=None)

Auto-scale gizmos and display sizes according to robot bounding box dimensions.

Parameters:

• scene (Any) – The active Blender scene.

• context (Any) – Optional Blender context (uses bpy.context if omitted).

Return type:

tuple[float, float] | None

Returns:

Tuple of (recommended_size, diagonal) or None if no robot components found.

linkforge.blender.utils.scene_utils.compute_anchor_size(gizmo_size, show_gpu_axes=True)

Compute the native Blender empty display size.

When custom GPU visualization is enabled, keep the native empty wireframe compact (1-2 cm anchor) so it remains selectable without projecting large black crosshair lines across robot meshes.

Parameters:

• gizmo_size (float) – The user’s preferred gizmo/axis display size in meters.

• show_gpu_axes (bool) – Whether custom GPU RViz axes are currently active.

Return type:

float

Returns:

Compact anchor size in meters.

Utilities for managing object transforms and parenting.

linkforge.blender.utils.transform_utils.matrix_to_transform(matrix)

Convert a Blender 4x4 matrix to a Core Transform.

Parameters:

matrix (Any) – Blender mathutils.Matrix (4x4)

Return type:

Transform

Returns:

Core Transform with XYZ position and RPY rotation.

linkforge.blender.utils.transform_utils.set_parent_keep_transform(child_obj, parent_obj)

Set object parent while preserving its world transform (visual location/rotation).

This matches standard Blender ‘Object (Keep Transform)’ behavior by setting matrix_parent_inverse to the inverse of the parent’s world matrix.

Parameters:

• child_obj (Any) – The Blender object to be parented

• parent_obj (Any) – The Blender object to become the parent

Return type:

None

linkforge.blender.utils.transform_utils.clear_parent_keep_transform(child_obj)

Clear object parent while preserving its world transform.

Parameters:

child_obj (Any) – The Blender object to unparent

Return type:

None

linkforge.blender.utils.transform_utils.get_local_bounding_box_center(obj)

Calculate the geometric center of an object’s bounding box in local space.

Parameters:

obj (Any) – Blender object (must have bound_box attribute)

Return type:

Any

Returns:

mathutils.Vector representing the local center offset.

Handlers

Scene lifecycle and name synchronization handlers.

Handler for synchronizing LinkForge names with Blender object names.

This ensures that renaming an object in the Outliner or duplicating it automatically updates the corresponding LinkForge robot model identity.

linkforge.blender.handlers.name_sync_handler.flush_deferred_renames()

Execute all pending datablock renames in the queue.

Used primarily in background mode or during tests to ensure synchronization is complete after depsgraph evaluation.

Return type:

None

linkforge.blender.handlers.name_sync_handler.on_depsgraph_update_post(_scene, _depsgraph)

Synchronize LinkForge identities when objects are renamed in the Outliner.

This handler detects renames in the depsgraph and updates the corresponding LinkForge property groups. We only perform synchronization for robot components, avoiding overhead on standard Blender objects.

Parameters:

• _scene (Any)

• _depsgraph (Any)

Return type:

None

linkforge.blender.handlers.name_sync_handler.register()

Register name synchronization handlers.

Return type:

None

linkforge.blender.handlers.name_sync_handler.sync_object_identity(obj)

Synchronize a single object’s LinkForge identity with its datablock name.

Adheres to Blender depsgraph handler guidelines: 1. Unwraps evaluated proxy objects to their persistent original datablock (update.id.original). 2. Guards against ReferenceError when objects are being deleted. 3. Exits early if properties already match to prevent recursive update cycles. 4. Only operates on objects marked as LinkForge robot components.

Parameters:

obj (Any)

Return type:

None

linkforge.blender.handlers.name_sync_handler.sync_scene_identities(scene)

Synchronize all robot components in the scene with their datablock names.

Parameters:

scene (Any)

Return type:

None

linkforge.blender.handlers.name_sync_handler.unregister()

Unregister name sync handler.

Return type:

None

Visualization

3D Viewport gizmos for inertia tensors and joint kinematics.

3D gizmos for visualizing Center of Mass and Inertia Frames in the viewport.

This module provides high-visibility overlays for the Center of Mass (CoM) and Inertia Frame (Principal Axes) when manual inertia is configured.

Visualization Style: - Orange/White Axis System (Principal Axes of Inertia) - Yellow Wireframe Sphere (Center of Mass Marker, RViz/Gazebo style) - Semi-transparent line connecting CoM to link origin - Permanently visible for objects with manual inertia (when enabled in preferences)

linkforge.blender.visualization.inertia_gizmos.get_shader()

Get the appropriate builtin shader name for the current Blender version.

Return type:

GPUShader

linkforge.blender.visualization.inertia_gizmos.generate_inertia_axes_geometry(obj, axis_length=0.1)

Generate geometry data for Inertia Axes (Orange/White style).

Parameters:

• obj (Any) – Blender Object (Link)

• axis_length (float) – Length of axis in Blender units

Return type:

dict[str, list[Any]]

Returns:

Dictionary with line data for drawing

linkforge.blender.visualization.inertia_gizmos.draw_inertia_gizmos()

Draw Inertia frames and CoM spheres for all visible links with manual inertia.

Return type:

None

linkforge.blender.visualization.inertia_gizmos.tag_redraw()

Force redraw of all 3D views.

Return type:

None

linkforge.blender.visualization.inertia_gizmos.ensure_inertia_handler()

Ensure the inertia visualization draw handler is registered.

This should be called when Manual Inertia is enabled or when a file is loaded with Manual Inertia links. It is safe to call multiple times.

Return type:

None

linkforge.blender.visualization.inertia_gizmos.check_manual_inertia_on_load(_arg1=None, _arg2=None)

Check if any link has Manual Inertia on file load or registration.

Parameters:

• _arg1 (Any)

• _arg2 (Any)

Return type:

Any

linkforge.blender.visualization.inertia_gizmos.register()

Register inertia visualization components.

Return type:

None

linkforge.blender.visualization.inertia_gizmos.unregister()

Unregister inertia visualization components.

Return type:

None

3D gizmos for visualizing joint axes in the viewport.

This module provides RViz-style RGB axis visualization for robot joints: - Red = X axis (with arrow head) - Green = Y axis (with arrow head) - Blue = Z axis (with arrow head)

Each axis is drawn as a solid colored line with an arrow cone at the tip, matching the professional appearance of RViz.

linkforge.blender.visualization.joint_gizmos.get_shader()

Get the appropriate builtin shader name for the current Blender version.

Return type:

GPUShader

linkforge.blender.visualization.joint_gizmos.generate_arrow_cone_vertices(origin, direction, length, cone_ratio=0.2)

Generate vertices for an arrow cone at the tip of an axis.

Parameters:

• origin (Vector) – Start point of the arrow

• direction (Vector) – Direction vector (normalized)

• length (float) – Total length of axis

• cone_ratio (float) – Ratio of cone length to total length (default 0.2 = 20%)

Return type:

tuple[list[tuple[float, ...]], list[int]]

Returns:

Tuple of (positions, indices) for triangle drawing

linkforge.blender.visualization.joint_gizmos.generate_axis_geometry(obj, axis_length=0.2)

Generate geometry data for RGB axes with arrow heads (RViz style).

Parameters:

• obj (Object) – Blender Empty object with joint properties

• axis_length (float) – Length of axis in Blender units

Return type:

dict[str, Any]

Returns:

Dictionary with line and triangle data for drawing

linkforge.blender.visualization.joint_gizmos.draw_joint_axes()

Draw RGB axes for all joint objects in the scene.

Draws RViz-style arrows with colored shafts and arrow heads.

Return type:

None

linkforge.blender.visualization.joint_gizmos.fix_existing_joints(_dummy=None)

Fix display type for existing joints.

Parameters:

• dummy – Unused parameter (Blender handlers pass filepath string, we ignore it)

• _dummy (Any)

Return type:

None

linkforge.blender.visualization.joint_gizmos.fix_current_scene()

Timer callback to fix joints in the current scene after registration.

This runs once after the addon registers to fix any existing joints in the currently open scene. Returns None to prevent the timer from repeating.

Return type:

float | None

linkforge.blender.visualization.joint_gizmos.register()

Register the joint axes visualization components.

Return type:

None

linkforge.blender.visualization.joint_gizmos.unregister()

Unregister the joint axes visualization components.

Return type:

None

linkforge.blender.visualization.joint_gizmos.update_viz_handle(context)

Enable or disable the draw handler based on user preferences.

This is called by the preference update function.

Parameters:

context (Context)

Return type:

None

Context

class linkforge.blender.adapters.context.IBlenderContext(*args, **kwargs)

Bases: Protocol

Protocol defining the necessary Blender environment access.

property scene: Any

Active Blender scene.

property data: Any

Access to bpy.data.

property ops: Any

Access to bpy.ops.

property view_layer: Any

Active Blender view layer.

property active_object: Any | None

Currently active Blender object.

property preferences: Any

Blender user preferences.

property window_manager: Any

Blender window manager.

get_objects()

Retrieve all objects relevant for the current context.

Return type:

Iterable[Any]

get_active_object()

Retrieve the currently active object.

Return type:

Any | None

__init__(*args, **kwargs)

Usage in Blender

Accessing from Blender Python Console

import bpy
from linkforge.blender.adapters.blender_to_core import scene_to_robot

# Convert current scene to robot model
robot = scene_to_robot(bpy.context)

# Access robot data
print(f"Robot: {robot.name}")
for link in robot.links:
    print(f"  Link: {link.name}")

Creating Custom Operators

import bpy
from linkforge.blender.utils.decorators import safe_execute

class LINKFORGE_OT_my_custom_op(bpy.types.Operator):
    bl_idname = "linkforge.my_custom_op"
    bl_label = "My Custom Operation"

    @safe_execute
    def execute(self, context):
        # Your code here
        self.report({'INFO'}, "Operation complete!")
        return {'FINISHED'}