v0.5.3 Optimization of Depth Rendering (#13)

* v0.5.3 rc1

* update README

* update README

* fix peng-3 link

* docs: improve README and CONTRIBUTING

* docs: update features section in lib.rs and README

* fix: update thiserror

.gitignore

@@ -13,6 +13,8 @@ Cargo.lock
 # MSVC Windows builds of rustc generate these, which store debugging information
 *.pdb
 
+# Rerun
+*.rrd
 
 # Added by cargo
 

CONTRIBUTING.md

@@ -1,41 +1,59 @@
-# Contributing to Peng Project
+# 🤝 Contributing
 
-Thank you for your interest in contributing! Please follow these guidelines.
+We welcome contributions of all kinds! Here's how you can help:
+
+## Ways to Contribute
+
+- 🐛 Bug Reports: Open detailed issues on GitHub
+- 💡 Feature Requests: Share ideas for improvements
+- 🛠️ Code Contributions: Submit pull requests
+- 📚 Documentation: Improve docs and examples
+- 🧪 Testing: Add test cases and improve coverage
 
 ## Getting Started
 
 1. **Fork the repository**: Click the "Fork" button at the top right of the repository page.
-2. **Clone your fork**: 
-    ```sh
-    git clone https://github.com/makeecat/Peng.git
-    ```
+2. **Clone your fork**:
+   ```sh
+   git clone https://github.com/makeecat/Peng.git
+   ```
 3. **Navigate to the project directory**:
-    ```sh
-    cd Peng
-    ```
-4. **Build and run the project**: 
-    ```sh
-    cargo run
-    ```
+   ```sh
+   cd Peng
+   ```
+4. **Build and run the project**:
+   ```sh
+   cargo run
+   ```
 
 ## How to Contribute
 
 1. **Create a new branch**:
-    ```sh
-    git checkout -b feature/your-feature-name
-    ```
-2. **Make your changes**.
+   ```sh
+   git checkout -b feature/your-feature-name
+   ```
+2. **Make your changes**. Add tests for your changes in the inline documentation. Document public APIs
 3. **Test your changes**.
+   ```sh
+   cargo test
+   cargo fmt
+   cargo clippy -- -D warnings
+   ```
 4. **Commit your changes**:
-    ```sh
-    git commit -m "Brief description of your changes"
-    ```
+   ```sh
+   git commit -m "Brief description of your changes"
+   ```
 5. **Push to your fork**:
-    ```sh
-    git push origin feature/your-feature-name
-    ```
+   ```sh
+   git push origin feature/your-feature-name
+   ```
 6. **Create a pull request**: Go to the repository on GitHub and click "New Pull Request".
 
 ## License
 
-By contributing, you agree that your contributions will be licensed under the [GPL-3.0 License](LICENSE).
+By contributing, you agree that your contributions will be licensed under:
+
+- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
+- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project shall be dual licensed as above, without any additional terms or conditions.

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 exclude = ["assets/", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md", "SECURITY.md"]
 name = "peng_quad"
-version = "0.5.2"
+version = "0.5.3"
 edition = "2021"
 rust-version = "1.76"
 authors = ["Yang Zhou <yangzhou.info@gmail.com>"]
@@ -31,7 +31,7 @@ nalgebra = "0.33.0"
 rand = { version = "0.8.5", features = ["rand_chacha"] }
 rand_distr = "0.4.3"
 rerun = "0.19.0"
-thiserror = "1.0.63"
+thiserror = "2.0.0"
 serde = { version = "1.0.209", features = ["derive"] }
 serde_yaml = "0.9.34"
 env_logger = "0.11.5"

README.md

@@ -8,81 +8,96 @@
 [![dependency status](https://deps.rs/repo/github/makeecat/peng/status.svg)](https://deps.rs/repo/github/makeecat/peng)
 [![Gitter](https://img.shields.io/gitter/room/peng/peng)](https://app.gitter.im/#/room/#peng:gitter.im)
 
-## What is Peng
-
-Peng is a minimal quadrotor autonomy framework in Rust. It includes a simulator, controller, and planner, providing a basic framework for simulating quadrotor dynamics and control.
-![demo](https://raw.githubusercontent.com/makeecat/Peng/main/assets/Peng_demo.gif)
-
-## Getting Started
+## 🔍 Overview
+
+Peng is a minimal quadrotor autonomy framework written in Rust that provides real-time dynamics simulation, trajectory planning, and control with modern visualization capabilities.
+
+[![rerun demo](https://raw.githubusercontent.com/makeecat/Peng/main/assets/Peng_demo.gif)](https://rerun.io/viewer?url=https%3A%2F%2Fyangrobotics.com%2Ffiles%2Fpeng_v0.5.3_demo.rrd)
+
+## 🎯 Key Features
+
+- 🚁 **Real-time Simulation**
+  - High-fidelity quadrotor dynamics with configurable parameters
+  - IMU and depth sensor simulation
+  - Optional RK4 integration for accurate dynamics
+- 🎮 **Advanced Control**
+  - PID control for position and attitude with tunable gains
+  - Integral windup prevention
+  - Support for different control frequencies
+- 📍 **Rich Trajectory Planning**
+  - Minimum jerk line trajectory planner
+  - Lissajous curve planner
+  - Circular trajectory planner
+  - Obstacle avoidance planner
+  - Waypoint navigation planner
+  - Landing planner
+- 📊 **Visualization & Debug**
+  - Real-time 3D visualization via rerun.io
+  - Depth map rendering
+  - State telemetry logging
+  - Configurable logging frequencies
+- ⚡ **Performance**
+  - Memory-safe and Efficient Rust implementation
+  - Multi-threaded depth rendering
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- [Rust](https://www.rust-lang.org/tools/install)
+- [rerun-cli](https://rerun.io/docs/getting-started/installing-viewer)
 
 ### Installation from Crates.io
 
 ```bash
-cargo install rerun-cli # ensure you installed rerun-cli>=0.19.0 by checking rerun --version
+# Install rerun-cli (ensure version >= 0.19.0)
+cargo install rerun-cli
 cargo install peng_quad
 peng_quad config/quad.yaml
 ```
 
 ### Installation from Source
 
 ```bash
+# Install rerun-cli (ensure version >= 0.19.0)
 cargo install rerun-cli
-git clone https://github.com/makeecat/Peng.git && cd Peng
+git clone https://github.com/makeecat/Peng.git
+cd Peng
 cargo run --release config/quad.yaml
 ```
 
-You can configure the simulation through config file, see [quad.yaml](config/quad.yaml) for example.
-
-Please follow [rerun troubleshooting](https://rerun.io/docs/getting-started/troubleshooting) if you are using Linux or WSL2.
-
-## Overview
-
-### Quadrotor Simulator
-
-Simulates realistic quadrotor dynamics with properties like position, velocity, orientation, angular velocity, mass, and inertia. Includes methods for updating dynamics with control inputs and simulating IMU readings and Depth map rendering.
-
-### PID Controller
+## ⚙️ Configuration
 
-Controls position and attitude with configurable gains for proportional, integral, and derivative terms. Handles both position and attitude control.
+- You can configure the simulation through config file, see [quad.yaml](config/quad.yaml) for example.
+- Configure simulation parameters such as mass, inertia, and control gains.
+- Configure control parameters such as PID gains.
+- Configure trajectory planner parameters such as waypoints, obstacles, and trajectory type.
+- Configure visualization parameters such as camera intrinsics and depth rendering.
 
-### Trajectory Planners
+## 🔧 Troubleshooting
 
-Includes multiple planners:
+If you encountered any issue with the rerun:
 
-- Hover Planner
-- Minimum Jerk Line Planner
-- Lissajous Curve Planner
-- Circular Trajectory Planner
-- Landing Planner
-- Obstacle Avoidance Planner
-- Waypoint Planner
+1. Verify rerun-cli version matches rerun version in [Cargo.toml](https://github.com/makeecat/Peng/blob/main/Cargo.toml):
 
-### Obstacle Simulation
-
-Simulates moving obstacles in the environment, with collision detection and avoidance capabilities based on potential field.
-
-### Data Logging and Visualization
+```bash
+rerun --version
+```
 
-Logs comprehensive simulation data including quadrotor state, desired positions, IMU readings, and depth map rendering. Visualizes the simulation using the rerun library.
+2. For Linux/WSL2 users, consult the [rerun troubleshooting](https://rerun.io/docs/getting-started/troubleshooting).
 
-## Features
+## 🗺️ Roadmap
 
-- Realistic quadrotor dynamics simulation
-- IMU sensor simulation with configurable noise parameters
-- Multiple trajectory planners for diverse flight patterns
-- PID controller for position and attitude control
-- Obstacle generation and avoidance
-- Depth map rendering based on primitives
-- Integration with rerun for real-time visualization
+- [ ] Wind field and environmental effects
+- [ ] Motor dynamics simulation
+- [ ] Multi-quadrotor simulation
+- [ ] Model Predictive Control (MPC)
 
-## TODO
+## 🤝 Contributing
 
-- [ ] Environment Effect simulation such as wind field
-- [ ] Add motor speed simulation
-- [ ] Multi-quadrotor simulation
-- [ ] MPC controller
+We welcome contributions of all kinds! Please check out the [Contributing Guidelines](CONTRIBUTING.md) for more details.
 
-## License
+## 📄 License
 
 Peng is free, open source and permissively licensed!
 Except where noted (below and/or in individual files), all code in this repository is dual-licensed under either:
@@ -93,21 +108,17 @@ Except where noted (below and/or in individual files), all code in this reposito
 
 This means you can select the license you prefer!
 
-## Why call it Peng?
-
-Peng (traditional Chinese: 鵬; simplified Chinese: 鹏; pinyin: péng; Wade–Giles: p'eng) or Dapeng (大鵬) is a giant bird that transforms from a Kun (鯤; 鲲; kūn; k'un) giant fish in Chinese mythology.
-
-The pipeline is designed to be minimal and for educational purpose.
-We chose the name Peng because our pipeline is flexible and can transform to suit different needs, just like the mythical bird.
+## 🐦 Why call it Peng?
 
-Reference: https://en.wikipedia.org/wiki/Peng_(mythology)
+Peng (鵬/鹏, péng), or Dapeng (大鵬), represents a mythical Chinese bird that transforms from a giant Kun (鯤/鲲) fish. This name reflects our framework's adaptability and transformative capabilities.
 
-## Blog posts
+## 📝 Blog Posts
 
 - [Peng #1: Minimal quadrotor pipeline in Rust](https://yangrobotics.com/peng-1-minimal-quadrotor-pipeline-in-rust)
 - [Peng #2: Error Handling, Configuration System and Obstacle Avoidance Planner](https://yangrobotics.com/peng-2-error-handling-configuration-system-and-obstacle-avoidance-planner)
+- [Peng #3: Optimization of Depth Rendering and RK4-based Dynamics Update](https://yangrobotics.com/peng-3-optimization-of-depth-rendering-and-rk4-based-dynamics-update)
 
-## Citation
+## 📚 Citation
 
 If you use this project in your research or work, please cite it as follows:
 

src/lib.rs

@@ -1,13 +1,39 @@
-//! # Quadrotor Simulation
-//! This crate provides a comprehensive simulation environment for quadrotor drones.
-//! It includes models for quadrotor dynamics, IMU simulation, various trajectory planners,
-//! and a PID controller for position and attitude control.
-//! ## Features
-//! - Realistic quadrotor dynamics simulation
-//! - IMU sensor simulation with configurable noise parameters
-//! - Multiple trajectory planners including hover, minimum jerk, Lissajous curves, and circular paths
-//! - PID controller for position and attitude control
-//! - Integration with the `rerun` crate for visualization
+//! # Peng - A Minimal Quadrotor Autonomy Framework
+//!
+//! A high-performance quadrotor autonomy framework written in Rust that provides
+//! real-time dynamics simulation, trajectory planning, and control with modern
+//! visualization capabilities.
+//!
+//! # Features
+//!
+//! ## Real-time Simulation
+//! - High-fidelity quadrotor dynamics with configurable parameters
+//! - IMU and depth sensor simulation
+//! - Optional RK4 integration for accurate dynamics
+//!
+//! ## Advanced Control
+//! - PID control for position and attitude with tunable gains
+//! - Integral windup prevention
+//! - Support for different control frequencies
+//!
+//! ## Rich Trajectory Planning
+//! - Minimum jerk line trajectory planner
+//! - Lissajous curve planner
+//! - Circular trajectory planner
+//! - Obstacle avoidance planner
+//! - Waypoint navigation planner
+//! - Landing planner
+//!
+//! ## Visualization & Debug
+//! - Real-time 3D visualization via rerun.io
+//! - Depth map rendering
+//! - State telemetry logging
+//! - Configurable logging frequencies
+//!
+//! ## Performance
+//! - Memory-safe and Efficient Rust implementation
+//! - Multi-threaded depth rendering
+//!
 //! ## Example
 //! ```
 //! use nalgebra::Vector3;