Lula Description Generator

lula_generate_robot_description(
    urdf_path,               # absolute path to URDF
    output_path=None,        # defaults to <urdf_dir>/<name>_lula_description.yaml
    mesh_search_paths=None,  # extra dirs for mesh resolution (incl. package:// URIs)
    controlled_joint_names=None,  # explicit cspace list; auto-detected if omitted
    max_spheres_per_link=16, # 8–32 is typical; more = tighter fit but slower planning
    voxel_fraction=0.04,     # 4% of max bounding-box dim; lower = finer but slower
    skip_sphere_links=None,  # links to exclude from sphere generation (virtual frames)
)

Returns: success, output_path, cspace, num_links_with_spheres, total_spheres, warnings, summary.

Standard workflow

Phase 1 — Inspect the URDF

Use urdf_inspect to understand the robot structure before generating:

• How many links and joints?
• Which joints are controllable (revolute/prismatic/continuous)?
• Are there gripper/finger joints separate from the arm?
• Are mesh paths resolvable (package:// URIs need search paths)?

Phase 2 — Decide the c-space

For manipulator arms, the c-space is typically the arm joints only (NOT gripper fingers). Gripper joints should appear in cspace_to_urdf_rules as fixed entries.

Example: UR5e — c-space is 6 revolute joints:

controlled_joint_names=["shoulder_pan_joint", "shoulder_lift_joint",
                        "elbow_joint", "wrist_1_joint",
                        "wrist_2_joint", "wrist_3_joint"]

Example: Piper — 6-DOF arm (joint1–joint6); gripper joints (joint7, joint8) go in cspace_to_urdf_rules:

controlled_joint_names=["joint1", "joint2", "joint3", "joint4", "joint5", "joint6"]

When controlled_joint_names is omitted, ALL non-fixed joints are included.

Phase 3 — Resolve mesh paths

If the URDF uses package:// URIs, provide mesh_search_paths pointing to the directory that contains the package folder. For example:

URDF: package://piper_description/meshes/base_link.STL