Merge pull request #29 from automatika-robotics/feature/vision_dwa

Author: aleph-ra

.github/workflows/build_and_deploy.yml

@@ -16,7 +16,7 @@ jobs:
       matrix:
         os-arch:
           - { os: ubuntu-latest, arch: x86_64 }
-          - { os: ubuntu-24.04-arm, arch: aarch64 }
+          # - { os: ubuntu-24.04-arm, arch: aarch64 }
 
     name: Build wheels on ${{ matrix.os-arch.os }} ${{ matrix.os-arch.arch }}
     runs-on: ${{ matrix.os-arch.os }}
@@ -27,6 +27,12 @@ jobs:
       - name: Set environment variables
         run: echo "CIBW_ARCHS=${{ matrix.os-arch.arch }}" >> $GITHUB_ENV
 
+      - name: Install Python development headers
+        run: |
+             PYTHON_VERSION=$(python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
+             sudo apt-get update
+             sudo apt-get install -y python${PYTHON_VERSION}-dev
+
       - name: Build wheels
         uses: pypa/cibuildwheel@v2.21.3
 

README.md

@@ -1,105 +1,110 @@
 # Kompass Core
 
+[![中文版本][cn-badge]][cn-url]
+[![ドキュメント-日本語][jp-badge]][jp-url]
 [![PyPI][pypi-badge]][pypi-url]
 [![MIT licensed][mit-badge]][mit-url]
 [![Python Version][python-badge]][python-url]
 
+[cn-badge]: https://img.shields.io/badge/文档-中文-blue.svg
+[cn-url]: docs/README.zh.md
+[jp-badge]: https://img.shields.io/badge/ドキュメント-日本語-red.svg
+[jp-url]: docs/README.ja.md
 [pypi-badge]: https://img.shields.io/pypi/v/kompass-core.svg
 [pypi-url]: https://pypi.org/project/kompass-core/
 [mit-badge]: https://img.shields.io/pypi/l/kompass-core.svg
 [mit-url]: https://github.com/automatika-robotics/kompass-core/LICENSE
 [python-badge]: https://img.shields.io/pypi/pyversions/kompass-core.svg
 [python-url]: https://www.python.org/downloads/
 
-Kompass Core is a fast, GPU powered motion planning and control package for robot navigation. The package contains C++ implementation for core algorithms along with Python wrappers. It also implements third party integrations with [OMPL](https://ompl.kavrakilab.org/) and [FCL](https://github.com/flexible-collision-library/fcl). The Kompass philosophy is to be blazzingly fast and highly reliable, by implementing GPGPU supported parallelized algorithms which are agnostic to underlying hardware. Thus Kompass Core can be run on CPUs, GPUs or FPGAs from a wide variety of vendors, making it easy for robot hardware manufacturers to switch underlying compute architecture.
+Kompass Core is a high-performance, GPU-accelerated library for motion planning, mapping, and control in robot navigation systems. The core algorithms are implemented in C++ with seamless Python bindings. It also implements third party integrations with [OMPL](https://ompl.kavrakilab.org/) and [FCL](https://github.com/flexible-collision-library/fcl). The Kompass philosophy is to be blazzingly fast and highly reliable, by implementing GPGPU supported parallelized algorithms which are agnostic to underlying hardware. Thus Kompass Core can be run on CPUs or GPUs from a wide variety of vendors, making it easy for robot hardware manufacturers to switch underlying compute architecture without overhauling their software stack.
 
 This package is developed to be used with [Kompass](https://github.com/automatika-robotics/kompass) for creating navigation stacks in [ROS2](https://docs.ros.org/en/rolling/index.html). For detailed usage documentation, check Kompass [docs](https://automatika-robotics.github.io/kompass/).
 
-## Installation
 
-### Install with GPU Support (Recommended)
+- [**Install**](#installation) Kompass Core 🛠️
+- Check the [**Package Overview**](#-package-overview)
+- To use Kompass Core on your robot with ROS2, check the [**Kompass**](https://automatika-robotics.github.io/kompass) framework 🚀
 
-To install kompass-core with GPU support, on any Ubuntu 20+ (including Jetpack) based machine, you can simply run the following:
 
-- `curl https://raw.githubusercontent.com/automatika-robotics/kompass-core/refs/heads/main/build_dependencies/install_gpu.sh | bash`
+# Installation
+
+## Install with GPU Support (Recommended)
+
+- To install kompass-core with GPU support, on any Ubuntu 20+ (including Jetpack) based machine, you can simply run the following:
+
+```bash
+curl https://raw.githubusercontent.com/automatika-robotics/kompass-core/refs/heads/main/build_dependencies/install_gpu.sh | bash
+```
 
 This script will install all relevant dependencies, including [AdaptiveCPP](https://github.com/AdaptiveCpp/AdaptiveCpp) and install the latest version of kompass-core from source. It is good practice to read the [script](https://github.com/automatika-robotics/kompass-core/blob/main/build_dependencies/install_gpu.sh) first.
 
-### Installing with pip (CPU only)
+## Installing with pip (CPU only)
 
-On Ubuntu versions >= 22.04, install dependencies by running the following:
+- On Ubuntu versions >= 22.04, install dependencies by running the following:
 
-- `sudo apt-get install libompl-dev libfcl-dev libpcl-dev`
+```bash
+sudo apt-get install libompl-dev libfcl-dev libpcl-dev
+```
 
-Then install kompass-core as follows:
+- Then install kompass-core as follows:
 
-- `pip install kompass-core`
+```bash
+pip install kompass-core
+```
 
 Wheels are available on Pypi for linux x86_64 and aarch64 architectures. Please note that the version available on Pypi does not support GPU acceleration yet.
 
-### Installation Contents
+## Installation Contents
 
 The following three packages will become available once kompass-core is installed.
 
-- `kompass_core`: The main Python API containing all the wrappers and utilities for motion planning and control for navigation in 2D spaces.
-- `kompass_cpp`: Python bindings for Kompass core C++ library containing the algorithms implementation for path tracking and motion control.
+- `kompass_cpp`: Core C++ library for control, collision checking, and mapping algorithms.
+- `kompass_core`: Python bindings for Kompass core C++ library with front-end classes for configuration and high-level logic.
 - `omplpy`: Bespoke python bindings for the Open Motion Planning Library (OMPL).
 
-## Testing
 
-### Run Planning Test
+# 📦 Package Overview
 
-- `cd tests`
-- `python3 test_ompl.py`
+The package includes modules for mapping, control, trajectory planning, and vision-based tracking algorithms, with **GPU acceleration** support and Python bindings via `nanobind`.
 
-To test path planning using OMPL bindings a reference planning problem is provided using Turtlebot3 Waffle map and fixed start and end position. The test will simulate the planning problem for all geometric planners for the number of desired repetitions to get average values.
 
-### Run Controllers Test
+### Control Module
+- Includes a rich set of optimized C++ control strategies implementations and their python wrappers.
+- Supports **GPU-accelerated** trajectory sampling and cost evaluation with customizable weights for sampling based controllers.
+- Internally implements feature-based bounding box tracking and depth detection for enhanced vision-based tracking control.
 
-- `cd tests`
-- `python3 test_controllers.py`
+| Algorithm                                   | Description                                        |
+| ------------------------------------------- | -------------------------------------------------- |
+| **Stanley**                   | Path tracking with robust convergence              |
+| **DWA (Dynamic Window Approach)** | Velocity-space sampling and optimization           |
+| **DVZ**                           | Reactive obstacle avoidance using deformable zones |
+| **VisionRGBFollower**   | Follow visual targets using RGB images          |
+| **VisionRGBDFollower**   | Follow visual targets using RGBD (depth) images          |
 
-The test will simulate path tracking using a reference global path. The results plot for each available controller will be generated in tests/resources/control
+### Mapping Module
+- Implements efficient local mapping and occupancy grid generation algorithms, with configuration support for various laser models and grid resolution settings.
+- Supports **GPU-accelerated** mapping for real-time performance.
 
-## Usage Example
 
-```python
-from kompass_core.control import DVZ
+### Utilities Module
+- Provides collision checking utilities and critical zone detection to ensure safe navigation, including both CPU and GPU implementations.
+- Logger utilities for runtime diagnostics.
+- Linear state-space Kalman filter implementation for state estimation (C++).
+- Spline interpolation utilities for path control.
 
-from kompass_core.models import (
-    AngularCtrlLimits,
-    LinearCtrlLimits,
-    Robot,
-    RobotCtrlLimits,
-    RobotGeometry,
-    RobotType,
-)
+### Data Types and Models Modules
+- Rich set of data types to represent paths, trajectories, controls, velocities, bounding boxes and various sensor data.
+- Strongly-typed parameters and configuration classes to enable flexible tuning.
+- Robot models and motion kinematics, supporting differential, omni-directional, and Ackermann robots. Along with geometry definitions, control limits and simulation-ready state representations.
 
-# Setup the robot
-my_robot = Robot(
-        robot_type=RobotType.ACKERMANN,
-        geometry_type=RobotGeometry.Type.CYLINDER,
-        geometry_params=np.array([0.1, 0.4]),
-    )
+### Third Party Modules
+Includes wrappers and integrations with external planning and collision libraries:
 
-# Set the robot control limits
-robot_ctr_limits = RobotCtrlLimits(
-    vx_limits=LinearCtrlLimits(max_vel=1.0, max_acc=5.0, max_decel=10.0),
-    omega_limits=AngularCtrlLimits(
-        max_vel=2.0, max_acc=3.0, max_decel=3.0, max_steer=np.pi
-    ),
-)
+- FCL (Flexible Collision Library)
 
-# Set the control time step (s)
-control_time_step = 0.1     # seconds
+- OMPL (Open Motion Planning Library)
 
-# Initialize the controller
-dvz = DVZ(
-        robot=my_robot,
-        ctrl_limits=robot_ctr_limits,
-        control_time_step=control_time_step,
-    )
-```
 
 ## Copyright
 

build_dependencies/install_gpu.sh

@@ -162,8 +162,8 @@ install_dependencies
 # Check for LLVM/Clang versions
 if [[ $LLVM_VERSION ]]; then
     # Check if given version is within range
-    if (( LLVM_VERSION < 14 || LLVM_VERSION > 17 )); then
-        log ERROR "LLVM Versions higher than 17 and lower than 14 are not compatible with kompass-core."
+    if (( LLVM_VERSION < 15 || LLVM_VERSION > 17 )); then
+        log ERROR "LLVM Versions higher than 20 and lower than 15 are not compatible with kompass-core."
         exit 1
     fi
     if check_llvm_clang_version $LLVM_VERSION; then