adding migration info + configuration guide for changes to refinement_num (#370)

Author: SteveMacenski

configuration/packages/configuring-simple-smoother.rst

@@ -36,6 +36,17 @@ Simple Smoother Parameters
   Description
     Whether to smooth the smoothed path recursively to refine the quality further
 
+:refinement_num:
+
+  ============== ===========================
+  Type           Default                    
+  -------------- ---------------------------
+  int            2   
+  ============== ===========================
+
+  Description
+    Number of times to recursively attempt to smooth, must be ``>= 1``.
+
 :max_its:
 
   ============== ===========================
@@ -84,6 +95,7 @@ Example
           plugin: "nav2_smoother::SimpleSmoother"
           tolerance: 1.0e-10
           do_refinement: True
+          refinement_num: 2
           max_its: 1000
           w_data: 0.2
           w_smooth: 0.3

configuration/packages/smac/configuring-smac-hybrid.rst

@@ -288,6 +288,17 @@ Parameters
   Description
     Performs extra refinement smoothing runs. Essentially, this recursively calls the smoother using the output from the last smoothing cycle to further smooth the path for macro-trends. This typically improves quality especially in the Hybrid-A* planner due to the extra "wobbling" it can have due to the very small primitive lengths but may cause the path to get slightly closer to some obstacles.
 
+:``<name>``.smoother.refinement_num:
+
+  ============== ===========================
+  Type           Default                    
+  -------------- ---------------------------
+  int            2   
+  ============== ===========================
+
+  Description
+    Number of times to recursively attempt to smooth, must be ``>= 1``.
+
 Example
 *******
 .. code-block:: yaml
@@ -326,3 +337,4 @@ Example
           w_data: 0.2
           tolerance: 1.0e-10
           do_refinement: true
+          refinement_num: 2

configuration/packages/smac/configuring-smac-lattice.rst

@@ -270,6 +270,17 @@ Parameters
   Description
     Performs extra refinement smoothing runs. Essentially, this recursively calls the smoother using the output from the last smoothing cycle to further smooth the path for macro-trends. This typically improves quality especially in the Hybrid-A* planner but can be helpful on the state lattice planner to reduce the "blocky" movements in State Lattice caused by the limited number of headings.
 
+:``<name>``.smoother.refinement_num:
+
+  ============== ===========================
+  Type           Default                    
+  -------------- ---------------------------
+  int            2   
+  ============== ===========================
+
+  Description
+    Number of times to recursively attempt to smooth, must be ``>= 1``.
+
 Example
 *******
 .. code-block:: yaml
@@ -305,3 +316,4 @@ Example
           w_data: 0.2
           tolerance: 1.0e-10
           do_refinement: true
+          refinement_num: 2

migration/Humble.rst

@@ -17,6 +17,11 @@ Run-time Speed up of Smac Planner
 *********************************
 The core data structure of the graph implementation in the Smac Planner framework was swapped out in `PR 3201 <https://github.com/ros-planning/navigation2/pull/3201>`_ to using a specialized unordered map implementation. This speeds up the planner by 10% on trivial requests and reports up to 30% on complex plans that involve numerous rehashings.
 
+Recursive Refinement of Smac and Simple Smoothers
+*************************************************
+
+The number of recursive refinements for the Simple and Smac Planner Smoothers have been exposed under the ``refinement_num`` parameter. Previous behavior had this hardcoded if ``do_refinement = True`` to ``4``. Now, default is ``2`` to help decrease out-of-the-box over smoothing reducing in paths closer to collision than probably ideal, but old behavior can be achieved by changing this to ``4``.
+
 Simple Commander Python API
 ***************************
 `PR 3159 <https://github.com/ros-planning/navigation2/pull/3159>`_ and follow-up PRs add in Costmap API in Python3 simple commander to receive ``OccupancyGrid`` messages from Nav2 and be able to work with them natively in Python3, analog to the C++ Costmap API. It also includes a line iterator and collision checking object to perform footprint or other collision checking in Python3. See the Simple Commander API for more details.