TaichiGAME

<div align="center"> <!-- Title: --> <img src="https://raw.githubusercontent.com/maksyuki/TaichiGAME-res/main/logo.png" /> <br /> <br /> <a href="https://github.com/maksyuki/TaichiGAME/actions"> <img src="https://img.shields.io/github/workflow/status/maksyuki/TaichiGAME/unit-test/main?label=unit-test&logo=github&style=flat-square"> </a> <a href="https://app.codecov.io/gh/maksyuki/TaichiGAME/"> <img src="https://img.shields.io/codecov/c/github/maksyuki/TaichiGAME/main?logo=codecov&style=flat-square"> </a> <a href="https://github.com/maksyuki/TaichiGAME"> <img src="https://img.shields.io/pypi/v/TaichiGAME?logo=pypi&style=flat-square"> </a> <a href="https://github.com/maksyuki/TaichiGAME"> <img src="https://img.shields.io/pypi/pyversions/TaichiGAME?logo=python&style=flat-square"> </a> <!-- Second row: --> <br> <a href="https://github.com/maksyuki/TaichiGAME"> <img src="https://img.shields.io/github/license/maksyuki/TaichiGAME?color=brightgreen&logo=github&style=flat-square"> </a> <!-- <a href="https://github.com/maksyuki/TaichiGAME"> <img src="https://img.shields.io/tokei/lines/github/maksyuki/TaichiGAME?style=flat-square"> </a> --> <a href="https://github.com/maksyuki/TaichiGAME"> <img src="https://img.shields.io/badge/total%20lines-12k-blue?style=flat-square"> </a> <a href="https://github.com/google/yapf"> <img src="https://img.shields.io/badge/code%20style-yapf%20mypy-red?style=flat-square"> </a> <a href="https://github.com/PyCQA"> <img src="https://img.shields.io/badge/static%20checker-pylint%20pycodestyle-red?style=flat-square"> </a> <a href="https://github.com/maksyuki/TaichiGAME/blob/main/CONTRIBUTING.md"> <img src="https://img.shields.io/badge/contribution-welcome-brightgreen?style=flat-square"> </a> <!-- Short description: --> <h1></h1> </div>

Overview

TaichiGAME is aim to become a lightweight simulation engine in motion planning and control research fields. And it is written in python and taichi, which combines the traditional numerical methods for solving rigid dynamics equations, model parameters derivation, with parallel implementation capabilites in order to maximize scientists' productivity.

Motivation

I am a postgraduate in school of astronautics and major in aerospace robot guidance, navigation and control. During my first year, I took a class on advanced control theory and was taught many different control algorithms for estimating dynamic model, fitting state curves and so on.

When I carried out a research on asteroid rover motion planning supported by NFSC(National Natural Science Foundation of China), I spent lots of time on learning c++ for writing parallel program to solve complex rigid body dynamics equations. To be honest, achieving all of the details, especially some c++ advanced features, made me thoroughly exhausted. I could not just focus on the algorithms and built rapid prototype to verify it. I thought others feel the same way. After that, I searched online and found no open source, scientific-oriented, out-of-the-box tools or framework to execute such high performance rigid body motion computing. In that case, why not build one? The result of that desire is this project.

Feature

NOTE: Due to my research is still under review and revise, I could not release all results now. At present, I only release the initial physics engine component of TaichiGAME. So I only introduce physics engine component now. In the first half of 2022, I will release other components of TaichiGAME.

To implement the physics engine, I refer to the Physics2D (c++, MIT License) project, and rewrite entire content of it into python with taichi and add more unit tests. The following architecture chart illustrates the basic features:

<p align="center"> <img src="https://raw.githubusercontent.com/maksyuki/TaichiGAME-res/main/arch.drawio.svg"/> <p align="center"> <em>The basic features of physics component in TaichiGAME</em> <br> <em>(open it in a new window to browse the larger picture)</em> </p> </p>

What is missing

First, the physics engine component is under alpha phase, so it is lack of stability and reliability. Second, to narrow the development period, I use the easy-to-implement numberical methods, that makes the performance suffer a bit.

Requirements

1. python>=3.7, <=3.9, because:

   • use from __future__ import annotations to postpone evaluation of annotations (python3.7+ intro)
   • taichi supports the highest version of python is python3.9

2. taichi>=0.8.0, because:

   • support taichi's new features
   • now TaichiGAME doesn't use the new GGUI (taichi0.8+ intro), so maybe you can use lower version taichi(such as taichi0.7+).
   • NOTE: some TaichiGAME's API is based on specific taichi features. In views of the rapid development of taichi, I don't have much enery and time to maintain TaichiGAME to adapt or be compatiable to multiple different major version of taichi. It can make TaichiGAME too verbose. So I decide to ONLY maintain TaichiGAME to adapt to current major verion plus one latest previous major verion of taichi. For now, because a major version of taichi has not been released yet, I decide to CHANGE the 'major version' of previous policy into 'minor version'. Specifically, I develop and test all features of TaichiGAME in taichi0.8+ , and ONLY maintain compatible version of TaichiGAME to taichi0.7+, the TaichiGAME based on taichi<0.7+ will no longer be maintained.

Install

Installation is simple, you can just type the following command in shell or cmd terminal(Recommend).

$ python3 -m pip install TaichiGAME

After installation, type following command to run the build-in example testbed.py.

$ python3 -m TaichiGAME example testbed

You can type python3 -m TaichiGAME -h and python3 -m TaichiGAME example -h to get detail command line parameters usage. This cli module refers to taichi main module.

NOTE: Recommand use venv to isolate test environment from system directories, you can get more details from Creation of virtual environments.

Another method is git clone this repo, pip install dependencies, and then run the testbed.py from package directly.

$ git clone https://github.com/maksyuki/TaichiGAME.git
$ cd TaichiGAME/
$ python3 -m pip install -r requirements.txt
$ cd TaichiGAME/ # necessary, run main.py in project root path can trigger module import error
$ python3 main.py example testbed

NOTE: When running code, you maybe notice terminal print some informations like [Taichi] version 0.8.7, llvm 10.0.0, commit 1c3c705a, osx, python 3.8.8. I have tested TaichiGAME under taichi>=0.7. Your output maybe different from mine, but it doesn't matter.

Testbed keyborad and mouse control

• Press esc to exit the gui, space to pause simulation.
• Press left arrow or right arrow key to switch different frames.
• Press and hold right mouse button to move viewport position. Roll mouse wheel to zoom in or out the viewport.
• Press and hold left mouse button to apply a mouse joint constraint to selected shape from the start point(mouse press position) to end point(current mouse hold position).
• | keyboard button | function | keyboard button | function | keyboard button | function | | :-------------: | :------: | :-------------: | :------: | :-------------: | :------: | | q | toggle frame visibility | w | toggle AABB visibility | e| toggle joint visibility| | r | toggle body visibility | t | toggle axis visibility | a | toggle dbvh visibility | | s | toggle dbvt visibility | d | toggle grid visibility | f | toggle rotation line visibility | | g | toggle center visibility | z | toggle contact visibility |

Testbed simulation result

1. dbvt query: this frame is aim to show the dbvt's ability to accelerate the broad phase query of collision. The red rectangle represents the query region, yellow rectangles represent the query results(AABB of the shape).

<p align="center"> <img src="https://raw.githubusercontent.com/maksyuki/TaichiGAME-res/main/dbvt_query.gif"/> <p align="center"> <em>The dbvt query with smooth viewport zoom in</em> </p> </p>

2. raycast: this frame casts a ray in given direction. You can move the cast direction by mouse, and the cast shapes are rendered in cyan color.

<p align="center"> <img src="https://raw.githubusercontent.com/maksyuki/TaichiGAME-res/main/raycast.gif"/> <p align="center"> <em>The raycast from the origin in given direction </em> </p> </p>

3. bitmask: this frame shows two objects, a square and a ground, are with same bitmask property can contact with each other. In addition, the yellow rectangles represent the real time update result of dbvt.

<p align="center"> <img src="https://raw.githubusercontent.com/maksyuki/TaichiGAME-res/main/bitmask.gif"/> <p align="center"> <em>Three squares contact with ground</em> </p> </p>

4. collision: those frames show multiple collision examples. First one is a simple collision, second frame shows eight balls hit the ground with different restitution increased from left to right, the last one shows the three squares slide down from slopes with different friction coefficient.

<p align="center"> <img src="https://raw.githubusercontent.com/maksyuki/TaichiGAME-res/main/collision_simple.gif"/> <p align="center"> <em>A capsule hit the ground</em> </p> </p> <p align="center"> <img src="https://raw.githubusercontent.com/maksyuki/TaichiGAME-res/main/collision_restit.gif"/> <p align="center"> <em>Eight balls hit the ground with different restitut