From 6b2c53c113078541cd56dbe72040484ed227981d Mon Sep 17 00:00:00 2001 From: Adi Vardi Date: Thu, 30 Apr 2026 08:39:37 +0200 Subject: [PATCH 1/2] Add doc for occupancy_check_min_distance Signed-off-by: Adi Vardi --- configuration/packages/configuring-mppic.rst | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/configuration/packages/configuring-mppic.rst b/configuration/packages/configuring-mppic.rst index e4a0e69cc..84f44368b 100644 --- a/configuration/packages/configuring-mppic.rst +++ b/configuration/packages/configuring-mppic.rst @@ -821,7 +821,18 @@ This critic incentivizes aligning with the global path, if relevant. It does not ============== =========================== Description - Maximum proportion of the path that can be occupied before this critic is not considered to allow the obstacle and path follow critics to avoid obstacles while following the path's intent in presence of dynamic objects in the scene. Between 0-1 for 0-100%. + Maximum proportion of a path segment that can be occupied before this critic is not considered to allow the obstacle and path follow critics to avoid obstacles while following the path's intent in presence of dynamic objects in the scene. Between 0-1 for 0-100%. + +:occupancy_check_min_distance: + + ============== =========================== + Type Default + -------------- --------------------------- + double 2.0 + ============== =========================== + + Description + Min distance for the occupancy check's path segment. The segment length is ``min(occupancy_check_min_distance, distance_to_furthest_reached_path_point).`` :use_path_orientations: @@ -1208,6 +1219,8 @@ The same applies to the Path Follow and Align offsets from furthest. In the same The Path Follow critic cannot drive velocities greater than the projectable distance of that velocity on the available path on the rolling costmap. The Path Align critic `offset_from_furthest` represents the number of path points a trajectory passes through while tracking the path. If this is set either absurdly low (e.g. 5) it can trigger when a robot is simply trying to start path tracking causing some suboptimal behaviors and local minima while starting a task. If it is set absurdly high (e.g. 50) relative to the path resolution and costmap size, then the critic may never trigger or only do so when at full-speed. A balance here is wise. A selection of this value to be ~30% of the maximum velocity distance projected is good (e.g. if a planner produces points every 2.5cm, 60 can fit on the 1.5m local costmap radius. If the max speed is 0.5m/s with a 3s prediction time, then 20 points represents 33% of the maximum speed projected over the prediction horizon onto the path). When in doubt, ``prediction_horizon_s * max_speed / path_resolution / 3.0`` is a good baseline. +If your robot's kinematics is very different than the defaults, you may need to tune ``PathAlignCritic.occupancy_check_min_distance``. This distance defines the min length of the path segment used to disable the ``PathAlignCritic``. A reasonable initial value should be the horizon's length at full speed. If the distance is too short, the robot may slow down when approaching an obstacle ahead and may even get too close to it and get stuck. If the distance is too big, the critic will be disabled too early, which may cause deviation from path (if for example, the reference point for PathFollowCritic is beyond a curve on the path). + Obstacle, Inflation Layer, and Path Following --------------------------------------------- From 1a12613d73e0d992b3b8dcfb9a541d05c5fe0b6f Mon Sep 17 00:00:00 2001 From: Adi Vardi Date: Thu, 30 Apr 2026 17:08:26 +0200 Subject: [PATCH 2/2] rename param & add note Signed-off-by: Adi Vardi --- configuration/packages/configuring-mppic.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/configuration/packages/configuring-mppic.rst b/configuration/packages/configuring-mppic.rst index 84f44368b..7b6ec37f4 100644 --- a/configuration/packages/configuring-mppic.rst +++ b/configuration/packages/configuring-mppic.rst @@ -823,7 +823,7 @@ This critic incentivizes aligning with the global path, if relevant. It does not Description Maximum proportion of a path segment that can be occupied before this critic is not considered to allow the obstacle and path follow critics to avoid obstacles while following the path's intent in presence of dynamic objects in the scene. Between 0-1 for 0-100%. -:occupancy_check_min_distance: +:min_distance_occupancy_check: ============== =========================== Type Default @@ -832,7 +832,7 @@ This critic incentivizes aligning with the global path, if relevant. It does not ============== =========================== Description - Min distance for the occupancy check's path segment. The segment length is ``min(occupancy_check_min_distance, distance_to_furthest_reached_path_point).`` + Min distance for the occupancy check's path segment. The segment length is ``min(min_distance_occupancy_check, distance_to_furthest_reached_path_point).`` :use_path_orientations: @@ -1219,7 +1219,9 @@ The same applies to the Path Follow and Align offsets from furthest. In the same The Path Follow critic cannot drive velocities greater than the projectable distance of that velocity on the available path on the rolling costmap. The Path Align critic `offset_from_furthest` represents the number of path points a trajectory passes through while tracking the path. If this is set either absurdly low (e.g. 5) it can trigger when a robot is simply trying to start path tracking causing some suboptimal behaviors and local minima while starting a task. If it is set absurdly high (e.g. 50) relative to the path resolution and costmap size, then the critic may never trigger or only do so when at full-speed. A balance here is wise. A selection of this value to be ~30% of the maximum velocity distance projected is good (e.g. if a planner produces points every 2.5cm, 60 can fit on the 1.5m local costmap radius. If the max speed is 0.5m/s with a 3s prediction time, then 20 points represents 33% of the maximum speed projected over the prediction horizon onto the path). When in doubt, ``prediction_horizon_s * max_speed / path_resolution / 3.0`` is a good baseline. -If your robot's kinematics is very different than the defaults, you may need to tune ``PathAlignCritic.occupancy_check_min_distance``. This distance defines the min length of the path segment used to disable the ``PathAlignCritic``. A reasonable initial value should be the horizon's length at full speed. If the distance is too short, the robot may slow down when approaching an obstacle ahead and may even get too close to it and get stuck. If the distance is too big, the critic will be disabled too early, which may cause deviation from path (if for example, the reference point for PathFollowCritic is beyond a curve on the path). +If your robot's kinematics is very different than the defaults, you may need to tune ``PathAlignCritic.min_distance_occupancy_check``. This distance defines the min length of the path segment used to disable the ``PathAlignCritic``. A reasonable initial value should be the horizon's length (``= time_step*model_dt``) at full speed. If the distance is too short, the robot may slow down when approaching an obstacle ahead and may even get too close to it and get stuck. If the distance is too big, the critic will be disabled too early, which may cause deviation from path (if for example, the reference point for PathFollowCritic is beyond a curve on the path). + +Note: that a sufficiently long horizon length is needed for this behavior to work well. If the horizon is too short, the controller may not find trajectories around the obstacle. Obstacle, Inflation Layer, and Path Following ---------------------------------------------