automatika-robotics · aleph-ra · Jul 1, 2025 · Apr 4, 2025 · Apr 4, 2025 · Apr 4, 2025
diff --git a/.github/workflows/build_and_deploy.yml b/.github/workflows/build_and_deploy.yml
@@ -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
 

diff --git a/README.md b/README.md
@@ -1,105 +1,111 @@
 # 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)
+- [**Copyright**](#copyright) and [**Contributions**](#contributions)
+- 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
 

diff --git a/build_dependencies/install_gpu.sh b/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

diff --git a/docs/README.ja.md b/docs/README.ja.md
@@ -0,0 +1,158 @@
+# Kompass Core
+
+[![English Version][en-badge]][en-url]
+[![中文版本][cn-badge]][cn-url]
+[![PyPI][pypi-badge]][pypi-url]
+[![MIT licensed][mit-badge]][mit-url]
+[![Python Version][python-badge]][python-url]
+
+[en-badge]: https://img.shields.io/badge/Documentation-English-green.svg
+[en-url]: ../README.md
+[cn-badge]: https://img.shields.io/badge/文档-中文-blue.svg
+[cn-url]: README.zh.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** は、ロボットナビゲーションシステムにおける経路計画、マッピング、および制御のための高性能で GPU アクセラレーション対応のライブラリです。コアアルゴリズムは C++ で実装され、Python バインディングによってシームレスに利用できます。また、[OMPL](https://ompl.kavrakilab.org/) や [FCL](https://github.com/flexible-collision-library/fcl) との外部統合も備えています。
+
+Kompass の理念は、「驚異的な高速性」と「高信頼性」を追求することです。GPGPU 対応の並列アルゴリズムを基盤とし、ハードウェアに依存しない設計を実現しているため、Kompass Core はさまざまなベンダーの CPU または GPU 上で実行可能です。これにより、ロボットハードウェアメーカーは、ソフトウェアスタックを大きく変更することなく、計算アーキテクチャを柔軟に切り替えることが可能です。
+
+このパッケージは、[ROS2](https://docs.ros.org/en/rolling/index.html) 上でナビゲーションスタックを構築するための [Kompass](https://github.com/automatika-robotics/kompass) と共に使用するように設計されています。詳細な使用方法については、[Kompass ドキュメント](https://automatika-robotics.github.io/kompass/) をご覧ください。
+
+- [**インストール**](#installation) Kompass Core 🛠️
+- [**パッケージ概要**](#-package-overview) を確認
+- [**著作権**](#copyright) および [**コントリビューション**](#contributions)
+- ROS2 環境でロボットに Kompass Core を導入したい場合は、[**Kompass**](https://automatika-robotics.github.io/kompass) フレームワークをご参照ください 🚀
+
+# インストール方法
+
+## GPU サポート付きインストール（推奨）
+
+Ubuntu 20 以降（Jetpack を含む）の任意のマシンに GPU サポート付きで kompass-core をインストールするには、以下を実行します：
+
+```bash
+curl https://raw.githubusercontent.com/automatika-robotics/kompass-core/refs/heads/main/build_dependencies/install_gpu.sh | bash
+```
+
+このスクリプトは、[AdaptiveCPP](https://github.com/AdaptiveCpp/AdaptiveCpp) を含むすべての関連依存関係をインストールし、`kompass-core` の最新版をソースから構築します。実行前に、[スクリプト](https://github.com/automatika-robotics/kompass-core/blob/main/build_dependencies/install_gpu.sh) の内容を確認することを推奨します。
+
+
+## pip によるインストール（CPU のみ）
+
+- Ubuntu 22.04 以降では、以下のコマンドで依存パッケージをインストールします：
+
+```bash
+  sudo apt-get install libompl-dev libfcl-dev libpcl-dev
+```
+- その後、以下のように kompass-core をインストールします：
+
+```bash
+pip install kompass-core
+```
+
+PyPI では、Linux x86_64 と aarch64 向けのホイールが提供されています。なお、現時点で PyPI にあるバージョンは GPU アクセラレーションには対応していません。
+
+
+## インストール内容
+
+kompass-core をインストールすると、以下の 3 つのパッケージが使用可能になります。
+
+- `kompass_core`：2D 空間でのナビゲーションのための運動計画と制御に関するラッパーやユーティリティを含む主要な Python API
+- `kompass_cpp`：経路追跡および運動制御アルゴリズムを実装した Kompass コア C++ ライブラリの Python バインディング
+- `omplpy`：Open Motion Planning Library（OMPL）向けに特化した Python バインディング
+
+# 📦 パッケージ概要
+
+本リポジトリには以下のモジュールが含まれます：
+
+- `kompass_cpp/` — 計画、制御、衝突判定、マッピングアルゴリズムを実装したコア C++ モジュール
+
+- `kompass_core/` — 設定や高レベルロジックのための Python 実装およびフロントエンドクラス
+
+## `kompass_cpp` モジュール概要
+
+`kompass_cpp/` はマッピング、制御、軌道計画、視覚ベースのトラッキングアルゴリズムを含む C++ パッケージであり、**GPU アクセラレーション** をサポートし、`nanobind` 経由で Python バインディングが提供されています。
+
+### 1. マッピング
+- 高速な局所マッピングアルゴリズムを実装
+- **GPU アクセラレーション** に対応しリアルタイム性能を実現
+- 主なクラス：`LocalMapper`, `LocalMapperGPU`
+
+### 2. 制御と軌道計画
+- PID、Stanley、動的ウィンドウ法（DWA）、ビジョンガイドコントローラなど複数の制御戦略を搭載
+- **GPU アクセラレーション** による軌道サンプリングとコスト評価、重みのカスタマイズが可能
+- 主なクラス：`Controller`, `PID`, `Stanley`, `DWA`, `VisionDWA`, `TrajectorySampler`, `CostEvaluator`
+
+### 3. 衝突判定とクリティカルゾーン検出
+- 安全なナビゲーションを実現する衝突判定とクリティカルゾーン検出機能を提供
+- CPU 実装と GPU 実装の両方に対応
+- 主なクラス：`CollisionChecker`, `CriticalZoneChecker`, `CriticalZoneCheckerGPU`
+
+### 4. ビジョンとトラッキング
+- 特徴点ベースのバウンディングボックス追跡と深度検出により認識性能を強化
+- 頑健な視覚ベースのナビゲーションアルゴリズムをサポート
+- 主なクラス：`FeatureBasedBboxTracker`, `DepthDetector`
+
+### 5. ユーティリティ
+- 高効率なマルチスレッド処理を実現するスレッドプール
+- 実行時診断用のロガー
+- 線形状態空間カルマンフィルタによる状態推定
+- `tk` 名前空間で提供されるスプライン補間ユーティリティ
+
+### 6. データ型とパラメータ
+- 経路、軌道、制御、速度、バウンディングボックスを表現する豊富なデータ型
+- 柔軟なパラメータ調整を可能にする強型の設定クラス
+
+### 7. Python バインディング
+- `nanobind` によって構築された包括的な Python バインディングにより、Python ワークフローとシームレスに統合可能
+- マッピング、制御、ビジョン、ユーティリティの主要機能を広くカバー
+
+## `kompass_core` モジュール概要
+
+- `kompass_core.calibration` - ロボット運動モデルのキャリブレーション、フィッティング、ロボットシミュレーション用モジュール
+
+- `kompass_core.control` - 多様な制御戦略と設定を含む。C++ 実装の Python ラッパークラスを提供：
+
+| アルゴリズム名                        | 説明                                       |
+|---------------------------------------|------------------------------------------|
+| **Stanley**                          | 高い収束性能を持つ経路追従                |
+| **DWA（動的ウィンドウ法）**         | 速度空間のサンプリングと最適化             |
+| **DVZ**                              | 可変ゾーンを用いたリアクティブな障害物回避 |
+| **VisionRGBFollower**               | RGB 画像を用いた視覚ターゲット追従         |
+| **VisionRGBDFollower**              | RGBD（深度付き）画像を用いた視覚ターゲット追従 |
+
+- `kompass_core.datatypes` - ロボットやセンサーデータ用の標準メッセージ・データ形式
+
+- `kompass_core.mapping` - 局所マッピングおよび占有グリッド生成。さまざまなレーザーモデルとグリッド解像度設定に対応
+
+- `kompass_core.models` - 差動型、全方向型、アッカーマン型ロボットの運動モデルおよび運動学をサポート。ジオメトリ定義、制御制限、シミュレーション用の状態表現も提供
+
+- `kompass_core.motion_cost` - Python 上で使用可能な軌道評価用コストモデル（衝突確率、リファレンストラッキング、動的・静的障害物対応を含む）
+
+- `kompass_core.performance` - アルゴリズム性能評価用モジュール
+
+- `kompass_core.py_path_tools` - 経路補間と実行ツール
+
+- `kompass_core.simulation` - ロボット運動のシミュレーションと経路の実行可能性評価ツール
+
+- `kompass_core.third_party` - 外部計画ライブラリおよび衝突判定ライブラリとのラッパーと統合：
+
+    - FCL（Flexible Collision Library）
+
+    - OMPL（Open Motion Planning Library）
+
+- `kompass_core.utils` - 汎用ユーティリティ群
+
+## 著作権
+
+本配布物に含まれるコードは、特記がない限り 2024 年 Automatika Robotics に著作権があります。
+Kompass Core は MIT ライセンスのもとで公開されています。詳細は [LICENSE](LICENSE) ファイルをご覧ください。
+
+## コントリビューション
+
+Kompass Core は [Automatika Robotics](https://automatikarobotics.com/) と [Inria](https://inria.fr/) の共同開発プロジェクトです。コミュニティからの貢献は大歓迎です。
+