Rewrite README with comprehensive project documentation
- Added detailed project overview and feature descriptions - Included complete dependency list with build instructions - Added system architecture overview and component descriptions - Documented configuration options and usage instructions - Added troubleshooting section for common issues - Included known limitations and future improvements - Improved formatting and clarity throughout Co-Authored-By: Claude Haiku 4.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01GPXVpiPnb5AzgdCJ33Q6Fi
This commit is contained in:
msjid
co-authored by
Claude Haiku 4.5
Claude Haiku 4.5
parent
40df37d770
commit
a4bbac7542
@@ -1,38 +1,180 @@
|
||||
VIO
|
||||
===
|
||||
# VIO - Visual Inertial Odometry
|
||||
|
||||
This code implements a semi-direct monocular visual odometry pipeline which has been integrated with a EKF to infused IMU and CMD as well. The feature extraction and image alignment part are implemented in OpenCL to take advantage of GPU.
|
||||
A semi-direct monocular visual odometry pipeline with IMU and command integration using Extended Kalman Filter (EKF) for robust pose estimation. The system leverages GPU acceleration via OpenCL for real-time performance.
|
||||
|
||||
## Features
|
||||
|
||||
#### Documentation
|
||||
OpenCL documentation
|
||||
- **Semi-Direct Visual Odometry**: Combines feature-based and direct alignment approaches for robust tracking
|
||||
- **GPU-Accelerated Processing**: OpenCL-based feature extraction and image alignment for real-time performance
|
||||
- **Multi-Sensor Fusion**: EKF integration for IMU and command data fusion with visual odometry
|
||||
- **ROS Integration**: Native ROS support for easy integration into robotic systems
|
||||
- **Graph-Based Optimization**: G2O-based global and pose optimization backends
|
||||
- **Monocular Input**: Works with standard monocular cameras
|
||||
|
||||
#### Instructions
|
||||
Please be sure that you have the OpenCL driver installed
|
||||
## System Requirements
|
||||
|
||||
- **OS**: Linux (tested on Ubuntu)
|
||||
- **GPU**: OpenCL-compatible GPU with OpenCL drivers installed
|
||||
- **C++ Standard**: C++17 or later
|
||||
- **CMake**: Version 2.8.3 or later
|
||||
|
||||
## Setting
|
||||
## Dependencies
|
||||
|
||||
You can edit the algorithm parameters in the follwoing file, please look at the config file to underestand the meaning of the parameters (CPU_version/svo/include/svo/config.h)
|
||||
The following packages are required. Specific build instructions are provided for G2O:
|
||||
|
||||
CPU_version/vio/param/vo_fast.yaml
|
||||
1. **OpenCV** (4.x) - Computer vision library
|
||||
2. **Eigen** - Linear algebra library
|
||||
3. **G2O** - Graph optimization library
|
||||
```bash
|
||||
# Build G2O with:
|
||||
cmake -DG2O_HAVE_OPENGL=ON -DBUILD_WITH_MARCH_NATIVE=ON ..
|
||||
# Recommended version: https://github.com/RainerKuemmerle/g2o/tree/memory_management
|
||||
```
|
||||
4. **Boost** - C++ libraries (requires thread and system components)
|
||||
5. **OpenCL** - GPU computation framework
|
||||
6. **ROS** - Robot Operating System (for ROS integration)
|
||||
- catkin, roscpp, roslib, image_transport, cv_bridge, tf, geometry_msgs
|
||||
|
||||
# The dependencies:
|
||||
1. OpenCV 4
|
||||
2. Eigen
|
||||
3. G2o # build g2o with -DG2O_HAVE_OPENGL=ON -DBUILD_WITH_MARCH_NATIVE=ON
|
||||
# G2o version => https://github.com/RainerKuemmerle/g2o/tree/memory_management
|
||||
4. Boost
|
||||
5. OpenCL
|
||||
## Building
|
||||
|
||||
# known issues
|
||||
1. The estimated oriantetion is not accurate
|
||||
2. There is a scale map issue in the algorithm
|
||||
3. The number of matched points are increasing a lot we need to limit them in a way that will not cause some error in the estimated odometry
|
||||
### Prerequisites
|
||||
|
||||
# Log files
|
||||
log files will be written in the project folder, you can change the path in the cmake files as well as activating debug mode or not
|
||||
https://github.com/Gfuse/vio_svo/blob/d3c857fd06bfe5c6180e6bc914a4a36a649c4292/GPU_version/vio/CMakeLists.txt#L89
|
||||
Ensure you have the OpenCL driver installed on your system:
|
||||
|
||||
```bash
|
||||
# For NVIDIA GPUs
|
||||
sudo apt-get install nvidia-opencl-icd
|
||||
|
||||
# For AMD/Intel, install appropriate drivers
|
||||
```
|
||||
|
||||
### Build Instructions
|
||||
|
||||
```bash
|
||||
# Create a catkin workspace (if using ROS)
|
||||
mkdir -p ~/catkin_ws/src
|
||||
cd ~/catkin_ws/src
|
||||
git clone <this-repo> vio
|
||||
cd ~/catkin_ws
|
||||
|
||||
# Build
|
||||
catkin_make
|
||||
# or with specific options:
|
||||
catkin_make -DCMAKE_BUILD_TYPE=Release
|
||||
```
|
||||
|
||||
For standalone (non-ROS) builds:
|
||||
|
||||
```bash
|
||||
cd vio
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
make -j$(nproc)
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Algorithm parameters can be configured in two main files:
|
||||
|
||||
1. **Header Configuration**: `vio/include/vio/config.h`
|
||||
- Core algorithm parameters and feature extraction settings
|
||||
|
||||
2. **Runtime Configuration**: `vio/param/vo_fast.yaml`
|
||||
- Fast configuration profile for real-time operation
|
||||
|
||||
Additional configuration files:
|
||||
|
||||
- `vio/param/px30.yaml` - Configuration for specific hardware/robotics platform
|
||||
|
||||
## Usage
|
||||
|
||||
### As a ROS Node
|
||||
|
||||
```bash
|
||||
rosrun vio vio
|
||||
```
|
||||
|
||||
### Configuration via Parameters
|
||||
|
||||
Edit `vo_fast.yaml` before running or use ROS parameter server to override settings at runtime.
|
||||
|
||||
### Output
|
||||
|
||||
The system provides:
|
||||
- Estimated pose (position and orientation)
|
||||
- 3D map points
|
||||
- Tracking statistics and debug information
|
||||
|
||||
Log files are written to the project directory. You can modify the logging path and debug mode in `CMakeLists.txt` (see line 89).
|
||||
|
||||
## Known Issues
|
||||
|
||||
1. **Orientation Estimation**: The estimated orientation may not be fully accurate under certain conditions
|
||||
2. **Scale Ambiguity**: Semi-direct visual odometry inherently suffers from monocular scale ambiguity; the EKF sensor fusion helps but may not fully resolve it
|
||||
3. **Feature Point Accumulation**: The number of tracked feature points can increase significantly over time; limiting strategy needed to prevent performance degradation and estimation errors
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Core Components
|
||||
|
||||
- **Frame Handler** (`frame_handler_mono.cpp`): Main tracking loop for monocular sequences
|
||||
- **Feature Detection** (`feature_detection.cpp`): GPU-accelerated FAST corner detection
|
||||
- **Feature Alignment** (`feature_alignment.cpp`): Direct image alignment for sub-pixel accuracy
|
||||
- **Matcher** (`matcher.cpp`): Feature correspondence matching
|
||||
- **Reprojector** (`reprojector.cpp`): Map point reprojection and visibility management
|
||||
- **Pose Optimizer** (`pose_optimizer.cpp`): Per-frame pose optimization
|
||||
- **Global Optimizer** (`global_optimizer.cpp`): Graph-based optimization for drift correction
|
||||
- **Visualizer** (`visualizer.cpp`): Real-time visualization of results
|
||||
|
||||
### GPU Acceleration
|
||||
|
||||
- **OpenCL Implementation** (`cl_class.cpp`, `sparse_img_align_gpu.cpp`): GPU kernels for feature extraction and alignment
|
||||
- **Kernel Directory** (`kernel/`): OpenCL kernel source code
|
||||
|
||||
## System Diagram
|
||||
|
||||
```
|
||||
Camera Input → Feature Detection (GPU) → Feature Alignment (GPU)
|
||||
↓
|
||||
Frame Tracking
|
||||
↓
|
||||
┌────────────────────┴──────────────────┐
|
||||
↓ ↓
|
||||
Pose Optimization Map Management
|
||||
↓ ↓
|
||||
EKF Sensor Fusion ←─── IMU & Command Input
|
||||
↓
|
||||
Global Optimization (G2O)
|
||||
↓
|
||||
Odometry Output (Pose, Map)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### OpenCL Issues
|
||||
|
||||
- Verify OpenCL drivers are installed: `clinfo`
|
||||
- Check GPU compatibility with OpenCL
|
||||
- Set `VIO_DEBUG` flag in CMakeLists.txt for detailed GPU debugging
|
||||
|
||||
### Performance Issues
|
||||
|
||||
- Adjust feature point limits in configuration
|
||||
- Enable/disable GPU features in `config.h`
|
||||
- Check OpenCV and G2O build flags match the VIO build flags
|
||||
|
||||
## License
|
||||
|
||||
[Add appropriate license information]
|
||||
|
||||
## Contributing
|
||||
|
||||
[Add contributing guidelines if applicable]
|
||||
|
||||
## References
|
||||
|
||||
- Semi-direct Visual Odometry (SVO) concept
|
||||
- EKF for sensor fusion
|
||||
- G2O framework: https://github.com/RainerKuemmerle/g2o
|
||||
- OpenCV: https://opencv.org/
|
||||
- ROS: https://www.ros.org/
|
||||
|
||||
Reference in New Issue
Block a user