From 12f73de1741940ed56dbf99a979c2bd1c464e6c3 Mon Sep 17 00:00:00 2001 From: Yang Zhou Date: Wed, 6 Nov 2024 17:50:27 -0500 Subject: [PATCH 1/7] v0.5.3 rc1 --- .gitignore | 2 ++ Cargo.toml | 2 +- README.md | 3 ++- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 04b7fe06..ca0f8214 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,8 @@ Cargo.lock # MSVC Windows builds of rustc generate these, which store debugging information *.pdb +# Rerun +*.rrd # Added by cargo diff --git a/Cargo.toml b/Cargo.toml index 3cfe80bf..652b1d27 100644 --- a/Cargo.toml +++ b/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 "] diff --git a/README.md b/README.md index bbbeae71..8a43fd6b 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ ## 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) +[![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) ## Getting Started @@ -106,6 +106,7 @@ Reference: https://en.wikipedia.org/wiki/Peng_(mythology) - [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 of A Quadrotor Autonomy Pipeline in Rust](https://yangrobotics.com/peng-3-optimization-of-depth-rendering-and-rk4-based-dynamics-update-of-a-quadrotor-autonomy-pipeline) ## Citation From 84edb063b8300acb6770b813aa13e27526af6968 Mon Sep 17 00:00:00 2001 From: Yang Zhou Date: Wed, 6 Nov 2024 18:05:06 -0500 Subject: [PATCH 2/7] update README --- README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8a43fd6b..57527680 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,8 @@ Peng is a minimal quadrotor autonomy framework in Rust. It includes a simulator, ### Installation from Crates.io ```bash -cargo install rerun-cli # ensure you installed rerun-cli>=0.19.0 by checking rerun --version +cargo install rerun-cli +# ensure you installed rerun-cli>=0.19.0 by checking rerun --version cargo install peng_quad peng_quad config/quad.yaml ``` @@ -33,7 +34,15 @@ 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. +If you encountered any issue with the rerun: + +1. Please ensure you installed the same version of rerun-cli of the rerun version in [Cargo.toml](https://github.com/makeecat/Peng/blob/main/Cargo.toml) by checking + +```bash +rerun --version +``` + +2. Please follow [rerun troubleshooting](https://rerun.io/docs/getting-started/troubleshooting) if you are using Linux or WSL2. ## Overview From 06581c36733b287a829569fb33f4906adfdeed64 Mon Sep 17 00:00:00 2001 From: Yang Zhou Date: Wed, 6 Nov 2024 18:06:18 -0500 Subject: [PATCH 3/7] update README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 57527680..d9d3dfed 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ You can configure the simulation through config file, see [quad.yaml](config/qua If you encountered any issue with the rerun: -1. Please ensure you installed the same version of rerun-cli of the rerun version in [Cargo.toml](https://github.com/makeecat/Peng/blob/main/Cargo.toml) by checking +1. Please ensure you installed the same version of rerun-cli by checking the rerun version in [Cargo.toml](https://github.com/makeecat/Peng/blob/main/Cargo.toml): ```bash rerun --version From db291831acc4226985e91eb8562be14787a2991e Mon Sep 17 00:00:00 2001 From: Yang Zhou Date: Wed, 6 Nov 2024 20:59:11 -0500 Subject: [PATCH 4/7] fix peng-3 link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d9d3dfed..92e731c2 100644 --- a/README.md +++ b/README.md @@ -115,7 +115,7 @@ Reference: https://en.wikipedia.org/wiki/Peng_(mythology) - [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 of A Quadrotor Autonomy Pipeline in Rust](https://yangrobotics.com/peng-3-optimization-of-depth-rendering-and-rk4-based-dynamics-update-of-a-quadrotor-autonomy-pipeline) +- [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 From 1a33c8b2d9b5f9a861f3b0437ca52317ceb43f88 Mon Sep 17 00:00:00 2001 From: Yang Zhou Date: Wed, 6 Nov 2024 22:01:19 -0500 Subject: [PATCH 5/7] docs: improve README and CONTRIBUTING --- CONTRIBUTING.md | 66 +++++++++++++++++---------- README.md | 118 +++++++++++++++++++++++------------------------- 2 files changed, 99 insertions(+), 85 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2fb7d3ff..9c95be8a 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index 92e731c2..0841eb59 100644 --- a/README.md +++ b/README.md @@ -8,18 +8,45 @@ [![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 +## ๐Ÿ” 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. -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. [![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) -## Getting Started +## ๐ŸŽฏ 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 +- ๐Ÿ“ **Rich Trajectory Planning** + - Minimum jerk line trajectories + - Lissajous curves + - Circular paths + - Obstacle avoidance + - Waypoint navigation +- ๐Ÿ“Š **Visualization & Debug** + - Real-time 3D visualization via rerun.io + - Depth map rendering + - State telemetry logging +- โšก **Performance** + - Multi-threaded depth rendering + - Memory-safe and Efficient Rust implementation + +## ๐Ÿš€ 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 +# Install rerun-cli (ensure version >= 0.19.0) cargo install rerun-cli -# ensure you installed rerun-cli>=0.19.0 by checking rerun --version cargo install peng_quad peng_quad config/quad.yaml ``` @@ -27,71 +54,45 @@ 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. +## โš™๏ธ Configuration + +- 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. + +## ๐Ÿ”ง Troubleshooting If you encountered any issue with the rerun: -1. Please ensure you installed the same version of rerun-cli by checking the rerun version in [Cargo.toml](https://github.com/makeecat/Peng/blob/main/Cargo.toml): +1. Verify rerun-cli version matches rerun version in [Cargo.toml](https://github.com/makeecat/Peng/blob/main/Cargo.toml): ```bash rerun --version ``` -2. 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 - -Controls position and attitude with configurable gains for proportional, integral, and derivative terms. Handles both position and attitude control. - -### Trajectory Planners - -Includes multiple planners: +2. For Linux/WSL2 users, consult the [rerun troubleshooting](https://rerun.io/docs/getting-started/troubleshooting). -- Hover Planner -- Minimum Jerk Line Planner -- Lissajous Curve Planner -- Circular Trajectory Planner -- Landing Planner -- Obstacle Avoidance Planner -- Waypoint Planner +## ๐Ÿ—บ๏ธ Roadmap -### Obstacle Simulation - -Simulates moving obstacles in the environment, with collision detection and avoidance capabilities based on potential field. - -### Data Logging and Visualization - -Logs comprehensive simulation data including quadrotor state, desired positions, IMU readings, and depth map rendering. Visualizes the simulation using the rerun library. - -## Features - -- 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: @@ -102,22 +103,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: From dc3d7e7a2ef7069d9cc0a2d8d6398aa5af8755b4 Mon Sep 17 00:00:00 2001 From: Yang Zhou Date: Wed, 6 Nov 2024 22:17:00 -0500 Subject: [PATCH 6/7] docs: update features section in lib.rs and README --- README.md | 19 ++++++++++++------- src/lib.rs | 46 ++++++++++++++++++++++++++++++++++++---------- 2 files changed, 48 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 0841eb59..bd978351 100644 --- a/README.md +++ b/README.md @@ -20,20 +20,25 @@ Peng is a minimal quadrotor autonomy framework written in Rust that provides rea - 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 +- ๐ŸŽฎ **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 trajectories - - Lissajous curves - - Circular paths - - Obstacle avoidance - - Waypoint navigation + - 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** - - Multi-threaded depth rendering - Memory-safe and Efficient Rust implementation + - Multi-threaded depth rendering ## ๐Ÿš€ Getting Started diff --git a/src/lib.rs b/src/lib.rs index 138f023c..bf495ca0 100644 --- a/src/lib.rs +++ b/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; From 845ee378ac93b6fabcd492a1158b9ada355eb13c Mon Sep 17 00:00:00 2001 From: Yang Zhou Date: Wed, 6 Nov 2024 22:24:08 -0500 Subject: [PATCH 7/7] fix: update thiserror --- Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Cargo.toml b/Cargo.toml index 652b1d27..d575ce02 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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"