Color Follow (No-PTZ)

1. Experiment Objective

The camera detects a target of a specified color, and the car body uses PD control for rotation tracking + distance following to keep the target centered in the frame and maintain a constant distance.

2. Experiment Principle

1. Key Terms

Difference Between Tracking and Following: Tracking only controls the body rotation to keep the target at the center of the frame (angular.z); following adds distance control (linear.x) on top of that, keeping the car at the desired distance from the target.

2. Technical Architecture

Shares the same node color_tracker_node as Color Tracking; distance following is enabled with enable_distance_follow:=true:

/camera/image_raw (BEST_EFFORT)
  → color_tracker_node (enable_distance_follow:=true)
    ├── Image processing: HSV binarization → largest contour → centroid + color block radius
    └── Body control timer (10 Hz):
        ├── Pixel error → PD angular velocity → angular.z
        └── Color block radius error → PD linear velocity → linear.x → /cmd_vel (BEST_EFFORT)

3. Core Topics Quick Reference

Firmware Downlink

3. Experiment Steps

1. Hardware Preparation

2. Start Agent + Camera + Joint Model (Terminal 1)

xxxxxxxxxx
ros2 launch microros_v2_bringup car_base.launch.py

3. Start Color Follow (Terminal 2)

xxxxxxxxxx
ros2 launch microros_v2_no_ptz_visual_control_pkg color_follow.launch.py

Follow mode is equivalent to color_tracker.launch.py enable_distance_follow:=true.

5. Operation Instructions

Distance Follow Behavior: The target approaches (color block radius increases) → move backward; the target moves away (radius decreases) → move forward; radius within tolerance → stay still.

4. Experiment Result

• Target approaches → the car automatically moves backward to keep the distance
• Target moves away → the car automatically moves forward to follow
• Distance within the desired range → the car stays still
• Target lost → the car automatically stops once the lost-target count exceeds the threshold

5. Code Explanation

Source code paths:

• Launch: ~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/launch/color_follow.launch.py
• Node source: ~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/microros_v2_no_ptz_visual_control_pkg/color_tracker_node.py

1. Core Node Explanation

color_follow.launch.py launches color_tracker_node (the same node shared with Color Tracking); the only difference is that enable_distance_follow defaults to true.

Distance Follow PD Logic (in the body control timer):

​x
# Source file: ~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/microros_v2_no_ptz_visual_control_pkg/color_tracker_node.py
​
# Distance follow: color block radius error → PD linear velocity
if self._dist_follow and tr is not None:
    err_r = self._target_r_px - tr           # desired radius - actual radius
    if abs(err_r) > self._dist_tol_r:        # deadband check
        now = time.perf_counter()
        dt = now - self._prev_dt if self._prev_dt > 0 else 1.0 / self._body_rate
        dt = max(dt, 1e-3)
        d_err_r = (err_r - self._prev_derr) / dt
        self._prev_derr = err_r; self._prev_dt = now
        lx = self._dist_kp * err_r + self._dist_kd * d_err_r
        lx = clamp(lx, -self._max_lx, self._max_lx)
        cmd.linear.x = lx

Key Logic:

• err_r > 0 (actual radius < desired = target far) → positive linear.x → move forward to approach
• err_r < 0 (actual radius > desired = target close) → negative linear.x → move backward to retreat
• Radius error within distance_tolerance_r (12 px) → no adjustment (deadband)

2. Key Parameters

Parameter definition files:

• Launch: ~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/launch/color_follow.launch.py
• Node: ~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/microros_v2_no_ptz_visual_control_pkg/color_tracker_node.py

3. Node Description

6. Common Issues