Object Follow (No-PTZ)

Function package: microros_v2_kcf_follow_pkg

1. Function Description

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

Therefore, the complete functionality consists of two parts:

1. The tracker is responsible for obtaining the target bounding box from the image, for example smart_tracker/super_tracker or the KCF tracking node.
2. tracking_bbox_follow_node computes the PTZ angle, body angular velocity, and body linear velocity from the target box center and target box size.

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

2. Control Chain

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

PTZ Version

By default enable_ptz_follow:=true:

• Uses independent X/Y PD control to update the PTZ angle from the pixel error of the target center relative to the image center.
• After the PTZ horizontal angle deviates from the initial angle by servo1_engage_deg, body PD control is used for angular.z, letting the body gradually follow the PTZ back to center.
• At the same time, linear.x can be controlled based on the target box size.

No-PTZ Version

A fixed camera cannot adjust its line of sight through the PTZ; the following must be set at startup:

xxxxxxxxxx
enable_ptz_follow:=false publish_initial_ptz_command:=false

In this case, the node uses the horizontal pixel error of the target center 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 following logic, so it cannot be the only modification for a No-PTZ configuration.

3. Topics and Messages

The node is also compatible with:

• smart_tracker/msg/TrackBox, auto-detected 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 corner (x1, y1) and the bottom-right corner (x2, y2). The node automatically 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 has been 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 the program smart_tracker/super_tracker, Terminal 2:

xxxxxxxxxx
ros2 launch microros_v2_bringup super_tracker.launch.py display_windows_only_track:=false display_windows:=true

Press c to enter box-selection mode, then use the mouse to draw a box

Then press Enter to start following the coordinate data.

4.4 Start the Follow Controller

Terminal 3:

xxxxxxxxxx
ros2 launch microros_v2_kcf_follow_pkg tracking_bbox_follow.launch.py \
  enable_ptz_follow:=false \
  publish_initial_ptz_command:=false

After a successful startup, slowly move the object to test left/right tracking and forward/backward following.

5. Distance Following Algorithm

The node does not estimate distance from the color radius, but instead uses the geometric size of the bounding box:

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

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

The distance control uses the PID form; with the default distance_ki:=0.0, it is effectively 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 reference, size_error > 0, and it moves forward to approach by default;
• When the target box is larger than the reference, size_error < 0, and it moves backward to retreat by default;
• When abs(size_error) <= distance_tolerance_ratio, it stops moving forward/backward;
• linear.x is clamped to [-max_linear_x, max_linear_x], with a default maximum absolute value of 0.12 m/s.

6. Key Parameters

General Parameters

PTZ and Body Turning Parameters

Distance Following Parameters