# turtlebot3_relative_move

*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

An interactive node that moves the TurtleBot3 relative to its current position and orientation. Users can specify movement distances and rotation angles relative to the robot's current pose. The node executes movements in three phases: rotate toward target, move forward, and rotate to final heading.

## Publishers

- `cmd_vel` ([geometry_msgs/Twist](http://docs.ros.org/api/geometry_msgs/html/msg/Twist.html) or [geometry_msgs/TwistStamped](http://docs.ros.org/api/geometry_msgs/html/msg/TwistStamped.html))
  - Velocity commands for relative movement
  - Message type depends on ROS_DISTRO environment variable

## Subscribers

- `odom` ([nav_msgs/Odometry](http://docs.ros.org/api/nav_msgs/html/msg/Odometry.html))
  - Current robot pose for relative movement calculations

## Parameters

The node uses hardcoded control parameters:

- Linear velocity: 0.1 m/s
- Angular velocity: 0.3 rad/s
- Position threshold: 0.01 meters
- Angle threshold: 0.01 radians (~0.57 degrees)
- Control rate: 100 Hz (0.010 second timer period)

## Example Usage

Launch the relative move node:

```bash
ros2 run turtlebot3_example turtlebot3_relative_move
```

Input example:

```
Input x: 1.0
Input y: 0.5
Input theta (deg): 45
```

The robot will:
1. Rotate to face the direction of (1.0, 0.5) relative to current pose
2. Drive approximately 1.12 meters to reach the relative position
3. Rotate 45 degrees from its original orientation
4. Prompt for the next movement

## Behavior

### Three-Phase Movement Strategy

1. **Phase 1 - Rotate to Path Angle**:
   - Calculates the angle to the target position relative to current pose
   - Rotates in place until facing the target direction
   - Uses fixed angular velocity of 0.3 rad/s

2. **Phase 2 - Move to Position**:
   - Moves straight forward to the target position
   - Uses fixed linear velocity of 0.1 m/s
   - Stops when within 0.01 m of target

3. **Phase 3 - Rotate to Final Heading**:
   - Rotates to achieve the final desired heading
   - Heading is relative to the robot's initial orientation
   - Uses fixed angular velocity of 0.3 rad/s

4. **Phase 4 - Ready for Next Command**:
   - Returns to Phase 1 and waits for new user input

## Input Format

- **x**: Forward/backward distance in meters (relative to current pose)
  - Positive = forward in robot's current frame
  - Negative = backward in robot's current frame
  
- **y**: Left/right distance in meters (relative to current pose)
  - Positive = left in robot's current frame
  - Negative = right in robot's current frame
  
- **theta**: Rotation angle in degrees (-180 to 180)
  - Relative to robot's current orientation
  - Positive = counterclockwise
  - Negative = clockwise

## Coordinate Transformation

The node transforms relative coordinates from the robot frame to the global odometry frame:

```
x_global = cos(current_heading) * x_input - sin(current_heading) * y_input
y_global = sin(current_heading) * x_input + cos(current_heading) * y_input
heading_global = current_heading + theta_input
```

## Example Movements

Move 1 meter forward:
```
x: 1.0, y: 0.0, theta: 0
```

Move 0.5 meters to the left:
```
x: 0.0, y: 0.5, theta: 0
```

Move diagonally and rotate:
```
x: 1.0, y: 0.5, theta: 45
```

Rotate 90° in place:
```
x: 0.0, y: 0.0, theta: 90
```

## Notes

- Movements are relative to the robot's pose at the time of command input
- Does not perform obstacle avoidance
- Requires accurate odometry for precise movements
- Input validation ensures theta is within -180° to 180° range
- Sequential movements can be chained by providing new inputs after completion