Object Follow

Package: microros_v2_kcf_follow_pkg

1. Feature Description

microros_v2_kcf_follow_pkg is a follow controller based on the target bounding box. It only subscribes to the target box published by a tracking node, and then controls the pan-tilt and/or the body motion.

Therefore, the complete functionality consists of two parts:

1. A tracker obtains the target bounding box from the image, e.g. smart_tracker/super_tracker or the KCF tracking node.
2. tracking_bbox_follow_node computes the pan-tilt angle, the body angular velocity, and the body linear velocity from the target box center and the target box size.

The default control rate is 10 Hz. When the target box is invalid, its confidence is too low, or it has not been updated for longer than target_stale_timeout_sec, the node immediately publishes zero velocity; the source code has no "allow 5 more frames of movement" lost-target tolerance logic.

2. Control Chain

Camera / vision tracker
    └── /tracking_bbox
          └── tracking_bbox_follow_node (10 Hz)
                ├── PTZ follow: target center -> /cmd_ptz_angle
                ├── Body turning: target horizontal error or pan-tilt angle -> /cmd_vel.angular.z
                └── Distance follow: target box size error -> /cmd_vel.linear.x

PTZ Version

enable_ptz_follow:=true by default:

• Based on the pixel error of the target center relative to the image center, independent X/Y PD control updates the pan-tilt angles.
• Once the pan-tilt horizontal angle deviates from the initial angle by servo1_engage_deg, the body PD control drives angular.z, letting the body gradually follow the pan-tilt back to center.
• linear.x can be controlled simultaneously based on the target box size.

No-PTZ Version

A fixed camera cannot adjust its line of sight through the pan-tilt, so at startup you must set:

xxxxxxxxxx
enable_ptz_follow:=false publish_initial_ptz_command:=false

In this mode the node uses the target center's horizontal pixel error to control the body angular.z, and controls linear.x based on the target box size. Setting only publish_initial_ptz_command:=false does not disable the PTZ follow logic, so it cannot be the only change for a No-PTZ configuration.

3. Topics and Messages

The node is also compatible with:

• smart_tracker/msg/TrackBox, auto-discovered via tracking_bbox_msg_type:=auto;
• std_msgs/msg/Int32MultiArray: when the length is at least 11, it is parsed as [valid, x1, y1, x2, y2, cx, cy, width, height, image_width, image_height]; when the length is 4 to 10, the first four elements are taken as the bounding box;
• messages with x1, y1, x2, y2 fields.

The bounding box format is uniformly the top-left (x1, y1) and bottom-right (x2, y2). The node auto-sorts the coordinates and checks the width, height, and confidence.

4. Startup Steps

The following commands assume the workspace is ~/microros_car_v2_ws and the ROS 2 environment is already configured.

4.1 Start the Chassis, Agent, Camera, and Model

Terminal 1:

xxxxxxxxxx
ros2 launch microros_v2_bringup car_base.launch.py

4.2 Start the Target Tracker

Run smart_tracker/super_tracker, Terminal 2:

xxxxxxxxxx
ros2 launch microros_v2_bringup super_tracker.launch.py

Press c to enter the box-selection mode, then select with the mouse:

Then press Enter to start following the coordinate data:

4.3 Start the Follow Controller

Terminal 3:

xxxxxxxxxx
ros2 launch microros_v2_kcf_follow_pkg tracking_bbox_follow.launch.py 

After a successful startup, slowly move the object for left/right tracking and forward/back following:

5. Distance-follow Algorithm

The node does not use the color radius to estimate distance; instead it uses the geometric size of the bounding box:

xxxxxxxxxx
current_size = sqrt(width * height)
size_error = (target_size - current_size) / target_size

auto_set_target_bbox_size:=true by default. The first valid bounding box received after startup is used as the target distance baseline. You can also specify target_bbox_size_px manually, in which case the node no longer waits for the first bounding box to initialize the baseline.

Distance control uses the PID form, with distance_ki:=0.0 by default, so it is actually PD:

xxxxxxxxxx
linear.x = linear_dir * (distance_kp * size_error
                       + distance_ki * integral
                       + distance_kd * d_error)

• When the target box is smaller than the baseline, size_error > 0, the default is to move forward and approach;
• When the target box is larger than the baseline, size_error < 0, the default is to move backward and move away;
• When abs(size_error) <= distance_tolerance_ratio, forward/back movement stops;
• linear.x is limited to [-max_linear_x, max_linear_x], with the default maximum absolute value being 0.12 m/s.

6. Key Parameters

Common Parameters

Pan-Tilt and Body Turning Parameters

Distance-follow Parameters