bots2d
bots2d copied to clipboard
Bots2D is a C++ framework for simulating robotics in 2D that provides boilerplate code and robotics assets to help you quickly get started.
Bots2D
Bots2D is a C++ framework for simulating robotics in 2D, which provides you with boilerplate and robotics assets to help you quickly set up your simulation. You can read more about it here.
![](https://github.com/artfulbytes/bots2d/raw/master/docs/images/sumobot_feature.gif)
![](https://github.com/artfulbytes/bots2d/raw/master/docs/images/line_follower_feature.png)
Background
There are several projects out there for simulating robotics (Gazebo, Webots, V-REP, AirSim, etc.). These have advanced toolsets and are great at realistic simulations, but come at the cost of a lot of overhead, which is tedious and overkill for simpler simulations.
Despite 2D simulators being useful and easier to implement, few well-established projects exist. It's fairly straightforward to develop one from scratch given the available open-source rendering/physics libraries, but it still takes quite a bit of work, enough to motivate this framework. And if we are several who use the same framework, we can assemble a larger set of reusable robotics assets.
Features
- C++
- Linux and Windows
- Physics based on Box2D
- Top-view and side-view
- Lightweight rendering using OpenGL, GLFW, GLAD and ImGui
- Basic shapes, Texture, Sprite animation
- Robotics assets (so far):
- Complete robots
- Sumobot with custom dimensions, wheels, sensors, speed, acceleration, etc.
- Line-follower with custom dimensions, wheels, sensors, speed, acceleration, etc.
- Sensors
- Range sensor
- Line detector
- Actuators
- Basic DC-motor model with tuneable acceleration and speed characteristics
- Playgrounds
- Sumobot dohyo with customizable radius
- Customizable line follower path
- It's easy to create new assets...
- Complete robots
- Language binding ("Software-in-loop")
- Controller code can be written in C (easy to transfer to a real MCU)
- Customizable controller/physics update rate
- ~60-2000 Hz (or more depending the host computer)
Limitations
- Not built or tested on macOS (OpenGL is deprecated on macOS)
- Physics
- Object dimensions limited to 0.01-1m
- As a consequence of Box2D being limited to 0.1-10m
- The physics scale factor can be changed, but the span between min and max is still limited
- Roughly approximated top-view physics
- Sets Box2D gravity to 0 and uses b2FrictionJoint for friction.
- Object dimensions limited to 0.01-1m
- Simulation speed fixed to real time
- No fast-forwarding or slowmotion.
- Rendering
- No z-indexing, so you must create objects in the order you want them rendered.
- No drag-and-drop GUI
- Everything is set up through code.
- Performance
- Not optimized for complex simulations (involving many objects)
Getting started
There is a testapp under testapp/, which shows you how to use the framework. It contains a set of scenes based on the existing robotics assets (under assets/).
Clone
Bots2D depends on other git projects checked out at specific commits. These are included as git submodules under external/. To clone the repo (including all submodules), run:
git clone --recursive -j8 https://github.com/artfulbytes/bots2d
If you already accidently cloned the repo non-recursively, you can get the submodules with:
git submodule update --init
Build
Bots2D is built with CMake. Look at testapp/ for an example of how to use it in your application.
Build testapp on Linux
On Ubuntu 20.04, you may have to install the following packages:
sudo apt install mesa-common-dev \
libxi-dev \
libxcursor-dev \
libxinerama-dev \
libxrandr-dev \
libx11-dev
Then run:
cd testapp/
mkdir build
cd build
cmake ..
cmake --build .
run build/bots2d_testapp
Build testapp on Windows
Tested with Visual Studio 2019:
1. Open local folder and select bots2d/testapp
2. After VS has loaded the project, right-click on CMakeLists.txt in the solution
explorer and set it as startup item.
3. Start Debugging (F5)
Folder structure
Folder name | Description |
---|---|
assets | Reusable robotics objects and textures |
docs | Documentation |
external | External dependencies |
src | Bots2D implementation and header files |
testapp | An example/test application with test scenes |
tools | Standalone helper tools/scripts |
Documentation
Bots2D is documented with Doxygen. You can generate the documentation with:
doxygen docs/Doxyfile
to docs/. You can also access it online here. If you want to push new updates to the online version, you should push the changes to the gh-branch (not master).
There is also a lenghty blog post about Bots2D here.
Known issues
- Rendering is slightly off (probably because of rounding error)
- Physics is fine, but two objects next to each other are rendered with a small gap in-between.
- Rendering movement is jittery when the physics rate < 2x rendering rate
- No graphics interpolation
Troubleshooting
- Incorrect OpenGL version (Linux)
- Check version in console output
- "export MESA_GL_VERSION_OVERRIDE=3.3"
- "RandR headers not found; install libxrandr development package"
- GLFW requires xorg-dev liblu1-mesa-dev
- On Ubuntu, run "sudo apt install xorg-dev libglu1-mesa-dev"
Contributing
If you modify or add something, you are encouraged to submit a pull request. In that case, make sure you also create a corresponding test scene in the testapp.
Dependencies
Bots2D depends on the following libraries:
Name | Description | License |
---|---|---|
Box2D | Used for 2D physics | MIT |
GLFW | Used for window management | zlib/libpng |
ImGui | Used for GUI overlay | MIT |
stb | Used for image loading | MIT |
GLM | Used for vector math | MIT |
They are included (untouched) as git submodules under external/.
Credits
Name | |
---|---|
The Cherno | Some of the rendering code stem from his YouTube tutorials. |
iforce2d | Very useful Box2D tutorials |