AprilTag Machine Code Follow (No-PTZ)

1. Experiment Objective

The camera tracks an AprilTag marker, with body rotation tracking + distance following keeping the Tag centered in the frame and maintaining a constant distance. Distance following is based on the 3D pose Z value (actual depth), which is more accurate than pixel-size estimation.

2. Experiment Principle

1. Key Terms

2. Technical Architecture

The distinctive feature of AprilTag following is that it uses the 3D pose Z value rather than pixel size for distance estimation, which is more accurate:

/camera/image_raw (BEST_EFFORT)
  → april_tag_tracker_node (enable_distance_follow:=true)
    ├── apriltag.Detector.detect() → 4 corner points + 3D pose (pose_z)
    └── Body control (10 Hz):
        ├── Pixel error → PD angular velocity
        └── pose_z error → PD linear velocity → /cmd_vel

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 AprilTag Follow (Terminal 2)

xxxxxxxxxx
ros2 launch microros_v2_no_ptz_visual_control_pkg april_tag_follow.launch.py

5. Operation Instructions

Distance Follow Behavior: Tag approaches (pose_z decreases) → move backward; Tag moves away (pose_z increases) → move forward; depth within tolerance (±0.02 m) → stay still.

4. Experiment Result

• Tag approaches → the car moves backward to keep the distance (based on the 3D depth Z value)
• Tag moves away → the car moves forward to follow
• Tag distance within the desired range (0.25 m) → the car stays still
• The terminal outputs the Tag 3D pose (x, y, z, roll, pitch, yaw) in real time
• Tag 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/april_tag_follow.launch.py
• Node source: ~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/microros_v2_no_ptz_visual_control_pkg/april_tag_tracker_node.py

1. Core Node Explanation

april_tag_follow.launch.py launches april_tag_tracker_node, with enable_distance_follow defaulting to true. Unlike other follow modes, AprilTag distance following directly uses the 3D pose Z value:

​x
# Source file: ~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/microros_v2_no_ptz_visual_control_pkg/april_tag_tracker_node.py
​
# Distance follow: based on the 3D depth Z value (not pixel size)
if self._dist_follow and tz is not None and tz > 0:
    err_z = self._target_z_m - tz  # target_z unit: meters
    if abs(err_z) > self._dist_tol_z:
        lx = self._dist_kp * err_z
        lx = clamp(lx, -self._max_lx, self._max_lx)
        if self._reverse_linear:
            lx = -lx
        cmd.linear.x = lx

Key Advantage: Accurate distance is obtained without calibrating the actual target size. The tag_size parameter (default 0.048 m) must match the physical side length of the printed Tag, otherwise the 3D pose will be inaccurate.

2. Key Parameters

Parameter definition files:

• Launch: ~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/launch/april_tag_follow.launch.py
• Node: ~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/microros_v2_no_ptz_visual_control_pkg/april_tag_tracker_node.py

3. Node Description

6. Common Issues