https://github.com/manifoldfr/candlewick
A cross-platform real-time 3D renderer for robotics powered by SDL3-gpu
https://github.com/manifoldfr/candlewick
Last synced: about 2 months ago
JSON representation
A cross-platform real-time 3D renderer for robotics powered by SDL3-gpu
- Host: GitHub
- URL: https://github.com/manifoldfr/candlewick
- Owner: ManifoldFR
- License: bsd-2-clause
- Created: 2024-09-14T18:15:24.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-03-19T13:35:11.000Z (2 months ago)
- Last Synced: 2025-03-19T14:33:48.279Z (2 months ago)
- Language: C++
- Homepage:
- Size: 1.16 MB
- Stars: 13
- Watchers: 3
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Candlewick: a WIP renderer based on SDL_gpu
> [!WARNING]
> Candlewick is still under **active** development. Support will be limited, and the API might break unexpectedly and repeatedly.
Candlewick is a WIP library for a renderer based on SDL3's new [GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU).
## Features
Candlewick comes with a set of graphical, interaction, and utility features.
### Graphical features
* Shadow mapping using directional shadow maps
* Screen-space ambient occlusion (SSAO)
* **WIP:** Screen-space shadows (SSS)
### Interactivitity
* Integration with ImGui
* **(optional)** Record videos from the main window using FFmpeg
### Pinocchio visualizer
Candlewick visualization utilities for robotics based on Pinocchio.
You can load a Pinocchio model, its geometry model, and create a visualizer that can be used similar to the other visualizers included in `pinocchio.visualize`.
Here's a Python example:
```python
import example_robot_data as erd
import pinocchio as pin
import numpy as np
from candlewick.multibody import Visualizer, VisualizerConfig
robot = erd.load("ur10")
model: pin.Model = robot.model
data: pin.Data = robot.data
visual_model = robot.visual_model
config = VisualizerConfig()
config.width = 1280
config.height = 720
viz = Visualizer(config, model, visual_model)
q0 = pin.neutral(model)
viz.setCameraPose(pin.SE3.Identity())
viz.display(q0)
```
## Installation
### Dependencies
Candlewick depends mainly on:
* [SDL3](https://github.com/libsdl-org/SDL/) for windowing, processing input events, and of course SDL GPU.
* [EnTT](https://github.com/skypjack/entt/) for the entity-component system (ECS)
* [nlohmann/json](https://github.com/nlohmann/json) for processing JSON files
* the [Eigen](https://gitlab.com/libeigen/eigen/) linear algebra template library
* the [Coal](https://github.com/coal-library/coal) collision algorithms library
* [magic_enum](https://github.com/Neargye/magic_enum) (enum reflection library)
* [Open Asset Importer Library (assimp)](https://assimp-docs.readthedocs.io/en/latest/) for loading meshes
These dependencies can be installed from Conda as follows:
```bash
conda install sdl3 eigen magic_enum assimp entt nlohmann_json
```
#### Optional dependencies
* [eigenpy](https://github.com/stack-of-tasks/eigenpy) for Python bindings.
* [FFmpeg](https://ffmpeg.org/) for support for recording videos from the rendered graphics. The CMake finder module also requires pkg-config.
```bash
conda install ffmpeg pkg-config
```
* [GoogleTest](https://github.com/google/googletest) for the tests | `conda install gtest`
* [CLI11](https://github.com/CLIUtils/CLI11) for the examples and tests | `conda install cli11`
* The [Pinocchio](https://github.com/stack-of-tasks/pinocchio) rigid-body dynamics library (required for the `candlewick::multibody` classes and functions). Pinocchio must be built with collision support. | [conda-forge](https://anaconda.org/conda-forge/pinocchio)
### Building
For building the library, you will need [CMake](https://cmake.org/) (version at least 3.20) and a C++17-compliant compiler. These can also be obtained through Conda.
In the directory where you have checked out the code, perform the following steps:
```bash
# 1. Create a CMake build directory
cmake -S . -B build/ -DCMAKE_BUILD_TYPE=Release \
-DBUILD_PINOCCHIO_VISUALIZER:BOOL=ON \ # For Pinocchio support
-DBUILD_PYTHON_BINDINGS:BOOL=ON \ # For Python bindings
-GNinja \ # or -G"Unix Makefiles" to use Make
-DCMAKE_INSTALL_PREFIX= # e.g. ~/.local/, or $CONDA_PREFIX
# 2. Move into it and build (generator-independent)
cd build/ && cmake --build . -j
# 3. Install
cmake --build . --target install
```
## Credits
Many of the design choices of this library are heavily inspired by other, more mature work in the open-source 3D graphics middleware space.
Here are some of the resources I've looked at:
* the [Magnum](https://magnum.graphics/) graphics middleware (the design ideas around mesh layouts, how to load geometry primitives, and the type-erased `MeshData` type)
* [bgfx](https://github.com/bkaradzic/bgfx/)
* Sascha Willems' Vulkan examples: https://github.com/SaschaWillems/Vulkan/