Add camera controls to Lua and Lua exit (#99)

* Add camera controls to Lua and Lua exit

* Fix ffmpeg colour/fps, no bitrate, add profile

* Main profile as default

* No lossless by default

Author: Jerboa-app

DOCUMENTATION.md

@@ -117,9 +117,16 @@ It is possible to write Lua scripts to manipulate visualisation in SFOAV. By sup
 | getAtomsNeighbours | Atom index x, cutoff distance | The neighbours of a within the cutoff |
 | setText | Text string | Set the text display |
 | getFrame | | The current frame number (from 0) |
-| toggleRecord | | Start or stop video recording |
+| startRecording | | Start video recording if not already recording |
+| stopRecording | | Stop video recording if already recording |
 | play | | Play the trajectory |
 | pause | | Pause playing the trajectory |
+| cameraPosition | Bool for spherical coordinates | Get the camera's position |
+| setCameraPosition | r, theta, phi spherical coordinates | Set the camera's position |
+| rotateCamera | dphi, the azimuthal increment | Rotate the camera |
+| zoomCamera | dr, move the camera to or from the focus | Zoom the camera |
+| inclineCamera | dtheta, the inclination increment | Incline the camera |
+| exit | | Exit sfoav |
 
 E.g. the following script will set Atom 0 to a random colour every frame.
 
@@ -147,6 +154,30 @@ for i = 1, #neighbours do
 end
 ```
 
+Another example for automated video rendering
+
+```lua
+if (record == nil) then
+    -- Will only run once.
+    record = true
+    sfoav.inclineCamera(3.14*0.25)
+    -- Begins recording.
+    sfoav.startRecording()
+    -- Begins trajectory playing.
+    sfoav.play()
+end
+
+if (record and sfoav.getFrame() == 200) then
+    -- At frame 200 finish recording and exit when done.
+    sfoav.stopRecording()
+    sfoav.pause()
+    -- Exit will occur after frames are written.
+    sfoav.exit()
+    -- Ensure no duplicate calls.
+    record = false
+end
+```
+
 ## Video
 
 On macOS and Windows one release exists using jo_mpeg to write mp4 files.

README.md

@@ -111,11 +111,18 @@ It is possible to write Lua scripts to manipulate visualisation in SFOAV. By sup
 | getAtom        | Atom index a | The Atom structure for a |
 | atomCount      | | The number of atoms |
 | getAtomsNeighbours | Atom index x, cutoff distance | The neighbours of a within the cutoff |
-| setText | Text string | The neighbours of a within the cutoff |
+| setText | Text string | Set the text display |
 | getFrame | | The current frame number (from 0) |
-| toggleRecord | | Start or stop video recording |
+| startRecording | | Start video recording if not already recording |
+| stopRecording | | Stop video recording if already recording |
 | play | | Play the trajectory |
 | pause | | Pause playing the trajectory |
+| cameraPosition | Bool for spherical coordinates | Get the camera's position |
+| setCameraPosition | r, theta, phi spherical coordinates | Set the camera's position |
+| rotateCamera | dphi, the azimuthal increment | Rotate the camera |
+| zoomCamera | dr, move the camera to or from the focus | Zoom the camera |
+| inclineCamera | dtheta, the inclination increment | Incline the camera |
+| exit | | Exit sfoav |
 
 ```lua
 -- Set atom 0 to a random colour.
@@ -141,6 +148,30 @@ for i = 1, #neighbours do
 end
 ```
 
+Another example for automated video rendering
+
+```lua
+if (record == nil) then
+    -- Will only run once.
+    record = true
+    sfoav.inclineCamera(3.14*0.25)
+    -- Begins recording.
+    sfoav.startRecording()
+    -- Begins trajectory playing.
+    sfoav.play()
+end
+
+if (record and sfoav.getFrame() == 200) then
+    -- At frame 200 finish recording and exit when done.
+    sfoav.stopRecording()
+    sfoav.pause()
+    -- Exit will occur after frames are written.
+    sfoav.exit()
+    -- Ensure no duplicate calls.
+    record = false
+end
+```
+
 ## Video
 
 On macOS and Windows one release exists using jo_mpeg to write mp4 files.

include/camera.h

@@ -4,10 +4,14 @@
 #include <vector>
 #include <cstdint>
 
-#include <glm/glm.hpp>
+#include "glm/glm.hpp"
+#include "glm/gtc/matrix_transform.hpp"
+#include <lua.h>
 
 #include <atom.h>
 #include <util.h>
+#include <LuaNumber.h>
+#include <LuaBool.h>
 
 /**
  * @brief A 3D projective camera centered on a focus moving on a sphere.
@@ -222,6 +226,58 @@ class Camera
     uint16_t getResX() const { return resX; }
     uint16_t getResY() const { return resY; }
 
+    /**
+     * @brief Get the Camera position.
+     *
+     * @remark Lua arguments are:
+     * 1. Whether to return in spherical coordinates.
+     * @param lua the Lua context.
+     * @return int the return code.
+     */
+    inline int lua_cameraPosition(lua_State * lua);
+
+    /**
+     * @brief Set Camera position.
+     *
+     * @remark Lua arguments are:
+     * 1. r
+     * 2. theta
+     * 3. phi
+     * @param lua the Lua context.
+     * @return int the return code.
+     */
+    inline int lua_setCameraPosition(lua_State * lua);
+
+    /**
+     * @brief Rotate the Camera.
+     *
+     * @remark Lua arguments are:
+     * 1. The azimuthal increment.
+     * @param lua the Lua context.
+     * @return int the return code.
+     */
+    inline int lua_rotateCamera(lua_State * lua);
+
+    /**
+     * @brief Zoom the Camera.
+     *
+     * @remark Lua arguments are:
+     * 1. The zoom increment.
+     * @param lua the Lua context.
+     * @return int the return code.
+     */
+    inline int lua_zoomCamera(lua_State * lua);
+
+    /**
+     * @brief Incline the camera.
+     *
+     * @remark Lua arguments are:
+     * 1. The polar increment.
+     * @param lua the Lua context.
+     * @return int the return code.
+     */
+    inline int lua_inclineCamera(lua_State * lua);
+
 private:
 
     uint16_t resX;
@@ -253,4 +309,6 @@ class Camera
 
 };
 
+#include <luaBindings/camera.h>
+
 #endif /* CAMERA_H */

include/commandLine.h

@@ -505,11 +505,11 @@ struct CommandLine
             getArgument<uint8_t>(cq, commandLine, c, count);
             getArgument<uint8_t>(qp, commandLine, c, count);
             getArgument<uint8_t>(crf, commandLine, c, count);
-            getArgument<uint64_t>(bitrate, commandLine, c, count);
             getArgument<uint64_t>(maxBFrames, commandLine, c, count);
             getArgument<uint64_t>(gopSize, commandLine, c, count);
             getArgument<std::string>(preset, commandLine, c, count);
             getArgument<std::string>(codec, commandLine, c, count);
+            getArgument<std::string>(profile, commandLine, c, count);
             #endif
         }
     }
@@ -542,13 +542,13 @@ struct CommandLine
 
     #ifdef WITH_FFMPEG
     Argument<std::string> codec = {"codec", "FFmpeg codec name (see ffmpeg -codecs).", "libx264", false};
-    Argument<uint8_t> crf = {"crf", "Set the FFmpeg crf (0-51).", 0, false};
-    Argument<uint8_t> qp = {"qp", "Set the FFmpeg qp (0-51).", 0, false};
+    Argument<uint8_t> crf = {"crf", "Set the FFmpeg crf (0-51).", 18, false};
+    Argument<uint8_t> qp = {"qp", "Set the FFmpeg qp (0-51).", 18, false};
     Argument<uint8_t> cq = {"cq", "Set the FFmpeg cp (0-51).", 0, false};
-    Argument<uint64_t> bitrate = {"bitrate", "Set the FFmpeg bitrate.", 2000000, false};
     Argument<uint64_t> maxBFrames = {"maxBFrames", "Set the FFmpeg maxBFrames.", 0, false};
     Argument<uint64_t> gopSize = {"gopSize", "Set the FFmpeg GOP size.", 1, false};
     Argument<std::string> preset = {"preset", "Set the FFmpeg preset.", "slow", false};
+    Argument<std::string> profile = {"profile", "Set the FFmpeg profile.", "main", false};
     #endif
 
     /**
@@ -657,13 +657,13 @@ struct CommandLine
           << "\n"
           << argumentHelp(cq)
           << "\n"
-          << argumentHelp(bitrate)
-          << "\n"
           << argumentHelp(maxBFrames)
           << "\n"
           << argumentHelp(gopSize)
           << "\n"
           << argumentHelp(preset)
+          << "\n"
+          << argumentHelp(profile)
           #endif
           << "\n";
         std::cout << h.str();

include/console.h

@@ -18,6 +18,7 @@
 #include <LuaBool.h>
 #include <visualisationState.h>
 #include <commandLine.h>
+#include <camera.h>
 
 /**
  * @brief Store for lua global state.
@@ -28,6 +29,8 @@ struct LuaExtraSpace
 {
     VisualisationState * visualisationState;
     CommandLine * options;
+    Camera * camera;
+    bool * exit;
 };
 
 /**
@@ -53,18 +56,60 @@ int dispatchVisualisationState(lua_State * lua)
 }
 
 /**
- * @brief Toggle video recording.
+ * @brief A Lua binding in Camera;
  *
+ */
+typedef int (Camera::*CameraMember)(lua_State * lua);
+
+/**
+ * @brief Dispath to a Lua binding of Camera.
+ *
+ * @see LuaExtraSpace.
+ * @tparam function the Lua binding to dispatch.
  * @param lua the Lua context.
  * @return int the return code.
  */
-int lua_toggleRecord(lua_State * lua)
+template <CameraMember function>
+int dispatchCamera(lua_State * lua)
+{
+    LuaExtraSpace * store = *static_cast<LuaExtraSpace**>(lua_getextraspace(lua));
+    Camera * ptr = store->camera;
+    return ((*ptr).*function)(lua);
+}
+
+/**
+ * @brief Start video recording (if not already recording).
+ *
+ * @param lua the Lua context.
+ * @return int the return code.
+ */
+int lua_startRecord(lua_State * lua)
 {
     LuaExtraSpace * extraSpace = *static_cast<LuaExtraSpace**>(lua_getextraspace(lua));
-    extraSpace->visualisationState->toggleRecord(*extraSpace->options);
+    if (!extraSpace->visualisationState->recording)
+    {
+        extraSpace->visualisationState->toggleRecord(*extraSpace->options);
+    }
     return 0;
 }
 
+/**
+ * @brief Stop video recording (if already recording).
+ *
+ * @param lua the Lua context.
+ * @return int the return code.
+ */
+int lua_stopRecord(lua_State * lua)
+{
+    LuaExtraSpace * extraSpace = *static_cast<LuaExtraSpace**>(lua_getextraspace(lua));
+    if (extraSpace->visualisationState->recording)
+    {
+        extraSpace->visualisationState->toggleRecord(*extraSpace->options);
+    }
+    return 0;
+}
+
+
 /**
  * @brief Start playing frames.
  *
@@ -78,6 +123,19 @@ int lua_play(lua_State * lua)
     return 0;
 }
 
+/**
+ * @brief Exit SFOAV.
+ *
+ * @param lua the Lua context.
+ * @return int the return code.
+ */
+int lua_exit(lua_State * lua)
+{
+    LuaExtraSpace * extraSpace = *static_cast<LuaExtraSpace**>(lua_getextraspace(lua));
+    *(extraSpace->exit) = true;
+    return 0;
+}
+
 /**
  * @brief Stop playing frames.
  *
@@ -107,7 +165,8 @@ class Console
     (
         jLog::Log & l,
         VisualisationState * visualisationState,
-        CommandLine * options
+        CommandLine * options,
+        Camera * camera
     )
     : lastCommandOrProgram(""), lastStatus(false), log(l)
     {
@@ -116,6 +175,8 @@ class Console
         luaL_requiref(lua,"sfoav",load_sfoavLib,1);
         extraSpace.visualisationState = visualisationState;
         extraSpace.options = options;
+        extraSpace.camera = camera;
+        extraSpace.exit = &exit;
         *static_cast<LuaExtraSpace**>(lua_getextraspace(lua)) = &extraSpace;
     }
 
@@ -209,6 +270,14 @@ class Console
         return value;
     }
 
+    /**
+     * @brief If sfoav.exit() has been called.
+     *
+     * @return true exit has been requested in Lua.
+     * @return false exit has not been requested in Lua.
+     */
+    bool exitCalled() const { return exit; }
+
 private:
 
     lua_State * lua;
@@ -218,6 +287,7 @@ class Console
     std::stringstream input;
     static std::string stackTrace;
     bool lastStatus;
+    bool exit = false;
 
     jLog::Log & log;
 
@@ -250,7 +320,7 @@ class Console
 
     static int load_sfoavLib(lua_State * lua)
     {
-        luaL_Reg sfoavLib[14] =
+        luaL_Reg sfoavLib[21] =
         {
             {"setAtomColour", &dispatchVisualisationState<&VisualisationState::lua_setAtomColour>},
             {"getAtomColour", &dispatchVisualisationState<&VisualisationState::lua_getAtomColour>},
@@ -262,9 +332,16 @@ class Console
             {"getAtomsNeighbours", &dispatchVisualisationState<&VisualisationState::lua_getAtomsNeighbours>},
             {"setText", &dispatchVisualisationState<&VisualisationState::lua_setText>},
             {"getFrame", &dispatchVisualisationState<&VisualisationState::lua_getFrame>},
-            {"toggleRecord", &lua_toggleRecord},
+            {"startRecording", &lua_startRecord},
+            {"stopRecording", &lua_stopRecord},
             {"play", &lua_play},
             {"pause", &lua_pause},
+            {"cameraPosition", &dispatchCamera<&Camera::lua_cameraPosition>},
+            {"setCameraPosition", &dispatchCamera<&Camera::lua_setCameraPosition>},
+            {"rotateCamera", &dispatchCamera<&Camera::lua_rotateCamera>},
+            {"zoomCamera", &dispatchCamera<&Camera::lua_zoomCamera>},
+            {"inclineCamera", &dispatchCamera<&Camera::lua_inclineCamera>},
+            {"exit", &lua_exit},
             {NULL, NULL}
         };