[Big Feature] Add support for rendering via Magnum Engine

CMakeLists.txt

@@ -2,19 +2,17 @@ cmake_minimum_required(VERSION 3.11)
 project(dismech-rods)
 
 set(CMAKE_CXX_STANDARD 17)
-# set(CMAKE_BUILD_TYPE Release)
-# set(CMAKE_BUILD_TYPE Debug)
 
 set(CMAKE_CXX_FLAGS "-O3 -DNDEBUG -Wno-deprecated-declarations")
 include(CheckCXXCompilerFlag)
 CHECK_CXX_COMPILER_FLAG("-march=native" COMPILER_SUPPORTS_MARCH_NATIVE)
-if(COMPILER_SUPPORTS_MARCH_NATIVE)
+if (COMPILER_SUPPORTS_MARCH_NATIVE)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -march=native")
-endif()
+endif ()
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "../")
 
 set(CMAKE_INTERPROCEDURAL_OPTIMIZATION TRUE)
-
+set(MAGNUM_WITH_SDL2APPLICATION ON)
 set(THREADS_PREFER_PTHREAD_FLAG ON)
 
 # Per https://eigen.tuxfamily.org/dox/TopicUsingIntelMKL.html eigen should be used
@@ -34,6 +32,24 @@ find_package(Eigen3 3.4 REQUIRED)
 find_package(OpenMP)
 find_package(FCL REQUIRED)
 
+# Run with -DWITH_MAGNUM=ON to build with Magnum library.
+option(WITH_MAGNUM OFF)
+if (WITH_MAGNUM)
+    add_definitions(-DWITH_MAGNUM)
+    find_package(Corrade REQUIRED Main PluginManager Utility)
+    find_package(Magnum REQUIRED
+            GL
+            MeshTools
+            Primitives
+            Shaders
+            Trade
+            Sdl2Application
+            SceneGraph)
+    find_package(MagnumPlugins REQUIRED PngImageConverter)
+else ()
+    message(STATUS "Building with Magnum disabled")
+endif ()
+
 if (${HAVE_SYMENGINE_LLVM})
     message(STATUS "Testing SymEngine LLVM & SBML support - found")
 else ()
@@ -49,7 +65,6 @@ include_directories(${SYMENGINE_INCLUDE_DIRS}
 
 link_directories(${MKL_LIBRARY_DIR})
 
-
 # Run with cmake --fresh -DCREATE_DOCS=ON .. only when documentation needs to be updated.
 
 # If docs change and you want to preview the updates in index.html, you'll need to rm -rf * and
@@ -61,9 +76,9 @@ link_directories(${MKL_LIBRARY_DIR})
 # Probably a good idea to split the documentation cmake process into its own directory later.
 option(CREATE_DOCS OFF)
 
-if(CREATE_DOCS)
+if (CREATE_DOCS)
     add_subdirectory("docs")
-else()
+else ()
     add_executable(disMech
             src/main.cpp
             src/world.cpp
@@ -116,7 +131,13 @@ else()
             src/controllers/activeEntanglementController.cpp
 
             src/utils/utils.cpp
-            )
+            src/simulation_environments/magnumDERSimulationEnvironment.cpp
+    )
+    if (WITH_MAGNUM)
+        target_sources(disMech PRIVATE
+                src/simulation_environments/magnumDERSimulationEnvironment.cpp
+        )
+    endif ()
 
     target_include_directories(disMech PRIVATE
             src
@@ -139,8 +160,23 @@ else()
             ${SYMENGINE_LIBRARIES}
             fcl
     )
+    if (WITH_MAGNUM)
+        target_link_libraries(disMech PRIVATE
+                Corrade::Main
+                Corrade::PluginManager
+                Corrade::Utility
+                Magnum::Application
+                Magnum::GL
+                Magnum::Magnum
+                Magnum::MeshTools
+                Magnum::Primitives
+                Magnum::SceneGraph
+                Magnum::Shaders
+        )
+        target_link_libraries(disMech PRIVATE MagnumPlugins::PngImageConverter)
+    endif ()
 
     if (OpenMP_CXX_FOUND)
         target_link_libraries(disMech PUBLIC OpenMP::OpenMP_CXX)
     endif ()
-endif()
+endif ()

README.md

@@ -43,7 +43,6 @@ If you'd like DisMech to support a new feature, feel free create an issue and we
 
 #### High priority
 - [ ] Improve robustness of friction.
-- [ ] Add a more sophisticated renderer.
 - [ ] Add contact logic for joints.
 - [ ] Add URDF functionality for instantiating robot.
 - [ ] Add shell functionality.
@@ -57,6 +56,7 @@ If you'd like DisMech to support a new feature, feel free create an issue and we
 - [ ] Add more controller types.
 
 ### COMPLETED
+- [x] Add a more sophisticated renderer. PR [#12]()
 - [x] Add per-limb friction coefficient logic. PR [#5](https://github.com/StructuresComp/dismech-rods/pull/5)
 - [x] Add active entanglement example code.
 - [x] Add limb self-contact option.
@@ -138,13 +138,43 @@ For other operating systems you should be able to modify the commands below appr
     ```
 
 - [OpenGL / GLUT](https://www.opengl.org/)
-  - OpenGL / GLUT is used for rendering the knot through a simple graphic.
+  - OpenGL / GLUT is used for barebones rendering through simple line graphics.
   - Simply install through apt package manager:
     - **Ubuntu**: `sudo apt-get install libglu1-mesa-dev freeglut3-dev mesa-common-dev`
     - **macOS**: `sudo port install freeglut pkgconfig` (Note: `pkgconfig` is necessary to avoid finding system GLUT instead of `freeglut`.)
 
 - Lapack (*included in MKL*)
 
+### Optional Dependencies
+
+The default renderer used in DisMech is simply an isometric view of lines depicting rod centerlines using a barebones implementation based on OpenGL. 
+For users wishing to have more advanced rendering with camera pose manipulation via the mouse, they can install and build with the Magnum Engine.
+Below is an example rendering.
+
+<div align="center"> <img src="media/magnum.gif" width="500"> </div> 
+
+- [Magnum Engine](https://magnum.graphics/)
+  - Before downloading magnum, users must first build and install Magnum's utility library [Corrade](https://magnum.graphics/corrade/). 
+    Install instructions for various platforms can be found [here](https://doc.magnum.graphics/corrade/building-corrade.html).
+  - After installing Corrade, install instructions for Magnum can similarly be found [here](https://doc.magnum.graphics/magnum/building.html).
+  - Finally, Magnum allows users to save each rendered frame as a png file which can be used to create videos such as `ffmpeg`. 
+  For this feature, we must download and build [magnum-plugins](https://doc.magnum.graphics/magnum/building-plugins.html#building-plugins-manual) as follows.
+     ```bash
+    sudo apt-get install libpng-dev  # a dependency of magnum-plugins' PngImageConverter
+    git clone https://github.com/mosra/magnum-plugins
+    cd magnum-plugins && mkdir build && cd build
+    cmake -DWITH_PNGIMAGECONVERTER=ON ..
+    make -j$(nproc)
+    sudo make install
+    ```
+  - Once Corrade and Magnum are properly installed, users can build DisMech with the following additional cmake build flag:
+    ```bash
+    mkdir build && cd build
+    cmake -DWITH_MAGNUM=ON ..
+    make -j$(nproc)
+    ```
+  - For those wishing to customize the rendering settings, users can take a look and adjust the source code in `magnumDERSimulationEnvironment.cpp` accordingly.
+
 ***
 
 ### Running Examples
@@ -158,7 +188,7 @@ For example, using the cantilever beam example:
 cp examples/cantilever_case/cantileverExample.cpp robotDescription.cpp
 mkdir build && cd build
 cmake ..
-make -j4
+make -j$(nproc)
 cd ..
 ```
 Afterwards, simply run the simulation using the `dismech.sh` script.
@@ -179,8 +209,12 @@ In addition, many numerical parameters can be set through the `simParams` struct
 struct simParams {
   double sim_time = 10;                              //    Total time for simulation [s]
   double dt = 1e-3;                                  //    Time step size [s]
-  bool render = true;                                //    Live OpenGL rendering
-  bool show_mat_frames = false;                      //    Render material frames
+  renderer_type renderer = OPENGL;                   // *  Renderer type
+  int render_every = 1;                              //    Rendering period
+                                                     //        Currently only for Magnum. TODO for OpenGL support.
+  string render_record_path;                         //    Rendering frames recording path (only for Magnum). 
+                                                     //        Does not record if render_record_path is an empty string.
+  bool show_mat_frames = false;                      //    Render material frames (only for OpenGL)
   double render_scale = 1.0;                         //    Rendering scale
   double dtol = 1e-2;                                // *^ Dynamics tolerance [m/s]
   double ftol = 1e-4;                                // *^ Force tolerance
@@ -196,6 +230,11 @@ struct simParams {
 
 Detailed parameter explanations:
 
+- `renderer_type` - Determines the renderer. Currently, available options are
+  - `HEADLESS`: No rendering. Fastest and best for rapid data generation.
+  - `OPENGL`: Fixed isometric view rendering. Renders centerlines of rods as simple lines. Relatively low computational overhead. Recommended for general use and debugging.
+  - `MAGNUM`: Camera pose manipulation via mouse. Renders rod and environment with 3D meshes and shading. Higher computational overhead. Recommended only for creating videos.
+
 - `numerical_integration_scheme` - Determines the numerical integration scheme. Currently, available options are 
   - `FORWARD_EULER`: https://en.wikipedia.org/wiki/Euler_method
   - `VERLET_POSITION`: https://en.wikipedia.org/wiki/Verlet_integration

src/main.cpp

@@ -3,6 +3,9 @@
 #include "logging/worldLogger.h"
 #include "simulation_environments/headlessDERSimulationEnvironment.h"
 #include "simulation_environments/openglDERSimulationEnvironment.h"
+#ifdef WITH_MAGNUM
+#include "simulation_environments/magnumDERSimulationEnvironment.h"
+#endif
 #include "robotDescription.h"
 #include "global_const.h"
 
@@ -31,11 +34,20 @@ int main(int argc,char *argv[])
     verbosity = sim_params.debug_verbosity;
 
     unique_ptr<derSimulationEnvironment> env;
-    if (sim_params.render) {
-        env = make_unique<openglDERSimulationEnvironment>(my_world, sim_params, logger, argc, argv);
-    }
-    else {
-        env = make_unique<headlessDERSimulationEnvironment>(my_world, sim_params, logger);
+    switch(sim_params.renderer) {
+        case HEADLESS:
+            env = make_unique<headlessDERSimulationEnvironment>(my_world, sim_params, logger);
+            break;
+        case OPENGL:
+            env = make_unique<openglDERSimulationEnvironment>(my_world, sim_params, logger, argc, argv);
+            break;
+#ifdef WITH_MAGNUM
+        case MAGNUM:
+            env = make_unique<Magnum::magnumDERSimulationEnvironment>(my_world, sim_params, logger, argc, argv);
+            break;
+#endif
+        default:
+            throw std::runtime_error("Unknown renderer type provided.");
     }
 
     env->runSimulation();

src/robotDescription.h

@@ -30,13 +30,20 @@ typedef enum {FORWARD_EULER,
               IMPLICIT_MIDPOINT}
               numerical_integration_scheme;
 
+typedef enum {HEADLESS,
+              OPENGL,
+              MAGNUM}
+              renderer_type;
+
 
 struct simParams {
     double sim_time = 10;                              // Total time for simulation [s]
     double dt = 1e-3;                                  // Time step size [s]
-    bool render = true;                                // Live OpenGL rendering
-    bool show_mat_frames = false;                      // Render material frames
+    renderer_type renderer = OPENGL;                   // Renderer type
+    bool show_mat_frames = false;                      // Render material frames (only for OpenGL)
     double render_scale = 1.0;                         // Rendering scale
+    int render_every = 1;                              // Rendering period (only for Magnum)
+    string render_record_path;                         // Rendering frames recording path (only for Magnum)
     double dtol = 1e-2;                                // Dynamics tolerance [m/s]*
     double ftol = 1e-4;                                // Force tolerance*
     int max_iter = 500;                                // Maximum iterations for a time step

src/rod_mechanics/external_forces/floorContactForce.h

@@ -17,6 +17,7 @@ class floorContactForce : public baseForce
     void computeForceAndJacobian(double dt) override;
 
     double min_dist;
+    double floor_z;
     int num_contacts;
 
     void change_slip_tol(double scale);
@@ -40,6 +41,5 @@ class floorContactForce : public baseForce
     double orig_slip_tol;
     double K1;
     double K2;
-    double floor_z;
 };
 #endif