Force Fusion

A real-time PyQt dashboard visualizing vehicle dynamics and normal-force distribution.

#Vehicle Dynamics   #Normal-force Estimation   #PyQt   #3D Visualization

---

demo.mp4

🚀 Getting Started

It is recommended to use uv to create a virtual environment and pip install the following package.

pip install force-fusion

To run the application, simply type:

force-fusion
# or
force-fusion --help

---

👨‍💻 Development Setup

1. Clone the repository and navigate to project folder:

   git clone https://github.com/Sang-Buster/Force-Fusion
   cd Force-Fusion

2. Install uv first:

   # macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh

   # Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Create a virtual environment at Force-Fusion/.venv/:

   uv venv --python 3.10

4. Activate the virtual environment:

   # macOS/Linux
   source .venv/bin/activate

   # Windows
   .venv\Scripts\activate

5. Install the required packages:

   uv pip install -e .

6. Set up environment variables:

   # Copy the example environment file
   cp .env.example .env

   • You can get a MAPBOX_TOKEN by signing up at https://www.mapbox.com/
   • Update the CSV_PATH if you want to use a custom database file
   • Update the WS_HOST if you want to use a custom websocket host
   • Update the WS_PORT if you want to use a custom websocket port
   • Update the WS_RECONNECT_INTERVAL if you want to use a custom websocket reconnect interval
   • Modify more variables in .env as needed

7. Install ruff and pre-commit:

   uv pip install ruff pre-commit

   • ruff is a super fast Python linter and formatter.
   • pre-commit helps maintain code quality by running automated checks before commits are made.

8. Install git hooks:

   pre-commit install --hook-type commit-msg --hook-type pre-commit --hook-type pre-push

   These hooks perform different checks at various stages:

   • commit-msg: Ensures commit messages follow the conventional format
   • pre-commit: Runs Ruff linting and formatting checks before each commit
   • pre-push: Performs final validation before pushing to remote

9. Code Linting:

   ruff check
   ruff check --fix
   ruff check --select I
   ruff check --select I --fix
   ruff format

10. Run the application:

uv run src/force_fusion/app.py

---

📝 File Structure

📂Force-Fusion
 ┣ 📂src                         // Source Code
 ┃ ┗ 📦force_fusion                  // Python package
 ┃ ┃ ┣ 📂cli                             // Command Line Interface Directory
 ┃ ┃ ┃ ┣ 📄cli.py
 ┃ ┃ ┃ ┣ 📄env.py
 ┃ ┃ ┃ ┣ 📄test.py
 ┃ ┃ ┣ 📂resources                       // Static Resources Directory
 ┃ ┃ ┃ ┣ 📄car_back.svg
 ┃ ┃ ┃ ┣ 📄car_side.svg
 ┃ ┃ ┃ ┣ 📄demo.mp4
 ┃ ┃ ┃ ┣ 📄favicon.png
 ┃ ┃ ┃ ┗ 📄styles.qss
 ┃ ┃ ┣ 📂utils                           // Utility Directory
 ┃ ┃ ┃ ┣ 📄env_utils.py
 ┃ ┃ ┃ ┣ 📄geo_utils.py
 ┃ ┃ ┃ ┣ 📄test_utils.py
 ┃ ┃ ┃ ┣ 📄websocket_client_test.py
 ┃ ┃ ┃ ┗ 📄websocket_server.py
 ┃ ┃ ┣ 📂widgets                         // Widgets Directory  
 ┃ ┃ ┃ ┣ 📄attitude.py
 ┃ ┃ ┃ ┣ 📄gg_diagram.py
 ┃ ┃ ┃ ┣ 📄heading.py
 ┃ ┃ ┃ ┣ 📄mapbox_view.py
 ┃ ┃ ┃ ┣ 📄minimap.py
 ┃ ┃ ┃ ┣ 📄speedometer.py
 ┃ ┃ ┃ ┗ 📄tire_force.py
 ┃ ┃ ┣ 📄app.py
 ┃ ┃ ┣ 📄config.py
 ┃ ┃ ┣ 📄controller.py
 ┃ ┃ ┣ 📄sensors.py
 ┃ ┃ ┗ 📄ui_main_window.py
 ┣ 📄.env.example                // Template for environment variables
 ┣ 📄.gitignore                  // Git ignore patterns (env, cache, database)
 ┣ 📄.pre-commit-config.yaml     // Pre-commit hooks (ruff, commit message)
 ┣ 📄.pre-commit_msg_template.py // Commit message format validator
 ┣ 📄.python-version             // Python version
 ┣ 📄LICENSE                     // MIT License
 ┣ 📄README.md                   // Project documentation
 ┣ 📄pyproject.toml              // Project configuration
 ┗ 📄uv.lock                     // Lock file