add per-series opacity/color controls and monte-carlo alpha example

watsonryan · watsonryan · commit 72d53a513042 · 2026-02-25T15:41:53.000Z
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -65,6 +65,9 @@ if(BUILD_EXAMPLES)
 
   add_executable(three_line_ieee_example examples/three_line_ieee_example.cpp)
   target_link_libraries(three_line_ieee_example PRIVATE gnuplotpp::gnuplotpp)
+
+  add_executable(monte_carlo_alpha_example examples/monte_carlo_alpha_example.cpp)
+  target_link_libraries(monte_carlo_alpha_example PRIVATE gnuplotpp::gnuplotpp)
 endif()
 
 if(BUILD_TESTING)
diff --git a/README.md b/README.md
@@ -61,9 +61,10 @@ flowchart LR
 When using `IEEE_SingleColumn` or `IEEE_DoubleColumn`, renderer behavior is tightened to print-safe defaults:
 
 - 8.5 pt Times-style text defaults
-- monochrome plotting (`set monochrome`)
+- monochrome plotting by default (`set monochrome`)
 - dashed line-style differentiation per series (`dt 1..N`)
-- SciencePlots-like axis defaults: inward mirrored ticks, visible minor ticks, thin 0.5 axis/grid strokes
+- per-series color/opacity overrides disable global monochrome automatically
+- SciencePlots-like axis defaults: visible minor ticks, thin 0.5 axis/grid strokes
 - vector-first outputs (`PDF`, `SVG`, `EPS`)
 
 ## Examples
@@ -72,6 +73,7 @@ When using `IEEE_SingleColumn` or `IEEE_DoubleColumn`, renderer behavior is tigh
 ./build/dev-debug/two_window_example --out out/two_window
 ./build/dev-debug/layout_2x2_example --out out/layout_2x2
 ./build/dev-debug/three_line_ieee_example --out out/three_line_ieee
+./build/dev-debug/monte_carlo_alpha_example --out out/monte_carlo_alpha
 ```
 
 ### Annotated IEEE Example
diff --git a/docs/PLOT_CONTROLS.md b/docs/PLOT_CONTROLS.md
@@ -73,6 +73,10 @@ s.type = gnuplotpp::SeriesType::Line; // Line, Scatter, ErrorBars, Band
 s.label = "SRIF";
 s.has_line_width = true;
 s.line_width_pt = 1.6;
+s.has_color = true;
+s.color = "#000000";       // RGB hex
+s.has_opacity = true;
+s.opacity = 0.15;          // [0,1], converted to ARGB for gnuplot
 ```
 
 ## Data and Rendering
@@ -91,6 +95,28 @@ auto result = fig.save("out/my_run/figures");
 
 ## Figure Recipes
 
+### 0) Monte-Carlo Density (Many Lines, No Legend, Low Opacity)
+
+```cpp
+gnuplotpp::AxesSpec ax;
+ax.legend = false;
+ax.grid = true;
+fig.axes(0).set(ax);
+
+for (int k = 0; k < 1000; ++k) {
+  gnuplotpp::SeriesSpec s;
+  s.type = gnuplotpp::SeriesType::Line;
+  s.label = "";
+  s.has_line_width = true;
+  s.line_width_pt = 0.5;
+  s.has_color = true;
+  s.color = "#000000";
+  s.has_opacity = true;
+  s.opacity = 0.08;
+  fig.axes(0).add_series(s, t, y_mc[k]);
+}
+```
+
 ### 1) Single IEEE Plot (1x1)
 
 ```cpp
@@ -152,8 +178,20 @@ For each render:
 - `tmp/ax*_series*.dat`
 - `tmp/gnuplot.log`
 
+## Object Transparency (Native gnuplot Commands)
+
+Use `AxesSpec::gnuplot_commands` for transparent filled objects:
+
+```cpp
+ax.gnuplot_commands = {
+  "set object 1 rect from graph 0.05,0.80 to graph 0.35,0.95 "
+  "fc rgb '#000000' fs transparent solid 0.10 noborder"
+};
+```
+
 ## Existing End-to-End Examples
 
 - `examples/two_window_example.cpp`
 - `examples/layout_2x2_example.cpp`
 - `examples/three_line_ieee_example.cpp`
+- `examples/monte_carlo_alpha_example.cpp`
diff --git a/examples/monte_carlo_alpha_example.cpp b/examples/monte_carlo_alpha_example.cpp
@@ -0,0 +1,80 @@
+#include "gnuplotpp/gnuplot_backend.hpp"
+#include "gnuplotpp/logging.hpp"
+#include "gnuplotpp/plot.hpp"
+#include "gnuplotpp/presets.hpp"
+
+#include <filesystem>
+#include <random>
+#include <string>
+#include <vector>
+
+int main(int argc, char** argv) {
+  using namespace gnuplotpp;
+
+  std::filesystem::path out_dir = "out/monte_carlo_alpha_example";
+  for (int i = 1; i < argc; ++i) {
+    const std::string arg = argv[i];
+    if (arg == "--out" && i + 1 < argc) {
+      out_dir = argv[++i];
+    }
+  }
+
+  FigureSpec fs;
+  fs.preset = Preset::IEEE_DoubleColumn;
+  apply_preset_defaults(fs);
+  fs.rows = 1;
+  fs.cols = 1;
+  fs.formats = {OutputFormat::Pdf, OutputFormat::Svg, OutputFormat::Eps};
+  fs.title = "Monte Carlo Ensemble (N=1000)";
+
+  Figure fig(fs);
+
+  AxesSpec ax;
+  ax.xlabel = "t [s]";
+  ax.ylabel = "x(t)";
+  ax.grid = true;
+  ax.legend = false;
+  fig.axes(0).set(ax);
+
+  std::vector<double> t;
+  t.reserve(220);
+  for (int i = 0; i < 220; ++i) {
+    t.push_back(0.1 * static_cast<double>(i));
+  }
+
+  std::mt19937_64 rng(123456ULL);
+  std::normal_distribution<double> noise(0.0, 0.12);
+  for (int k = 0; k < 1000; ++k) {
+    std::vector<double> y;
+    y.reserve(t.size());
+
+    double state = 0.0;
+    for (double x_sample : t) {
+      (void)x_sample;
+      state = 0.985 * state + noise(rng);
+      y.push_back(state);
+    }
+
+    SeriesSpec s;
+    s.type = SeriesType::Line;
+    s.has_line_width = true;
+    s.line_width_pt = 0.5;
+    s.has_color = true;
+    s.color = "#000000";
+    s.has_opacity = true;
+    s.opacity = 0.08;
+    fig.axes(0).add_series(s, t, y);
+  }
+
+  fig.set_backend(make_gnuplot_backend());
+  const auto result = fig.save(out_dir / "figures");
+  if (!result.ok) {
+    gnuplotpp::log::Error("plot render incomplete: ", result.message);
+    gnuplotpp::log::Error("script: ", result.script_path.string());
+    return 1;
+  }
+  for (const auto& output : result.outputs) {
+    gnuplotpp::log::Info("output: ", output.string());
+  }
+  return 0;
+}
diff --git a/include/gnuplotpp/plot.hpp b/include/gnuplotpp/plot.hpp
@@ -84,6 +84,15 @@ struct SeriesSpec {
   std::string label;
   bool has_line_width = false;
   double line_width_pt = 1.0;
+  /** @brief Optional explicit line/point color (e.g., "#112233"). */
+  bool has_color = false;
+  std::string color = "#000000";
+  /**
+   * @brief Optional opacity in [0, 1].
+   * @note Backends map this to gnuplot ARGB color strings when possible.
+   */
+  bool has_opacity = false;
+  double opacity = 1.0;
 };
 
 /** @brief In-memory series samples used by backends for emission/rendering. */
diff --git a/src/figure.cpp b/src/figure.cpp
@@ -12,6 +12,9 @@ void Axes::add_series(const SeriesSpec& spec,
   if (x.size() != y.size()) {
     throw std::invalid_argument("x and y must have the same length");
   }
+  if (spec.has_opacity && (spec.opacity < 0.0 || spec.opacity > 1.0)) {
+    throw std::invalid_argument("series opacity must be in [0, 1]");
+  }
 
   SeriesData data;
   data.spec = spec;
diff --git a/src/gnuplot_backend.cpp b/src/gnuplot_backend.cpp
@@ -6,6 +6,7 @@
 #include <filesystem>
 #include <fstream>
 #include <iomanip>
+#include <cmath>
 #include <sstream>
 #include <string>
 #include <utility>
@@ -72,6 +73,46 @@ bool is_ieee_preset(const Preset preset) {
   return preset == Preset::IEEE_SingleColumn || preset == Preset::IEEE_DoubleColumn;
 }
 
+bool is_hex_digit(const char c) {
+  return (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F');
+}
+
+bool is_hex_rgb(const std::string& color) {
+  if (color.size() != 7 || color.front() != '#') {
+    return false;
+  }
+  for (std::size_t i = 1; i < color.size(); ++i) {
+    if (!is_hex_digit(color[i])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+std::string clamp_opacity_color(const std::string& color, const double opacity) {
+  const double clamped = std::clamp(opacity, 0.0, 1.0);
+  if (!is_hex_rgb(color)) {
+    return color;
+  }
+  const int alpha =
+      static_cast<int>(std::lround(clamped * 255.0));  // gnuplot expects AARRGGBB
+  std::ostringstream os;
+  os << "#" << std::hex << std::setfill('0') << std::nouppercase << std::setw(2) << alpha
+     << color.substr(1);
+  return os.str();
+}
+
+bool has_custom_color_or_opacity(const Figure& fig) {
+  for (const auto& axis : fig.all_axes()) {
+    for (const auto& series : axis.series()) {
+      if (series.spec.has_color || series.spec.has_opacity) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 std::string terminal_for(OutputFormat format, const FigureSpec& spec) {
   std::ostringstream os;
   os << std::fixed << std::setprecision(3);
@@ -109,32 +150,50 @@ std::string with_clause(const SeriesData& series,
       series.spec.has_line_width ? series.spec.line_width_pt : style.line_width_pt;
   const bool ieee = is_ieee_preset(preset);
   const int dt = static_cast<int>(series_idx % 7U) + 1;
+  std::string color;
+  if (series.spec.has_color) {
+    color = series.spec.color;
+  } else if (ieee || series.spec.has_opacity) {
+    color = "#000000";
+  }
+  if (series.spec.has_opacity) {
+    color = clamp_opacity_color(color, series.spec.opacity);
+  }
 
   std::ostringstream os;
   os << std::fixed << std::setprecision(3);
   switch (series.spec.type) {
     case SeriesType::Line:
       os << "with lines lw " << std::max(0.5, line_width);
+      if (!color.empty()) {
+        os << " lc rgb '" << color << "'";
+      }
       if (ieee) {
-        os << " lc rgb '#000000' dt " << dt;
+        os << " dt " << dt;
       }
       break;
     case SeriesType::Scatter:
       os << "with points pt 7 ps " << std::max(0.5, style.point_size);
-      if (ieee) {
-        os << " lc rgb '#000000'";
+      if (!color.empty()) {
+        os << " lc rgb '" << color << "'";
       }
       break;
     case SeriesType::ErrorBars:
       os << "with yerrorbars lw " << std::max(0.5, line_width);
+      if (!color.empty()) {
+        os << " lc rgb '" << color << "'";
+      }
       if (ieee) {
-        os << " lc rgb '#000000' dt " << dt;
+        os << " dt " << dt;
       }
       break;
     case SeriesType::Band:
       os << "with lines lw " << std::max(0.5, line_width);
+      if (!color.empty()) {
+        os << " lc rgb '" << color << "'";
+      }
       if (ieee) {
-        os << " lc rgb '#000000' dt " << dt;
+        os << " dt " << dt;
       }
       break;
   }
@@ -147,6 +206,7 @@ void emit_plot_body(std::ostream& os,
   const auto& spec = fig.spec();
   const auto& all_axes = fig.all_axes();
   const bool ieee = is_ieee_preset(spec.preset);
+  const bool custom_color_or_opacity = has_custom_color_or_opacity(fig);
   const double tick_font_pt = ieee ? 8.0 : spec.style.font_pt;
   const double label_font_pt = ieee ? 8.5 : spec.style.font_pt;
   const double title_font_pt = ieee ? 8.5 : spec.style.font_pt;
@@ -161,7 +221,7 @@ void emit_plot_body(std::ostream& os,
   os << "set ytics font '" << esc(spec.style.font) << "," << tick_font_pt << "'\n";
   os << "set format x '%.2g'\n";
   os << "set format y '%.2g'\n";
-  if (ieee) {
+  if (ieee && !custom_color_or_opacity) {
     os << "set monochrome\n";
   }
   os << "set key noopaque\n";
diff --git a/tests/api_test.cpp b/tests/api_test.cpp
@@ -3,6 +3,7 @@
 
 #include <cassert>
 #include <memory>
+#include <stdexcept>
 #include <vector>
 
 namespace {
@@ -37,6 +38,15 @@ int main() {
   const std::vector<double> x{0.0, 1.0, 2.0};
   const std::vector<double> y{1.0, 2.0, 3.0};
   fig.axes(0, 0).add_series(SeriesSpec{.label = "line"}, x, y);
+  bool threw = false;
+  try {
+    fig.axes(0, 0).add_series(SeriesSpec{.label = "bad", .has_opacity = true, .opacity = 1.2},
+                              x,
+                              y);
+  } catch (const std::invalid_argument&) {
+    threw = true;
+  }
+  assert(threw);
 
   assert(fig.axes(0, 0).series().size() == 1U);
   const auto no_backend = fig.save("out");
diff --git a/tests/gnuplot_backend_test.cpp b/tests/gnuplot_backend_test.cpp
@@ -45,8 +45,18 @@ int main() {
   const std::vector<double> t{0.0, 1.0, 2.0};
   const std::vector<double> ep{2.0, 1.0, 0.5};
   const std::vector<double> ev{0.4, 0.3, 0.2};
+  const std::vector<double> ep_mc{1.8, 1.1, 0.6};
 
   fig.axes(0, 0).add_series(SeriesSpec{.label = "SRIF"}, t, ep);
+  fig.axes(0, 0).add_series(SeriesSpec{.label = "MC",
+                                       .has_line_width = true,
+                                       .line_width_pt = 0.6,
+                                       .has_color = true,
+                                       .color = "#000000",
+                                       .has_opacity = true,
+                                       .opacity = 0.25},
+                            t,
+                            ep_mc);
   fig.axes(0, 1).add_series(SeriesSpec{.label = "SRIF"}, t, ev);
 
   const auto out_dir = std::filesystem::temp_directory_path() / "gnuplotpp_backend_test";
@@ -62,8 +72,9 @@ int main() {
   const auto script = read_file(result.script_path);
   assert(script.find("set multiplot layout 1,2") != std::string::npos);
   assert(script.find("set terminal pdfcairo") != std::string::npos);
-  assert(script.find("set monochrome") != std::string::npos);
+  assert(script.find("set monochrome") == std::string::npos);
   assert(script.find("dt 1") != std::string::npos);
+  assert(script.find("lc rgb '#40000000'") != std::string::npos);
   assert(script.find("plot") != std::string::npos);
 
   const auto data0 = out_dir / "tmp" / "ax0_series0.dat";

Original file line number	Diff line number	Diff line change
`@@ -12,6 +12,9 @@ void Axes::add_series(const SeriesSpec& spec,`
`12`	`12`	`if (x.size() != y.size()) {`
`13`	`13`	`throw std::invalid_argument("x and y must have the same length");`
`14`	`14`	`}`
	`15`	`+ if (spec.has_opacity && (spec.opacity < 0.0 \|\| spec.opacity > 1.0)) {`
	`16`	`+ throw std::invalid_argument("series opacity must be in [0, 1]");`
	`17`	`+ }`
`15`	`18`
`16`	`19`	`SeriesData data;`
`17`	`20`	`data.spec = spec;`