Add redirect_to_animated_gif, bump to version 0.9.0

Author: ziotom78

CMakeLists.txt

@@ -23,6 +23,10 @@ add_executable(example-addpoint
   example-addpoint.cpp
 )
 
+add_executable(example-animated-gif
+  example-animated-gif.cpp
+)
+
 add_executable(example-complex
   example-complex.cpp
   )

README.md

@@ -42,6 +42,7 @@ A few features of this library are the following:
       * [3D plots](#3d-plots)
       * [Vector fields](#vector-fields)
       * [Saving plots to a file](#saving-plots-to-a-file)
+      * [Animations](#animations)
       * [Low-level interface](#low-level-interface)
    * [Similar libraries](#similar-libraries)
    * [Changelog](#changelog)
@@ -482,6 +483,43 @@ Finally, you can use `Gnuplot::redirect_to_dumb` to send the plot to the termina
 
 ![](images/dumb-terminal-example.png)
 
+### Animations
+
+You can plot animations interactively by simply running a `for` loop and adding a delay before plotting the next frame. A better solution is to create an animated GIF file using `Gnuplot::redirect_to_animated_gif`:
+
+```c++
+int main(void) {
+  Gnuplot gnuplot{};
+  std::vector<double> x{1, 2, 3, 4, 5}, y{5, 2, 4, 1, 3};
+
+  std::cout << "Running gplot++ v" << GNUPLOTPP_MAJOR_VERSION << "."
+            << GNUPLOTPP_MINOR_VERSION << "." << GNUPLOTPP_PATCH_VERSION
+            << "\n";
+
+  gnuplot.redirect_to_animated_gif("animation.gif", "800,600", 1000, true);
+
+  for(int i{}; i < (int) x.size(); ++i) {
+	gnuplot.add_point(x[i], y[i]);
+	gnuplot.plot(); // Do the plot
+
+	// In an animation, it is advisable to force the x/y ranges in advance
+	gnuplot.set_xrange(0, 6);
+	gnuplot.set_yrange(0, 6);
+
+	gnuplot.show(); // Add the frame to the GIF file
+  }
+
+  gnuplot.show();
+
+  std::cout << "Press any key to quit...";
+  std::getchar();
+}
+```
+
+Here is the result:
+
+![](images/animation.gif)
+
 ### Low-level interface
 
 You can pass commands to Gnuplot using the method `Gnuplot::sendcommand`:

example-animated-gif.cpp

@@ -0,0 +1,53 @@
+/* Copyright 2020 Maurizio Tomasi
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use, copy,
+ * modify, merge, publish, distribute, sublicense, and/or sell copies
+ * of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#include "gplot++.h"
+#include <cstdio>
+#include <iostream>
+
+int main(void) {
+  Gnuplot gnuplot{};
+  std::vector<double> x{1, 2, 3, 4, 5}, y{5, 2, 4, 1, 3};
+
+  std::cout << "Running gplot++ v" << GNUPLOTPP_MAJOR_VERSION << "."
+            << GNUPLOTPP_MINOR_VERSION << "." << GNUPLOTPP_PATCH_VERSION
+            << "\n";
+
+  gnuplot.redirect_to_animated_gif("animation.gif", "800,600", 1000, true);
+
+  for(int i{}; i < (int) x.size(); ++i) {
+	gnuplot.add_point(x[i], y[i]);
+	gnuplot.plot(); // Do the plot
+
+	// In an animation, it is advisable to force the x/y ranges in advance
+	gnuplot.set_xrange(0, 6);
+	gnuplot.set_yrange(0, 6);
+
+	gnuplot.show(); // Add the frame to the GIF file
+  }
+
+  gnuplot.show();
+
+  std::cout << "Press any key to quit...";
+  std::getchar();
+}

gplot++.h

@@ -28,6 +28,8 @@
  *
  * Version history
  *
+ * - 0.9.0 (2024/11/19): new method `redirect_to_animated_gif`
+ *
  * - 0.8.0 (2024/10/15): new methods `add_point_xerr`,
  *                       `add_point_yerr`, and `add_point_xyerr`,
  *                       and new overloads for functions
@@ -70,7 +72,7 @@
 #include <unistd.h>
 #endif
 
-const unsigned GNUPLOTPP_VERSION = 0x000800;
+const unsigned GNUPLOTPP_VERSION = 0x000900;
 const unsigned GNUPLOTPP_MAJOR_VERSION = (GNUPLOTPP_VERSION & 0xFF0000) >> 16;
 const unsigned GNUPLOTPP_MINOR_VERSION = (GNUPLOTPP_VERSION & 0x00FF00) >> 8;
 const unsigned GNUPLOTPP_PATCH_VERSION = (GNUPLOTPP_VERSION & 0xFF);
@@ -251,6 +253,30 @@ class Gnuplot {
     return sendcommand(os);
   }
 
+  /* Save the plot to an animated GIF. The delay between frames is specified
+   * by the `delay_ms` parameter (in milliseconds). If `loop` is `true` (the
+   * default), the animation will loop indefinitely, otherwise it will just
+   * play once and stop at the last frame.
+   *
+   * Note that frames are saved only once you call `Gnuplot::show()`. Therefore,
+   * if you want to put N frames in your animation, you have to call
+   * `Gnuplot::show()` exactly N times.
+   */
+  bool redirect_to_animated_gif(const std::string &filename,
+								const std::string &size = "800,600",
+								int delay_ms = 50,
+								bool loop = true) {
+	std::stringstream os;
+
+	// Unfortunately, Gnuplot requires the delay to be expressed in units of 1/100 s
+	// instead of the more common unit 1/1000 s, so we need to divide by 10.
+	// We do not support a fixed number of repetitions: either you loop infinitely
+	// or play the animation just once
+	os << "set terminal gif animate delay " << delay_ms / 10 << " loop " << (loop ? 0 : 1) << "\n"
+	   << "set output '" << filename << "'\n";
+	return sendcommand(os);
+  }
+
   /* Send the plot to the terminal or to a text file */
   bool redirect_to_dumb(const std::string &filename = "",
                         unsigned int width = 80,

tests/run_tests.cpp

@@ -65,3 +65,31 @@ TEST_CASE("complex") {
 	CHECK(file_contents.find("X axis") != string::npos);
 	CHECK(file_contents.find("Y axis") != string::npos);
 }
+
+TEST_CASE("animation") {
+  const string file_name{"animation.gif"};
+
+  {
+	Gnuplot plt{};
+
+	plt.redirect_to_animated_gif(file_name);
+
+	vector<double> x{1, 2, 3, 4, 5};
+	vector<double> y{5, 4, 3, 2, 1};
+
+	for(int i{}; i < (int) x.size(); ++i) {
+	  plt.add_point(x[i], y[i]);
+
+	  // Draw the frame
+	  plt.plot();
+
+	  // Add it to the GIF file
+	  plt.show();
+	}
+  }
+
+  wait();
+
+  // No checks, just try to compile the code above and verify that no
+  // errors are issued
+}