Add example for the LuaScale class and fix it at the same time (#3271)

* Change the LuaScale to request a single table as a return value to be consistent with the other Lua transformation types

data/assets/examples/scale/luascale/example.lua

@@ -0,0 +1,12 @@
+-- The `scale` function takes exactly three arguments and returns the three scaling
+-- values (one for each axis) as a single table.
+-- The three parameters are all provided as the number of seconds past the J2000 epoch
+-- (2000-01-01 12:00:00), which can be both fractional numbers as well as negative numbers
+-- for dates earlier than the epoch.
+--  1. `simulationTime` is the value of the in-game clock for the current frame
+--  2. `prevSimulationTime` is the value of the in-game clock for the previous frame
+--  3. `wallTime` is the value of the computer clock as seconds past the epoch
+function scale(simulationTime, prevSimulationTime, wallTime)
+  -- Make the scaling along the x-axis oscillate between -3 and 3 once per second
+  return { 3 * math.sin(simulationTime), 1, 1 }
+end

data/assets/examples/scale/luascale/lua.asset

@@ -0,0 +1,34 @@
+-- Basic
+-- This asset creates a SceneGraphNode that only displays coordinate axes. The sizes of
+-- coordinate axes are determined by executing a Lua file that returns the scaling
+-- parameters to be used as a table.
+--
+-- ```{literalinclude} example.lua
+-- :language: lua
+-- :caption: The script file that is used in this example
+-- ```
+
+local Node = {
+  Identifier = "LuaScale_Example",
+  Transform = {
+    Scale = {
+      Type = "LuaScale",
+      Script = asset.resource("example.lua")
+    }
+  },
+  Renderable = {
+    Type = "RenderableCartesianAxes"
+  },
+  GUI = {
+    Name = "Basic",
+    Path = "/Examples/LuaScale"
+  }
+}
+
+asset.onInitialize(function()
+  openspace.addSceneGraphNode(Node)
+end)
+
+asset.onDeinitialize(function()
+  openspace.removeSceneGraphNode(Node)
+end)

modules/base/scale/luascale.cpp

@@ -41,14 +41,16 @@ namespace {
         "This value is the path to the Lua script that will be executed to compute the "
         "scaling factor for this transformation. The script needs to define a function "
         "'scale' that takes the current simulation time in seconds past the J2000 epoch "
-        "as the first argument, the current wall time as milliseconds past the J2000 "
-        "epoch the second argument and computes the three scaling factors.",
+        "as the first argument, the simulation time in seconds past the J2000 epoch of "
+        "the last frame as the second argument, and the current wall time as "
+        "milliseconds past the J2000 epoch the third argument and computes the three "
+        "scaling factors returned as a table.",
         openspace::properties::Property::Visibility::AdvancedUser
     };
 
     struct [[codegen::Dictionary(LuaScale)]] Parameters {
         // [[codegen::verbatim(ScriptInfo.description)]]
-        std::string script;
+        std::filesystem::path script;
     };
 #include "luascale_codegen.cpp"
 } // namespace
@@ -59,22 +61,23 @@ documentation::Documentation LuaScale::Documentation() {
     return codegen::doc<Parameters>("base_scale_lua");
 }
 
-LuaScale::LuaScale()
+LuaScale::LuaScale(const ghoul::Dictionary& dictionary)
     : _luaScriptFile(ScriptInfo)
-    , _state(ghoul::lua::LuaState::IncludeStandardLibrary::No)
+    , _state(
+        ghoul::lua::LuaState::IncludeStandardLibrary::Yes,
+        ghoul::lua::LuaState::StrictState::No
+    )
 {
-    addProperty(_luaScriptFile);
+    const Parameters p = codegen::bake<Parameters>(dictionary);
 
     _luaScriptFile.onChange([this]() {
         requireUpdate();
         _fileHandle = std::make_unique<ghoul::filesystem::File>(_luaScriptFile.value());
         _fileHandle->setCallback([this]() { requireUpdate(); });
     });
-}
+    addProperty(_luaScriptFile);
 
-LuaScale::LuaScale(const ghoul::Dictionary& dictionary) : LuaScale() {
-    const Parameters p = codegen::bake<Parameters>(dictionary);
-    _luaScriptFile = absPath(p.script).string();
+    _luaScriptFile = p.script.string();
 }
 
 glm::dvec3 LuaScale::scaleValue(const UpdateData& data) const {
@@ -99,13 +102,13 @@ glm::dvec3 LuaScale::scaleValue(const UpdateData& data) const {
     // Second argument is the number of seconds past the J2000 epoch of last frame
     ghoul::lua::push(_state, data.previousFrameTime.j2000Seconds());
 
-    // Second argument is the number of milliseconds past the J2000 epoch in wallclock
+    // Third argument is the number of milliseconds past the J2000 epoch in wallclock
     using namespace std::chrono;
     const auto now = std::chrono::high_resolution_clock::now();
     ghoul::lua::push(_state, duration_cast<milliseconds>(now.time_since_epoch()).count());
 
     // Execute the scaling function
-    const int success = lua_pcall(_state, 2, 1, 0);
+    const int success = lua_pcall(_state, 3, 1, 0);
     if (success != 0) {
         LERRORC(
             "LuaScale",
@@ -113,11 +116,8 @@ glm::dvec3 LuaScale::scaleValue(const UpdateData& data) const {
         );
     }
 
-    const double x = luaL_checknumber(_state, -1);
-    const double y = luaL_checknumber(_state, -2);
-    const double z = luaL_checknumber(_state, -3);
-    lua_settop(_state, 0);
-    return glm::dvec3(x, y, z);
+    const glm::dvec3 scale = ghoul::lua::value<glm::dvec3>(_state);
+    return scale;
 }
 
 } // namespace openspace

modules/base/scale/luascale.h

@@ -38,8 +38,7 @@ namespace documentation { struct Documentation; }
 
 class LuaScale : public Scale {
 public:
-    LuaScale();
-    LuaScale(const ghoul::Dictionary& dictionary);
+    explicit LuaScale(const ghoul::Dictionary& dictionary);
 
     glm::dvec3 scaleValue(const UpdateData& data) const override;