# mouse_teleop

*This file is ai generated. Do not edit this file directly. Instead, edit the node source code and run the generate-node-docs command to update this file.*

## Description

The `mouse_teleop` node provides a graphical mouse-based teleoperation interface for controlling robot velocity. It opens a Tkinter window where users can click and drag with the mouse to generate velocity commands. The node supports both holonomic (omnidirectional) and non-holonomic (differential drive) robots.

## Publishers

| Topic | Type | Description |
|-------|------|-------------|
| `mouse_vel` | `geometry_msgs/msg/TwistStamped` | Publishes velocity commands based on mouse position relative to click point |

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `frequency` | double | 0.0 | Publishing frequency in Hz. If 0.0, publishes only on mouse movement; if > 0.0, publishes periodically while mouse button is held |
| `scale` | double | 1.0 | Scaling factor applied to all velocity commands |
| `holonomic` | bool | false | If true, enables holonomic mode (x, y linear and z angular control); if false, only x linear and z angular control |

## Example Usage

### Basic Launch

```bash
ros2 run mouse_teleop mouse_teleop
```

### Launch with Parameters

```bash
ros2 run mouse_teleop mouse_teleop --ros-args \
  -p frequency:=10.0 \
  -p scale:=2.0 \
  -p holonomic:=true
```

### Launch with Configuration File

```bash
ros2 run mouse_teleop mouse_teleop --ros-args --params-file /path/to/config.yaml
```

### Example Configuration File

```yaml
mouse_teleop:
  ros__parameters:
    frequency: 10.0
    scale: 1.5
    holonomic: false
```

### Example Launch File

```python
from launch import LaunchDescription
from launch_ros.actions import Node
from ament_index_python.packages import get_package_share_directory
import os

def generate_launch_description():
    config_file = os.path.join(
        get_package_share_directory('mouse_teleop'),
        'config', 'mouse_teleop.yaml'
    )
    
    return LaunchDescription([
        Node(
            package='mouse_teleop',
            executable='mouse_teleop',
            parameters=[config_file],
            output='screen'
        )
    ])
```

### Remap Output Topic

```bash
ros2 run mouse_teleop mouse_teleop --ros-args -r mouse_vel:=cmd_vel
```

## Operation

### Non-Holonomic Mode (default)

- **Click and drag up/down**: Control linear velocity (forward/backward)
- **Click and drag left/right**: Control angular velocity (rotation)
- The farther you drag from the click point, the higher the velocity magnitude
- Release the mouse button to stop

### Holonomic Mode

- **Click and drag**: Control x and y linear velocities
- **Hold Shift + drag**: Control x linear and z angular velocities
- **Shift key**: Switches between linear and angular control modes
- Release the mouse button to stop

### Window Controls

- **Ctrl+C**: Close the window (in window or terminal)
- **q**: Not applicable (for keyboard teleop)

The GUI window displays:
- Real-time visualization of velocity vectors
- Current velocity values (linear and angular)
- Visual feedback using colored lines and arcs

## Notes

- The node uses a Tkinter GUI, so a graphical display is required
- Mouse velocity is normalized to the window size (ranges from -1.0 to 1.0)
- All published velocities are scaled by the `scale` parameter
- The frame_id in the published TwistStamped messages is set to "mouse_teleop"
- When `frequency` > 0, velocity commands continue to be published at the specified rate while the mouse button is held
- When `frequency` = 0, velocity commands are only published when the mouse moves