Add geometry-based robot class generator (#642)

* Add geometry-based robot class generator without LLM

Add robot_class_generator.py that generates Python robot classes
from URDF geometry without requiring LLM or API keys.

Key features:
- Automatic kinematic chain detection using NetworkX graph analysis
- Geometry-based limb type detection (arm, leg, head, torso)
- TCP estimation from gripper fingertip midpoint or mesh extent
- Tool frame and hand link detection from link structure
- Support for single-arm and dual-arm robots

* Add generate-robot-class to skr CLI

Move robot class generator from examples to skr CLI command.
Update README.md and docs/source/cli.rst with usage documentation.

* Support ROS package:// path in generate_robot_class

Automatically detect if URDF is inside a ROS package and generate
default_urdf_path with package:// format instead of absolute path.

* Support package:// URLs in URDF.load

Resolve package:// URLs using resolve_filepath before loading URDF.
This allows generated robot classes with package:// default_urdf_path
to work correctly when loaded from within a ROS package directory.

* Improve gripper detection with geometric symmetry

- Remove 'gripper_link' from tool_frame patterns (was too broad)
- Add _find_symmetric_gripper_midpoint() for geometry-based detection
- Detect gripper fingers by finding symmetric child links (same parent,
  opposite x/y coordinates) instead of relying on naming patterns
- Support package:// URLs in URDF.load

* Use mesh-based fingertip positions for gripper midpoint

- Calculate gripper midpoint using _get_fingertip_position() instead
  of link.worldpos() for more accurate TCP estimation
- Skip _calculate_gripper_tcp_offset if offset already set by
  symmetric gripper detection to avoid overwriting correct values

* Use link origins for symmetric gripper midpoint

Mesh-based fingertip detection doesn't work well for grippers with
opposing fingers (different directions). Use link origin midpoint
instead for symmetric gripper pairs.

* Fix package:// path double conversion

Skip _convert_to_ros_package_path if input is already a package:// URL
to avoid corrupting the path.

* Add gripper orientation calculation to robot class generator

Calculate end_coords orientation for symmetric gripper links so that:
- x-axis points in gripper forward direction (from parent to midpoint)
- y-axis points in gripper opening direction (between fingers)
- z-axis is computed as x cross y

The rotation is output as RPY angles in radians in the generated
CascadedCoords initialization.

* Externalize patterns and improve robot class generator

Based on feedback, this commit makes the following improvements:

1. Add PatternConfig class for externalizing all "magic words"
   - Users can customize patterns for non-standard naming conventions
   - Patterns can be extended or overridden via constructor
   - force_groups option to bypass auto-detection for specific groups

2. Use pre-compiled regex for pattern matching
   - Improves performance by compiling patterns once
   - All pattern matching now uses PatternConfig.matches()

3. Switch mesh priority for TCP estimation
   - Visual mesh now preferred over collision mesh
   - Visual meshes have more accurate vertex positions for fingertips
   - Collision meshes may be simplified convex hulls

4. Add documentation about geometric detection limitations
   - Y-coordinate based left/right detection assumes T-pose
   - Notes added to docstrings about potential failure cases

Example usage:
    config = PatternConfig(
        patterns={'right_arm': ['RA_', 'right_arm_j']},
        force_groups={'head': ['neck_link', 'head_link']}
    )
    generate_robot_class_from_geometry(robot, config=config)

* Fix non-deterministic Y-axis direction in gripper orientation

The Y-axis direction was dependent on the iteration order of child
links, which is non-deterministic. This caused the gripper orientation
to be inconsistent between runs.

Fix: Ensure Y-axis always points toward the positive direction of the
axis with the largest absolute component. This makes the orientation
calculation deterministic regardless of iteration order.

* Fix gripper orientation when finger origins are at parent origin

When finger link origins are located at the parent origin (like Fetch),
use fingertip mesh positions to determine the approach direction instead
of falling back to an arbitrary axis.

This fixes incorrect gripper orientations for robots like Fetch where
the finger links' origins are at [0, ±y, 0] relative to gripper_link,
resulting in a midpoint at the origin.

* Delete generate-robot-class command

* Extract magic numbers as named constants for better maintainability

- Add module-level constants for geometric detection thresholds
- Remove unused center calculation in _estimate_tcp_from_mesh
- Replace hardcoded values with descriptive constants:
  - SYMMETRY_POSITION_TOLERANCE, MIN_POSITION_OFFSET, Z_SIMILARITY_TOLERANCE
  - MAX_SEARCH_DEPTH, POSITION_EPSILON, FINGERTIP_RATIO, ASYMMETRY_RATIO
  - Y_THRESHOLD_WEAK, Y_THRESHOLD_STRONG, MIN_ARM_JOINTS

Author: iory

README.md

@@ -67,6 +67,9 @@ skr visualize-mesh mesh_file.stl
 
 # Convert wheel collision models
 skr convert-wheel-collision robot.urdf --output converted.urdf
+
+# Generate robot class from URDF geometry
+skr generate-robot-class robot.urdf --output MyRobot.py
 ```
 
 ### Legacy Commands (still supported)

docs/source/cli.rst

@@ -109,6 +109,29 @@ Convert wheel collision models in URDF files.
 
    skr convert-wheel-collision robot.urdf --output converted.urdf
 
+generate-robot-class
+~~~~~~~~~~~~~~~~~~~~
+
+Generate Python robot class from URDF geometry. This tool automatically detects
+kinematic chains (arms, legs, head, torso) and generates a Python class with
+appropriate properties and end-effector coordinates.
+
+No LLM or API keys required - uses only URDF structure and geometry.
+
+.. code-block:: bash
+
+   # Generate robot class and print to stdout
+   skr generate-robot-class robot.urdf
+
+   # Save to file
+   skr generate-robot-class robot.urdf --output MyRobot.py
+
+   # Specify custom class name
+   skr generate-robot-class robot.urdf --class-name MyCustomRobot --output MyRobot.py
+
+   # Show detected groups without generating code
+   skr generate-robot-class robot.urdf --show-groups
+
 Backward Compatibility
 ----------------------
 
@@ -124,6 +147,7 @@ For backward compatibility, all original individual commands are still available
    urdf-hash robot.urdf
    visualize-mesh mesh_file.stl
    convert-wheel-collision robot.urdf --output converted.urdf
+   generate-robot-class robot.urdf --output MyRobot.py
 
 Getting Help
 ------------

skrobot/apps/cli.py

@@ -22,6 +22,7 @@ def get_available_apps():
         'urdf_hash': ('Calculate URDF hash', None),
         'convert_wheel_collision': ('Convert wheel collision model', None),
         'extract_sub_urdf': ('Extract sub-URDF from a root link', None),
+        'generate_robot_class': ('Generate robot class from URDF geometry', None),
     }
 
     for filename in os.listdir(apps_dir):

skrobot/apps/generate_robot_class.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python
+
+"""Generate robot class from URDF geometry.
+
+This tool generates Python robot class code with kinematic chain properties
+(arm, right_arm, left_arm, etc.) from any URDF robot model.
+
+No LLM or API keys required - uses only URDF structure and geometry.
+"""
+
+import argparse
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Generate robot class from URDF geometry')
+    parser.add_argument(
+        'input_urdfpath',
+        type=str,
+        help='Input URDF path')
+    parser.add_argument(
+        '--output', '-o',
+        type=str,
+        default=None,
+        help='Output path for generated Python file')
+    parser.add_argument(
+        '--class-name', '-c',
+        type=str,
+        default=None,
+        help='Class name for the generated class (default: auto-generated)')
+    parser.add_argument(
+        '--show-groups',
+        action='store_true',
+        help='Show detected groups without generating code')
+    args = parser.parse_args()
+
+    from skrobot.models.urdf import RobotModelFromURDF
+    from skrobot.urdf.robot_class_generator import generate_groups_from_geometry
+    from skrobot.urdf.robot_class_generator import generate_robot_class_from_geometry
+
+    robot = RobotModelFromURDF(urdf_file=args.input_urdfpath)
+
+    print(f"Robot: {robot.name}")
+    print(f"Links: {len(robot.link_list)}")
+    print(f"Joints: {len(robot.joint_list)}")
+    print()
+
+    if args.show_groups:
+        groups, end_effectors, end_coords_info, robot_name = \
+            generate_groups_from_geometry(robot)
+        print("Detected groups:")
+        for group_name, group_data in groups.items():
+            links = group_data.get('links', [])
+            tip = group_data.get('tip_link', 'N/A')
+            print(f"  {group_name}: {len(links)} links, tip={tip}")
+        print()
+        print("End coordinates:")
+        for group_name, ec_info in end_coords_info.items():
+            parent = ec_info.get('parent_link', 'N/A')
+            pos = ec_info.get('pos', [0, 0, 0])
+            print(f"  {group_name}: parent={parent}, pos={pos}")
+        return
+
+    code = generate_robot_class_from_geometry(
+        robot,
+        output_path=args.output,
+        class_name=args.class_name,
+        urdf_path=args.input_urdfpath,
+    )
+
+    if args.output:
+        print(f"Generated class saved to: {args.output}")
+    else:
+        print("Generated code:")
+        print("-" * 60)
+        print(code)
+
+
+if __name__ == '__main__':
+    main()

skrobot/urdf/__init__.py

@@ -3,6 +3,8 @@
 from skrobot.urdf.modularize_urdf import find_root_link
 from skrobot.urdf.modularize_urdf import transform_urdf_to_macro
 from skrobot.urdf.primitives_converter import convert_meshes_to_primitives
+from skrobot.urdf.robot_class_generator import generate_groups_from_geometry
+from skrobot.urdf.robot_class_generator import generate_robot_class_from_geometry
 from skrobot.urdf.scale_urdf import scale_urdf
 from skrobot.urdf.transform_urdf import transform_urdf_with_world_link
 from skrobot.urdf.wheel_collision_converter import convert_wheel_collisions_to_cylinders
@@ -23,4 +25,6 @@
     'get_mesh_dimensions',
     'extract_sub_urdf',
     'scale_urdf',
+    'generate_groups_from_geometry',
+    'generate_robot_class_from_geometry',
 ]