Add support for saving multiple frames when using animation (#2785)

noclone · web-flow · commit 2dbe5471ec5d · 2026-01-10T09:20:16.000+01:00
Add support for saving multiple frames when using animation with --output and frame template filename
diff --git a/application/F3DStarter.cxx b/application/F3DStarter.cxx
@@ -43,6 +43,7 @@
 #include <algorithm>
 #include <atomic>
 #include <cassert>
+#include <cmath>
 #include <csignal>
 #include <filesystem>
 #include <fstream>
@@ -276,6 +277,34 @@ class F3DStarter::F3DInternals
     image.setMetadata("camera", cameraMetadata.str());
   }
 
+  /**
+   * Save image to file or stdout.
+   * Returns true on success, false on failure (error already logged).
+   */
+  bool saveImage(f3d::image& img, const fs::path& outputPath, bool toStdout)
+  {
+    if (toStdout)
+    {
+      const auto buffer = img.saveBuffer();
+      std::copy(buffer.begin(), buffer.end(), std::ostreambuf_iterator(std::cout));
+      f3d::log::debug("Output image saved to stdout");
+    }
+    else
+    {
+      try
+      {
+        img.save(outputPath);
+      }
+      catch (const f3d::image::write_exception& ex)
+      {
+        f3d::log::error("Could not write output: ", ex.what());
+        return false;
+      }
+      f3d::log::debug("Output image saved to ", outputPath);
+    }
+    return true;
+  }
+
   /**
    * Substitute the following variables in a filename template:
    * - `{app}`: application name (ie. `F3D`)
@@ -289,12 +318,16 @@ class F3DStarter::F3DInternals
    * - `{n}`: auto-incremented number to make filename unique (up to 1000000)
    * - `{n:2}`, `{n:3}`, ...: zero-padded auto-incremented number to make filename unique
    *   (up to 1000000)
+   * - `{frame}`: current animation frame number (when outputting multiple frames)
+   * - `{frame:4}`, `{frame:5}`, ...: zero-padded animation frame number
    */
-  fs::path applyFilenameTemplate(const fs::path& templatePath)
+  fs::path applyFilenameTemplate(
+    const fs::path& templatePath, std::optional<int> frame = std::nullopt)
   {
     constexpr size_t maxNumberingAttempts = 1000000;
     const std::regex numberingRe("(n:?(.*))");
     const std::regex dateRe("date:?(.*)");
+    const std::regex frameRe("(frame:?(.*))");
 
     /* Return a file related string depending on the currently loaded files, or the empty string if
      * a single file is loaded */
@@ -373,6 +406,29 @@ class F3DStarter::F3DInternals
         }
         return formatted;
       }
+      else if (std::regex_match(var, frameRe))
+      {
+        if (!frame.has_value())
+        {
+          f3d::log::warn("{frame} variable can only be used when outputting animation frames");
+          throw f3d::utils::string_template::lookup_error(var);
+        }
+        std::stringstream formattedFrame;
+        const std::string fmt = std::regex_replace(var, frameRe, "$2");
+        try
+        {
+          formattedFrame << std::setfill('0') << std::setw(std::stoi(fmt)) << frame.value();
+        }
+        catch (std::invalid_argument&)
+        {
+          if (!fmt.empty())
+          {
+            f3d::log::warn("ignoring invalid frame format for \"", var, "\"");
+          }
+          formattedFrame << std::setw(0) << frame.value();
+        }
+        return formattedFrame.str();
+      }
       throw f3d::utils::string_template::lookup_error(var);
     };
 
@@ -710,7 +766,7 @@ class F3DStarter::F3DInternals
     }
     else
     {
-      T localOption;
+      T localOption{};
       this->ParseOption(appOptions, name, localOption);
       option = localOption;
     }
@@ -1250,8 +1306,13 @@ int F3DStarter::Start(int argc, char** argv)
       f3d::utils::getEnv("CTEST_F3D_NO_DATA_FORCE_RENDER");
 
     fs::path reference = f3d::utils::collapsePath(this->Internals->AppOptions.Reference);
-    fs::path output = this->Internals->applyFilenameTemplate(
-      f3d::utils::collapsePath(this->Internals->AppOptions.Output));
+    // Check if output template contains {frame} - if so, defer template application
+    const std::string& outputTemplate = this->Internals->AppOptions.Output;
+    const bool hasFrameTemplate =
+      f3d::utils::string_template(outputTemplate).hasVariable(std::regex("frame:?.*"));
+    fs::path output = hasFrameTemplate
+      ? fs::path{}
+      : this->Internals->applyFilenameTemplate(f3d::utils::collapsePath(outputTemplate));
 
     // Render and compare with file if needed
     if (!reference.empty())
@@ -1337,36 +1398,67 @@ int F3DStarter::Start(int argc, char** argv)
       }
     }
     // Render to file if needed
-    else if (!output.empty())
+    else if (!this->Internals->AppOptions.Output.empty())
     {
       if (this->Internals->LoadedFiles.empty() && !noDataForceRender.has_value())
       {
         f3d::log::error("No files loaded, no rendering performed");
         return EXIT_FAILURE;
       }
 
-      f3d::image img = window.renderToImage(this->Internals->AppOptions.NoBackground);
-      this->Internals->addOutputImageMetadata(img);
-
-      if (renderToStdout)
+      if (hasFrameTemplate)
       {
-        const auto buffer = img.saveBuffer();
-        std::copy(buffer.begin(), buffer.end(), std::ostreambuf_iterator(std::cout));
-        f3d::log::debug("Output image saved to stdout");
+        f3d::scene& animScene = this->Internals->Engine->getScene();
+        const auto [minTime, maxTime] = animScene.animationTimeRange();
+
+        const double startTime = this->Internals->AppOptions.AnimationTime.value_or(minTime);
+        const double endTime = maxTime;
+        const double duration = endTime - startTime;
+        const int count = duration > 0
+          ? static_cast<int>(std::ceil(duration * this->Internals->AppOptions.FrameRate)) + 1
+          : 1;
+
+        if (count == 1)
+        {
+          f3d::log::warn("No animation available or animation has zero duration, outputting single "
+                         "frame");
+        }
+
+        const double timeStep = 1.0 / this->Internals->AppOptions.FrameRate;
+
+        f3d::log::info(
+          "Saving ", count, " animation frame(s) from time ", startTime, " to ", endTime);
+
+        for (int frame = 0; frame < count; ++frame)
+        {
+          const double currentTime = startTime + frame * timeStep;
+          animScene.loadAnimationTime(currentTime);
+
+          const fs::path frameOutput = renderToStdout
+            ? fs::path{}
+            : this->Internals->applyFilenameTemplate(
+                f3d::utils::collapsePath(this->Internals->AppOptions.Output), frame);
+
+          f3d::image img = window.renderToImage(this->Internals->AppOptions.NoBackground);
+          this->Internals->addOutputImageMetadata(img);
+
+          if (!this->Internals->saveImage(img, frameOutput, renderToStdout))
+          {
+            return EXIT_FAILURE;
+          }
+        }
+
+        f3d::log::info("Saved ", count, " animation frame(s)");
       }
       else
       {
-        try
-        {
-          img.save(output);
-        }
-        catch (const f3d::image::write_exception& ex)
+        f3d::image img = window.renderToImage(this->Internals->AppOptions.NoBackground);
+        this->Internals->addOutputImageMetadata(img);
+
+        if (!this->Internals->saveImage(img, output, renderToStdout))
         {
-          f3d::log::error("Could not write output: ", ex.what());
           return EXIT_FAILURE;
         }
-
-        f3d::log::debug("Output image saved to ", output);
       }
 
       if (this->Internals->FilesGroups.size() > 1)
diff --git a/application/testing/CMakeLists.txt b/application/testing/CMakeLists.txt
@@ -1310,6 +1310,15 @@ f3d_test(NAME TestOutputOutput DATA cow.vtp ARGS --reference=${CMAKE_BINARY_DIR}
 f3d_test(NAME TestUnsupportedInputOutput DATA unsupportedFile.dummy REGEXP "No files loaded, no rendering performed" NO_BASELINE)
 f3d_test(NAME TestOutputNoBackground DATA cow.vtp ARGS --no-background NO_BASELINE)
 
+# Multi-frame output tests
+f3d_test(NAME TestOutputFrameCount DATA BoxAnimated.gltf ARGS --output=${CMAKE_BINARY_DIR}/Testing/Temporary/TestOutputFrameCount_{frame:4}.png --frame-rate=0.25 REGEXP "Saved 2 animation frame" NO_BASELINE NO_OUTPUT)
+f3d_test(NAME TestOutputFrameCountFrame0 DATA BoxAnimated.gltf ARGS --reference=${CMAKE_BINARY_DIR}/Testing/Temporary/TestOutputFrameCount_0000.png --animation-time=0 DEPENDS TestOutputFrameCount NO_BASELINE)
+f3d_test(NAME TestOutputFrameCountFrame1 DATA BoxAnimated.gltf ARGS --reference=${CMAKE_BINARY_DIR}/Testing/Temporary/TestOutputFrameCount_0001.png --animation-time=3.70833 DEPENDS TestOutputFrameCount NO_BASELINE)
+f3d_test(NAME TestOutputFrameCountNoAnimation DATA cow.vtp ARGS --output=${CMAKE_BINARY_DIR}/Testing/Temporary/static_{frame:4}.png REGEXP "No animation available" NO_BASELINE NO_OUTPUT)
+f3d_test(NAME TestOutputFrameCountInvalidFormat DATA BoxAnimated.gltf ARGS --output=${CMAKE_BINARY_DIR}/Testing/Temporary/invalid_{frame:abc}.png --frame-rate=0.25 REGEXP "ignoring invalid frame format" NO_BASELINE NO_OUTPUT)
+f3d_test(NAME TestOutputFrameCountStartTime DATA BoxAnimated.gltf ARGS --output=${CMAKE_BINARY_DIR}/Testing/Temporary/TestOutputFrameCountStartTime_{frame:4}.png --frame-rate=0.3 --animation-time=2.0 REGEXP "Saving 2 animation frame" NO_BASELINE NO_OUTPUT)
+f3d_test(NAME TestScreenshotFrameVariable DATA cow.vtp ARGS --screenshot-filename=${CMAKE_BINARY_DIR}/Testing/Temporary/screenshot_{frame}.png SCRIPT TestCommandScriptScreenshotFrame.txt REGEXP "{frame} variable can only be used when outputting animation frames" NO_BASELINE)
+
 # Basic record and play test
 f3d_test(NAME TestInteractionRecord DATA cow.vtp ARGS --interaction-test-record=${CMAKE_BINARY_DIR}/Testing/Temporary/TestInteractionRecord.log NO_BASELINE)
 f3d_test(NAME TestInteractionPlay DATA cow.vtp ARGS --interaction-test-play=${CMAKE_BINARY_DIR}/Testing/Temporary/TestInteractionRecord.log DEPENDS TestInteractionRecord NO_BASELINE)
@@ -1687,6 +1696,8 @@ if(NOT WIN32)
   f3d_test(NAME TestInputTooLong ARGS --input=${_f3d_test_invalid_folder}/file.ext REGEXP "File name too long" NO_BASELINE)
   f3d_test(NAME TestReferenceTooLong DATA suzanne.ply ARGS --output=file.png --reference=${_f3d_test_invalid_folder}/file.ext REGEXP "File name too long" NO_BASELINE NO_OUTPUT)
   f3d_test(NAME TestOutputTooLong DATA suzanne.ply ARGS --output=${_f3d_test_invalid_folder}/file.ext REGEXP "File name too long" NO_BASELINE NO_OUTPUT)
+  f3d_test(NAME TestOutputFrameCountTooLong DATA BoxAnimated.gltf ARGS --output=${_f3d_test_invalid_folder}/frame_{frame}.png --frame-rate=0.25 REGEXP "Could not write output" NO_BASELINE NO_OUTPUT)
+  f3d_test(NAME TestOutputFrameCountNoAnimationTooLong DATA cow.vtp ARGS --output=${_f3d_test_invalid_folder}/frame_{frame}.png REGEXP "Could not write output" NO_BASELINE NO_OUTPUT)
   f3d_test(NAME TestOutputWithReferenceTooLong DATA suzanne.ply ARGS --reference=file.png --output=${_f3d_test_invalid_folder}/file.ext REGEXP "File name too long" NO_BASELINE NO_OUTPUT)
   f3d_test(NAME TestOutputWithExistingReferenceTooLong DATA suzanne.ply ARGS --reference=${F3D_SOURCE_DIR}/testing/data/world.png --output=${_f3d_test_invalid_folder}/file.ext REGEXP "File name too long" NO_BASELINE NO_OUTPUT)
 
diff --git a/doc/user/03-OPTIONS.md b/doc/user/03-OPTIONS.md
@@ -10,7 +10,7 @@ The input file or files to read, can also be provided as a positional argument.
 
 ### `--output=<png file>` (_string_)
 
-Instead of showing a render view and render into it, _render directly into a png file_. When used with --ref option, only outputs on failure. If `-` is specified instead of a filename, the PNG file is streamed to the stdout. Can use [template variables](#filename-templating).
+Instead of showing a render view and render into it, _render directly into a png file_. When used with --ref option, only outputs on failure. If `-` is specified instead of a filename, the PNG file is streamed to the stdout. Can use [template variables](#filename-templating). When using the `{frame}` variable, multiple animation frames are exported (see [Exporting animation frames](05-ANIMATIONS.md#exporting-animation-frames)).
 
 ### `--no-background` (_bool_, default: `false`)
 
@@ -569,6 +569,8 @@ The destination filename used by `--output` or to save screenshots using `--scre
 - `{date:format}`: current date as per C++'s `std::put_time` format
 - `{n}`: auto-incremented number to make filename unique (up to 1000000)
 - `{n:2}`, `{n:3}`, ...: zero-padded auto-incremented number to make filename unique (up to 1000000)
+- `{frame}`: frame number when outputting animation frames (see [Animations](05-ANIMATIONS.md))
+- `{frame:4}`, `{frame:5}`, ...: zero-padded frame number when outputting animation frames
 - variable names can be escaped by doubling the braces (eg. use `{{model}}.png` to output `{model}.png` without the model name being substituted)
 
 For example the screenshot filename is configured as `{app}/{model}_{n}.png` by default, meaning that, assuming the model `hello.glb` is being viewed,
diff --git a/doc/user/05-ANIMATIONS.md b/doc/user/05-ANIMATIONS.md
@@ -1,4 +1,4 @@
-# Animations
+#Animations
 
 F3D is able to play animations for any files which contain them.
 Play them either interactively or by selecting a specific time to display.
@@ -29,13 +29,37 @@ Note: A blue bar runs along the bottom of screen to indicate the current time in
 
 F3D animation behavior can be fully controlled from the command line using the following options.
 
-| Options                      | Default             | Description                                     |
-| ---------------------------- | ------------------- | ----------------------------------------------- |
-| \-\-animation\-indices       |                     | Select the animations to play.                  |
-| \-\-animation\-indices=-1    |                     | Play all animations at once (only if supported) |
-| \-\-animation\-speed\-factor | Time Unit = Seconds | Adjust time unit.                               |
-| \-\-animation\-frame\-rate   | 60 FPS              | Adjust animation frame rate.                    |
-| \-\-animation\-time          |                     | Load a specific time value on start.            |
+| Options                      | Default             | Description                                          |
+| ---------------------------- | ------------------- | ---------------------------------------------------- |
+| \-\-animation\-indices       |                     | Select the animations to play.                       |
+| \-\-animation\-indices=-1    |                     | Play all animations at once (only if supported)      |
+| \-\-animation\-speed\-factor | Time Unit = Seconds | Adjust time unit.                                    |
+| \-\-frame\-rate              | 60 FPS              | Adjust animation (and others components) frame rate. |
+| \-\-animation\-time          |                     | Load a specific time value on start.                 |
+
+## Exporting animation frames
+
+F3D can export multiple frames from an animation to image files. To do this, include `{frame}` in the output filename template:
+
+```bash
+f3d example.file --output=frame_{frame:04}.png
+```
+
+This will save frames as `frame_0000.png`, `frame_0001.png`, etc.
+
+The number of frames is determined by `--frame-rate`
+
+```bash
+f3d example.file --output=frame_{frame}.png --frame-rate=30
+```
+
+Use `--animation-time` to start exporting from a specific time instead of the beginning:
+
+```bash
+f3d example.file --output=frame_{frame}.png --frame-rate=10 --animation-time=1.5
+```
+
+See [Filename templating](03-OPTIONS.md#filename-templating) for more template variables.
 
 ## Animation Interactions
 
diff --git a/testing/scripts/TestCommandScriptScreenshotFrame.txt b/testing/scripts/TestCommandScriptScreenshotFrame.txt
@@ -0,0 +1 @@
+take_screenshot
