Task3/line_follower/config/line_follow_debug.yaml

# This node is visualisation-only: it never publishes /cmd_vel.
image_topic: /usb_cam/image_raw

# Metric inverse-perspective mapping (IPM), calibrated on 2026-08-10 with
# four ground marks measured from the vehicle-front centre.  The raw USB
# camera is horizontally mirrored, so its physical left marks appear at the
# right side of the source image.  The matching destinations undo that mirror.
# Point order: near-left, near-right, far-right, far-left.
use_perspective_transform: true
perspective_reference_size: [640, 480]
src_pts: [[562, 304], [75, 307], [193, 240], [466, 237]]
dst_pts: [[240, 360], [400, 360], [400, 120], [240, 120]]

# Process at half resolution for real-time control, then scale debug views
# back to the display size.  Published error is converted back to 640-pixel
# coordinates, so the controller parameters do not need changing.
processing_scale: 0.5
# GUI is intentionally slower than perception.  It must never throttle the
# messages consumed by the controller.
display_rate: 10.0

# Legacy scanline-offset compensation remains disabled.  The controller now
# uses a metric target point on the fitted IPM centreline.
use_camera_front_offset: false
camera_to_front_offset_m: 0.125
# Zero means calculate automatically from camera_to_front_offset_m and the
# metric IPM scale.  A positive value overrides it in 640x480 reference pixels.
camera_front_offset_px: 0
metric_scale_px_per_m: 400.0
metric_origin_px: [320, 480]
# Pure-pursuit target geometry.  The calibrated IPM origin is treated as
# 125 mm ahead of the robot control centre; the desired target lies 300 mm
# ahead of that control centre.  When the nearest reliable curve sample is
# farther away, continue only its tangent toward the vehicle by at most 250 mm.
lookahead_distance_m: 0.30
# Keep 0.30 m for LEFT/RIGHT routes and before the second maneuver. Once the
# STRAIGHT route completes its fixed second right turn and enters
# FOLLOW_AFTER_SECOND, automatically use 0.35 m without restarting this node.
task_state_topic: /traffic_line_task/state
normal_lookahead_distance_m: 0.30
after_second_lookahead_distance_m: 0.35
# Only after the second fixed right turn, move a curved lookahead target 25 mm
# farther toward that curve's inside. Near-straight targets remain centred.
after_second_inner_offset_m: 0.025
inner_offset_activation_m: 0.015
ipm_origin_ahead_of_control_m: 0.125
max_near_target_extrapolation_m: 0.25
lookahead_frame_id: base_link
# Ordered click targets: near-left, near-right, far-right, far-left.
# Each is [forward metres from vehicle-front centre, left metres].  These
# values are the four marks used for the current src_pts/dst_pts calibration.
calibration_markers_m: [[0.30, 0.20], [0.30, -0.20], [0.90, -0.20], [0.90, 0.20]]

# OpenCV HSV white-line threshold.  The upper scene (LED board, wall and desk)
# is excluded by roi_top_ratio before any line candidates are selected.
hsv_lower: [0, 0, 180]
hsv_upper: [180, 60, 255]
# In the real first/second junction images, the white route boundaries occupy
# approximately y=200..330 of a 480-pixel image.  Do not start at y=249: that
# misses the branches entirely.
roi_top_ratio: 0.42

# Several horizontal bands are checked from near to far.  At the first and
# second forks the visible white lines move high in the image, so one fixed
# scanline is not reliable.
scanline_ratios: [0.82, 0.79, 0.76, 0.73, 0.70, 0.66, 0.62, 0.58, 0.54, 0.50, 0.46]
scanline_half_height: 5
min_run_width: 3

# Discard isolated white connected components smaller than this area (pixels).
# Route boundaries in the collected images are long components, while floor
# speckles and LED artifacts are much smaller.
min_component_area: 30
# connectedComponentsWithStats is too slow on the vehicle at 640x480.  The
# 3x3 morphology above remains enabled; turn this on only for offline tuning.
use_component_filter: false

# Do not mask the image centre.  Set this above zero only if a later test
# confirms that LED reflection must be excluded again.
center_reflection_half_width_ratio: 0.0
# The metric calibration maps a 410 mm lane to about 25% of the processing
# image width.  Run centres and tape thickness can make the measured value a
# few pixels smaller, and some route sections are narrower, so keep margin.
min_lane_width_ratio: 0.18
max_lane_width_ratio: 0.98
morphology_kernel: 3

# A bend can temporarily hide its inner boundary.  Remember the most recent
# two-boundary width and infer the midpoint from the remaining outer boundary.
# The real finish bend hides its inner boundary for several seconds. Continue
# only while the same outer boundary remains visible, with an eight-second hard
# limit; complete/ambiguous line loss still publishes lane_valid=false.
use_single_boundary_fallback: true
single_boundary_timeout: 8.0
# Preserve the physical side identity briefly when the curved outer line
# crosses the image centre or one camera frame is missed.
single_boundary_side_memory_timeout: 0.75
lane_width_alpha: 0.2

# Fit a curved centreline through all usable near/far scan bands.  The fitted
# tangent remains available for diagnostics, while the metric point on this
# curve is published as /line_follow_debug/lookahead_target.
max_centerline_heading_rad: 0.70