ShisatoYano/AutonomousVehicleControlBeginnersGuide

Problem In src/components/state/state.py: The speed limiting code is duplicated in update() and update_by_localizer() draw() plots the whole position history every frame, so drawing gets slower as the simulation runs (11% of runtime in pure_pursuit_path_tracking) The argument name input in motion_model() shadows the Python built-in update_by_localizer() has no docstring Expected fix Extract the speed limiting into one private method, update the history plot incrementally (or with set_data, see the drawing performance issue), rename input, and add the missing docstring.

Problem In src/components/vehicle/vehicle_specification.py: Derived sizes use unexplained constants: f_edge_m = f_len_m + 0.5, tread_m = 0.25 * (1.0 + f_len_m + r_len_m), width_m = 1.0 * tread_m x_lim=MinMax(-30, 30) and y_lim=MinMax(-30, 30) are default arguments evaluated once, so all instances share the same objects area_size has no unit in its name, and axle_half_m is not documented Expected fix Name and explain the constants (or make them parameters with documented defaults), use None defaults for mutable arguments, rename area_size with a unit suffix, and document every argument with its unit.

Problem src/components/common/matrix_lib.py provides rot_mat_22 and hom_mat_33, but rotation matrices are also written by hand in other places, for example XYArray.homogeneous_transformation() in src/components/array/xy_array.py. XYArray also adds the translation with np.ones(shape) * [[x], [y]], where plain broadcasting (+ np.array([[x], [y]])) is enough. rot_mat_22 has no docstring. Expected fix Use rot_mat_22 in XYArray and in other hand-written rotations (find them with grep -rn "\-sin" src/components), simplify the translation, and add the missing docstring. Behavior must not change.

Problem draw_covariance_ellipse() exists in src/components/common/plot_lib.py, but the EKF, UKF and particle filter localizers each compute and draw the ellipse themselves (np.linalg.eig in extended_kalman_filter_localizer.py, unscented_kalman_filter_localizer.py, particle_filter_localizer.py). The helper also uses np.linalg.eig and Python loops. Expected fix Use draw_covariance_ellipse() in the three localizers In the helper, use np.linalg.eigh (covariance matrices are symmetric), compute the points with numpy instead of list comprehensions, and explain the scale factor 3.0 in a comment

Problem pi_to_pi() in src/components/common/angle_lib.py wraps an angle only once, so angles beyond ±3π are not normalized. The vehicle yaw angle is never normalized and keeps growing on courses with loops, and pi_to_pi() is used for the yaw error in cubic_spline_course.py and in lqr_controller.py. The same normalization is also implemented separately in several places: omni_directional_lidar.py (_normalize_angle_until_2pi, _normalize_angle_pi_2_pi) mppi_controller.py (% (2 * pi) and arctan2(sin, cos)) particle_filter_localizer.py (arctan2(sin, cos)) polar_histogram.py (% (2 * pi)) Expected fix Implement pi_to_pi correctly for any angle (e.g. (angle + pi) % (2 * pi) - pi), also accepting numpy arrays Use it (or a zero_to_2pi helper in the same module) instead of the local implementations Extend test/test_angle_lib.py with angles beyond ±3π