Add Candlewick runtime (executable and client)

.pre-commit-config.yaml

@@ -5,7 +5,7 @@ ci:
   submodules: true
 repos:
   - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: v20.1.0
+    rev: v20.1.8
     hooks:
     - id: clang-format
       types_or: []
@@ -15,6 +15,7 @@ repos:
     rev: v5.0.0
     hooks:
       - id: check-added-large-files
+        args: ['--maxkb=1800']
       - id: check-case-conflict
       - id: check-yaml
         exclude: ^packaging/conda/
@@ -23,17 +24,18 @@ repos:
       - id: mixed-line-ending
       - id: check-merge-conflict
       - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
         exclude: |
             (?x)^(
                 doc/doxygen-awesome.*
             )$
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.11.4'
+    rev: 'v0.12.3'
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
   - repo: https://github.com/BlankSpruce/gersemi
-    rev: 0.19.2
+    rev: 0.20.1
     hooks:
       - id: gersemi

CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added tools for loading models from a given description struct `RobotSpec` (https://github.com/Simple-Robotics/candlewick/pull/37)
+- Added Candlewick visualizer runtime, to be used to (up)load Pinocchio models and submit states to be displayed asynchronously. (https://github.com/Simple-Robotics/candlewick/pull/37)
+- Embed Inter Medium font into the application (https://github.com/Simple-Robotics/candlewick/pull/37)
+
+### Changed
+
+- CMake : sync jrl-cmakemodules to new release 1.0.0 (https://github.com/Simple-Robotics/candlewick/pull/37)
+- CMake : change option `BUILD_PYTHON_BINDINGS` to `BUILD_PYTHON_INTERFACE` (https://github.com/Simple-Robotics/candlewick/pull/37)
+- multibody/Visualizer : `stopRecording()` now returns a flag (https://github.com/Simple-Robotics/candlewick/pull/37)
+
+### Fixed
+
+- `core/Device.h` : fix release() function
+- Python examples : wrap some import statements in try/except statements (https://github.com/Simple-Robotics/candlewick/pull/37)
+
+### Removed
+
+- Remove dependency on `robot_descriptions_cpp` (https://github.com/Simple-Robotics/candlewick/pull/37)
+
 ## [0.7.0] - 2025-07-04
 
 ### Added

CMakeLists.txt

@@ -55,13 +55,19 @@ set(AWESOME_CSS_DIR ${PROJECT_SOURCE_DIR}/doc/doxygen-awesome-css)
 
 option(BUILD_EXAMPLES "Build examples." OFF)
 option(BUILD_PINOCCHIO_VISUALIZER "Build the Pinocchio visualizer." ON)
+cmake_dependent_option(
+  BUILD_VISUALIZER_RUNTIME
+  "Build the visualizer runtime which is used to have a persistent visualizer (e.g. for async clients)."
+  OFF
+  BUILD_PINOCCHIO_VISUALIZER
+  OFF
+)
 
-option(BUILD_PYTHON_BINDINGS "Build Python bindings." OFF)
 cmake_dependent_option(
   GENERATE_PYTHON_STUBS
   "Generate the Python stubs associated to the Python library"
   OFF
-  BUILD_PYTHON_BINDINGS
+  BUILD_PYTHON_INTERFACE
   OFF
 )
 
@@ -133,7 +139,7 @@ if(BUILD_TESTING)
   add_subdirectory(tests)
 endif()
 
-if(BUILD_PYTHON_BINDINGS)
+if(BUILD_PYTHON_INTERFACE)
   add_subdirectory(bindings/python)
   # WIP nanobind bindings
   # add_subdirectory(bindings/nanobind)

README.md

@@ -2,17 +2,17 @@
 [![Conda package](https://img.shields.io/conda/vn/conda-forge/candlewick.svg)](https://anaconda.org/conda-forge/candlewick)
 
 
-# Candlewick: a WIP renderer based on SDL_gpu
+# Candlewick: a modern, cross-platform real-time renderer for robotics based on SDL3
 
 > [!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).
+Candlewick is a cross-platform framework for real-time visualization in robotics, based on SDL3's [graphics API](https://wiki.libsdl.org/SDL3/CategoryGPU).
 
-## Features
+![go2 standing](doc/go2_standing_example.png)
 
-Candlewick comes with a set of graphical, interaction, and utility features.
+## Features
 
 ### Graphical features
 
@@ -55,67 +55,130 @@ with create_recorder_context(viz, "ur10_video.mp4"):
     viz.display(q0)
 ```
 
+![ur10](doc/ur10_with_gui_example.png)
+
+#### Candlewick visualizer runtime and client
 
-## Installation
+The runtime allows users to persist a visualizer window and keep interacting with it asynchronously, *even when display commands are not being submitted*.
 
-### Dependencies
+To build the runtime, users must set the `BUILD_VISUALIZER_RUNTIME` CMake option.
+
+Launch the candlewick runtime:
+
+```bash
+candlewick-visualizer # --help
+```
+
+The corresponding asynchronous visualizer client is used as follows:
+
+```python
+from candlewick.async_visualizer import AsyncVisualizer
+
+viz = AsyncVisualizer(model, geom_model)
+viz.initViewer(hostname="127.0.0.1", port=12000)
+viz.loadViewerModel()
+# use as any other Pinocchio visualizer class
+```
+
+Check out the [corresponding example](examples/python/ur3_async_runtime.py).
+
+
+## Dependencies
+
+### Core 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
+* [SDL3](https://github.com/libsdl-org/SDL/) - Graphics backend, windowing, user input
+* [Assimp](https://assimp-docs.readthedocs.io/en/latest/) - Loading meshes and importing 3D assets
+* [EnTT](https://github.com/skypjack/entt/) - Implementing the Entity-Component System
+* [nlohmann_json](https://github.com/nlohmann/json) - JSON parsing (used internally for shader reflection)
+* [Eigen](https://gitlab.com/libeigen/eigen/) - Linear algebra
+* [Coal](https://github.com/coal-library/coal) - Collision detection, geometry primitives
+* [magic_enum](https://github.com/Neargye/magic_enum) - Enum reflection utilities
 
 These dependencies can be installed from Conda as follows:
 ```bash
 conda install -c conda-forge sdl3 eigen coal magic_enum assimp entt nlohmann_json
 ```
 
-#### Optional dependencies
+Additionally, candlewick depends on the following bundled dependencies:
+
+* [ImGui](https://github.com/ocornut/imgui/) - immediate-mode GUI
+
+### Optional dependencies
+
+#### Python bindings
 
 * [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
-  ```
+
+*Python runtime dependencies:* `numpy`
+
+#### Pinocchio support
+
+Required for the `candlewick::multibody` classes and functions:
+
+* [Pinocchio](https://github.com/stack-of-tasks/pinocchio), **must** be built with collision support.
+  `conda install -c conda-forge pinocchio`
+
+*Python runtime dependencies:* `pinocchio` (Python bindings)
+
+Additional dependencies for the `candlewick-visualizer` runtime:
+
+* [cppzmq](https://github.com/zeromq/cppzmq) - C++ ZeroMQ bindings
+* [msgpack-cxx](https://github.com/msgpack/msgpack-c/tree/cpp_master) - MessagePack serialization
+
+*Python runtime dependencies:* `pyzmq msgspec`
+
+#### Video recording
+
+* [FFmpeg](https://ffmpeg.org/) for support for recording videos from the rendered graphics. | `conda install ffmpeg pkg-config` | The following components are required:
+  * `libavformat` - Container format handling
+  * `libavcodec` - Video encoding/decoding
+  * `libswscale` - Image scaling and format conversion
+
+#### Development dependencies (tests, examples)
+
 * [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 install -c conda-forge pinocchio`
-  * With Pinocchio support activated, building the tests requires [example-robot-data](https://github.com/Gepetto/example-robot-data) | `conda install -c conda-forge example-robot-data`
+* <u>With Pinocchio support</u>: building the C++ examples requires [example-robot-data](https://github.com/Gepetto/example-robot-data).
+  `conda install -c conda-forge example-robot-data`
 
-The optional dependencies can be installed from conda:
-```bash
-conda install -c conda-forge
-  gtest \  # for testing
-  ffmpeg pkg-config \  # for FFmpeg support
-  cli11 \  # for the examples
-  pinocchio \  # for multibody/Pinocchio support
-  example-robot-data # for the examples, with the above
-```
-
-### Building
+## Building Candlewick
 
-For building the library, you will need [CMake](https://cmake.org/) (version at least 3.20) and a C++20-compliant compiler. These can also be obtained through Conda.
+For building the library, you will need [CMake](https://cmake.org/) (version at least 3.26) and a C++20-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 \
+cmake -S . -B build/ \
+  -DCMAKE_BUILD_TYPE=Release \
   -DBUILD_PINOCCHIO_VISUALIZER:BOOL=ON \  # For Pinocchio support
-  -DBUILD_PYTHON_BINDINGS:BOOL=ON \ # For Python bindings
+  -DBUILD_VISUALIZER_RUNTIME:BOOL=ON \  # Async visualizer runtime
+  -DBUILD_PYTHON_INTERFACE:BOOL=ON \  # For Python bindings
+  -DGENERATE_PYTHON_STUBS:BOOL=ON \  # Python binding type stubs
   -GNinja \ # or -G"Unix Makefiles" to use Make
   -DBUILD_TESTING=OFF \  # or ON not build the tests
-  -DCMAKE_INSTALL_PREFIX=<your-install-prefix> # e.g. ~/.local/, or $CONDA_PREFIX
+  -DCMAKE_INSTALL_PREFIX=<your-install-prefix> \  # e.g. ~/.local/, or $CONDA_PREFIX
+  <other-options...>
 # 2. Move into it and build (generator-independent)
-cd build/ && cmake --build . -j<num-parallel-jobs>
+cd build/
+cmake --build . -j<num-parallel-jobs>
 # 3. Install
 cmake --install .
 ```
 
+### A summary of build options
+
+| Build Option | Default | Description | Additional Dependencies | Requires |
+|-------------|---------|-------------|------------------------|----------|
+| `BUILD_PYTHON_INTERFACE` | `ON` | Build Python bindings | eigenpy | - |
+| `BUILD_PINOCCHIO_VISUALIZER` | `ON` | Enable Pinocchio robot visualization | pinocchio >= 3.5 | - |
+| `BUILD_VISUALIZER_RUNTIME` | `OFF` | Build `candlewick-visualizer` executable | cppzmq, msgpack-cxx | `BUILD_PINOCCHIO_VISUALIZER=ON` |
+| `BUILD_WITH_FFMPEG_SUPPORT` | `OFF` | Enable video recording capabilities | FFmpeg | - |
+| `GENERATE_PYTHON_STUBS` | `OFF` | Generate Python type stubs | *(handled by cmake submodule)* | `BUILD_PYTHON_INTERFACE=ON` |
+
+
 ## 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.
@@ -125,3 +188,13 @@ 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/
+
+
+### Font Credit/License
+
+Candlewick embeds the **Inter Medium** font as part of its source code:
+
+**Inter-Medium.ttf**, by Rasmus Andersson.  
+SIL OPEN FONT LICENSE Version 1.1  
+Copyright (c) 2016 The Inter Project Authors  
+https://rsms.me/inter

bindings/python/CMakeLists.txt

@@ -61,7 +61,7 @@ if(GENERATE_PYTHON_STUBS)
   )
 endif(GENERATE_PYTHON_STUBS)
 
-set(PYTHON_FILES __init__.py video_context.py)
+set(PYTHON_FILES __init__.py async_visualizer.py video_context.py)
 
 foreach(pyfile ${PYTHON_FILES})
   PYTHON_INSTALL_ON_SITE(${PROJECT_NAME} ${pyfile})