Refactor module links and improve code documentation. (#1211)

* Refactor module links and improve code documentation.

Updated documentation to rename "API" sections to "Code Link" for clarity and consistency. Enhanced docstrings for `circle_fitting` and `kmeans_clustering` functions, improving parameter descriptions and adding return value details. Fixed typos in function and file names in the ray casting grid map module.

* Fix import typo in ray casting grid map test module.

Corrected the import statement in the test file by updating the module's name to `ray_casting_grid_map` for consistency with the source file. This ensures proper functionality of the test suite.

Author: AtsushiSakai

Mapping/circle_fitting/circle_fitting.py

@@ -16,12 +16,33 @@
 
 def circle_fitting(x, y):
     """
-    Circle Fitting with least squared
-        input: point x-y positions
-        output  cxe x center position
-                cye y center position
-                re  radius of circle
-                error: prediction error
+    Fits a circle to a given set of points using a least-squares approach.
+
+    This function calculates the center (x, y) and radius of a circle that best fits
+    the given set of points in a two-dimensional plane. It minimizes the squared
+    errors between the circle and the provided points and returns the calculated
+    center coordinates, radius, and the fitting error.
+
+    Raises
+    ------
+    ValueError
+        If the input lists x and y do not contain the same number of elements.
+
+    Parameters
+    ----------
+    x : list[float]
+        The x-coordinates of the points.
+    y : list[float]
+        The y-coordinates of the points.
+
+    Returns
+    -------
+    tuple[float, float, float, float]
+        A tuple containing:
+        - The x-coordinate of the center of the fitted circle (float).
+        - The y-coordinate of the center of the fitted circle (float).
+        - The radius of the fitted circle (float).
+        - The fitting error as a deviation metric (float).
     """
 
     sumx = sum(x)

Mapping/kmeans_clustering/kmeans_clustering.py

@@ -17,12 +17,37 @@
 
 
 def kmeans_clustering(rx, ry, nc):
+    """
+    Performs k-means clustering on the given dataset, iteratively adjusting cluster centroids
+    until convergence within a defined threshold or reaching the maximum number of
+    iterations.
+
+    The implementation initializes clusters, calculates initial centroids, and refines the
+    clusters through iterative updates to optimize the cost function based on minimum
+    distance between datapoints and centroids.
+
+    Arguments:
+        rx: List[float]
+            The x-coordinates of the dataset points to be clustered.
+        ry: List[float]
+            The y-coordinates of the dataset points to be clustered.
+        nc: int
+            The number of clusters to group the data into.
+
+    Returns:
+        Clusters
+            An instance containing the final cluster assignments and centroids after
+            convergence.
+
+    Raises:
+        None
+
+    """
     clusters = Clusters(rx, ry, nc)
     clusters.calc_centroid()
 
     pre_cost = float("inf")
     for loop in range(MAX_LOOP):
-        print("loop:", loop)
         cost = clusters.update_clusters()
         clusters.calc_centroid()
 

Mapping/raycasting_grid_map/raycasting_grid_map.py renamed to Mapping/ray_casting_grid_map/ray_casting_grid_map.py

@@ -48,7 +48,7 @@ def atan_zero_to_twopi(y, x):
     return angle
 
 
-def precasting(minx, miny, xw, yw, xyreso, yawreso):
+def pre_casting(minx, miny, xw, yw, xyreso, yawreso):
 
     precast = [[] for i in range(int(round((math.pi * 2.0) / yawreso)) + 1)]
 
@@ -81,7 +81,7 @@ def generate_ray_casting_grid_map(ox, oy, xyreso, yawreso):
 
     pmap = [[0.0 for i in range(yw)] for i in range(xw)]
 
-    precast = precasting(minx, miny, xw, yw, xyreso, yawreso)
+    precast = pre_casting(minx, miny, xw, yw, xyreso, yawreso)
 
     for (x, y) in zip(ox, oy):
 

docs/modules/3_mapping/circle_fitting/circle_fitting_main.rst

@@ -11,3 +11,7 @@ The red crosses are observations from a ranging sensor.
 
 The red circle is the estimated object shape using circle fitting.
 
+Code Link
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: Mapping.circle_fitting.circle_fitting.circle_fitting

docs/modules/3_mapping/distance_map/distance_map_main.rst

@@ -14,8 +14,8 @@ The algorithm is demonstrated on a simple 2D grid with obstacles:
 
 .. image:: distance_map.png
 
-API
-~~~
+Code Link
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. autofunction:: Mapping.DistanceMap.distance_map.compute_sdf
 

docs/modules/3_mapping/gaussian_grid_map/gaussian_grid_map_main.rst

@@ -6,3 +6,9 @@ Gaussian grid map
 This is a 2D Gaussian grid mapping example.
 
 .. image:: https://github.com/AtsushiSakai/PythonRoboticsGifs/raw/master/Mapping/gaussian_grid_map/animation.gif
+
+Code Link
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: Mapping.gaussian_grid_map.gaussian_grid_map.generate_gaussian_grid_map
+

docs/modules/3_mapping/k_means_object_clustering/k_means_object_clustering_main.rst

@@ -4,3 +4,9 @@ k-means object clustering
 This is a 2D object clustering with k-means algorithm.
 
 .. image:: https://github.com/AtsushiSakai/PythonRoboticsGifs/raw/master/Mapping/kmeans_clustering/animation.gif
+
+Code Link
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: Mapping.kmeans_clustering.kmeans_clustering.kmeans_clustering
+

docs/modules/3_mapping/lidar_to_grid_map_tutorial/lidar_to_grid_map_tutorial_main.rst

@@ -196,3 +196,9 @@ Let’s use this flood fill on real data:
 
 .. image:: lidar_to_grid_map_tutorial_14_1.png
 
+Code Link
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: Mapping.lidar_to_grid_map.lidar_to_grid_map.main
+
+

docs/modules/3_mapping/normal_vector_estimation/normal_vector_estimation_main.rst

@@ -25,8 +25,8 @@ This is an example of normal vector calculation:
 
 .. figure:: normal_vector_calc.png
 
-API
-=====
+Code Link
+==========
 
 .. autofunction:: Mapping.normal_vector_estimation.normal_vector_estimation.calc_normal_vector
 
@@ -67,8 +67,8 @@ This is an example of RANSAC based normal vector estimation:
 
 .. figure:: ransac_normal_vector_estimation.png
 
-API
-=====
+Code Link
+==========
 
 .. autofunction:: Mapping.normal_vector_estimation.normal_vector_estimation.ransac_normal_vector_estimation
 

docs/modules/3_mapping/point_cloud_sampling/point_cloud_sampling_main.rst

@@ -27,8 +27,8 @@ This method determines which each point is in a grid, and replaces the point
 clouds that are in the same Voxel with their average to reduce the number of
 points.
 
-API
-=====
+Code Link
+==========
 
 .. autofunction:: Mapping.point_cloud_sampling.point_cloud_sampling.voxel_point_sampling
 
@@ -61,8 +61,8 @@ Although this method does not have good performance comparing the Farthest
 distance sample where each point is distributed farther from each other,
 this is suitable for real-time processing because of its fast computation time.
 
-API
-=====
+Code Link
+==========
 
 .. autofunction:: Mapping.point_cloud_sampling.point_cloud_sampling.poisson_disk_sampling