Added graph plot's central api

Author: Creamy-pie-96

docs/Plot/plot.md

@@ -303,21 +303,29 @@ auto cfg = AnimateConfig()
     .size_px(240, 140)      // Size in pixels (auto-converts to chars)
     .labels("cyan")         // Color for X/Y axis labels
     .ranges("magenta")      // Color for min/max range values
-    .set_title("My Animation");
+    .set_title("My Animation")
+    .loop(false);           // Stop after duration (don't loop)
 ```
 
 **Available configuration methods:**
 
-| Method               | Description                                | Default   |
-| -------------------- | ------------------------------------------ | --------- |
-| `.x_range(min, max)` | X axis range                               | -10 to 10 |
-| `.time(seconds)`     | Animation duration                         | 10.0      |
-| `.framerate(fps)`    | Frames per second                          | 30        |
-| `.size(w, h)`        | Size in terminal characters                | 80×24     |
-| `.size_px(w, h)`     | Size in pixels (Braille converts to chars) | -         |
-| `.labels(color)`     | Color for X/Y axis labels                  | "cyan"    |
-| `.ranges(color)`     | Color for min/max values                   | "magenta" |
-| `.set_title(text)`   | Plot title                                 | ""        |
+| Method               | Description                                          | Default   |
+| -------------------- | ---------------------------------------------------- | --------- |
+| `.x_range(min, max)` | X axis range                                         | -10 to 10 |
+| `.time(seconds)`     | Animation duration                                   | 10.0      |
+| `.framerate(fps)`    | Frames per second                                    | 30        |
+| `.size(w, h)`        | Size in terminal characters                          | 80×24     |
+| `.size_px(w, h)`     | Size in pixels (Braille converts to chars)           | -         |
+| `.labels(color)`     | Color for X/Y axis labels                            | "cyan"    |
+| `.ranges(color)`     | Color for min/max values                             | "magenta" |
+| `.set_title(text)`   | Plot title                                           | ""        |
+| `.loop(bool)`        | Loop animation (true) or stop after duration (false) | true      |
+
+**Signal Handling:**
+
+- Press **Ctrl+C** to stop the animation at any time
+- Terminal state (cursor visibility) is automatically restored via RAII
+- Signal handlers are properly restored after animation ends
 
 ---
 
@@ -411,6 +419,39 @@ int main() {
 
 ---
 
+### Non-Looping Animation
+
+Use `.loop(false)` to make the animation stop after the specified duration:
+
+```cpp
+#include <pythonic/pythonic.hpp>
+using namespace pythonic::plot;
+
+int main() {
+    auto cfg = AnimateConfig()
+        .x_range(-PI, PI)
+        .time(5.0)          // Run for exactly 5 seconds
+        .framerate(30)
+        .size(80, 24)
+        .loop(false);       // Stop after duration (don't repeat)
+
+    animate(cfg,
+        std::make_tuple(
+            [](double t, double x) { return std::sin(x + t); },
+            "green",
+            "wave"
+        )
+    );
+
+    std::cout << "Animation completed after 5 seconds!\n";
+    return 0;
+}
+```
+
+> **Note:** When `.loop(true)` (default), the animation repeats until you press Ctrl+C.
+
+---
+
 ### Complete Animation Example
 
 Here's a comprehensive example demonstrating all features:

include/pythonic/pythonicPlot.hpp

@@ -60,6 +60,7 @@
 #include <thread>
 #include <chrono>
 #include <atomic>
+#include <csignal>
 #include <map>
 #include <set>
 #include <memory>
@@ -1527,6 +1528,9 @@ namespace pythonic
 
         // ==================== Animation Support ====================
 
+        // Global flag for signal handling in animations
+        inline std::atomic<bool> g_animation_interrupted{false};
+
         /**
          * @brief Configuration for plot animations
          *
@@ -1542,7 +1546,7 @@ namespace pythonic
          *   cfg.height = 40;
          *
          *   // Or using the fluent builder pattern:
-         *   auto cfg = AnimateConfig().x_range(-PI, PI).size(120, 40).fps(60);
+         *   auto cfg = AnimateConfig().x_range(-PI, PI).size(120, 40).fps(60).loop(false);
          */
         struct AnimateConfig
         {
@@ -1553,6 +1557,7 @@ namespace pythonic
             int width = 80;                      ///< Width in terminal characters
             int height = 24;                     ///< Height in terminal characters
             bool use_pixels = false;             ///< If true, width/height are pixels (converted to chars)
+            bool loop_animation = true;          ///< If true, loop animation; if false, stop after duration
             std::string label_color = "cyan";    ///< Color for X/Y axis labels
             std::string range_color = "magenta"; ///< Color for min/max range values
             std::string title = "";              ///< Optional title
@@ -1603,6 +1608,11 @@ namespace pythonic
                 title = t;
                 return *this;
             }
+            AnimateConfig &loop(bool l)
+            {
+                loop_animation = l;
+                return *this;
+            }
 
             // Get actual character dimensions (converts pixels if needed)
             int char_width() const { return use_pixels ? (width + 1) / 2 : width; }
@@ -1612,6 +1622,53 @@ namespace pythonic
         // Internal implementation for multi-plot animation
         namespace detail
         {
+            // Signal handler for clean Ctrl+C exit
+            inline void animation_signal_handler(int /*sig*/)
+            {
+                g_animation_interrupted.store(true);
+            }
+
+            // RAII helper to manage terminal state and signal handlers
+            class TerminalStateGuard
+            {
+            public:
+                TerminalStateGuard()
+                {
+                    // Reset interrupt flag
+                    g_animation_interrupted.store(false);
+
+                    // Save old signal handler and install ours
+                    _old_handler = std::signal(SIGINT, animation_signal_handler);
+
+                    // Hide cursor
+                    std::cout << "\033[?25l" << std::flush;
+                }
+
+                ~TerminalStateGuard()
+                {
+                    // Restore cursor
+                    std::cout << "\033[?25h" << std::flush;
+
+                    // Clear screen back to normal position and add newline
+                    std::cout << "\n"
+                              << std::flush;
+
+                    // Restore old signal handler
+                    if (_old_handler != SIG_ERR)
+                    {
+                        std::signal(SIGINT, _old_handler);
+                    }
+                }
+
+                bool interrupted() const
+                {
+                    return g_animation_interrupted.load();
+                }
+
+            private:
+                void (*_old_handler)(int) = SIG_DFL;
+            };
+
             template <typename... PlotEntries>
             inline void animate_impl(const AnimateConfig &cfg, PlotEntries &&...plots)
             {
@@ -1648,57 +1705,71 @@ namespace pythonic
                 (sample_range(plots), ...);
                 fig.ylim(y_min - 0.1 * (y_max - y_min), y_max + 0.1 * (y_max - y_min));
 
-                // Hide cursor
-                std::cout << "\033[?25l" << std::flush;
+                // Use RAII guard for terminal state and signal handling
+                TerminalStateGuard terminal_guard;
 
                 auto frame_time = std::chrono::microseconds(static_cast<int>(1000000.0 / cfg.fps));
                 auto start_time = std::chrono::steady_clock::now();
 
-                try
+                while (!terminal_guard.interrupted())
                 {
-                    while (true)
-                    {
-                        auto now = std::chrono::steady_clock::now();
-                        double t = std::chrono::duration<double>(now - start_time).count();
+                    auto now = std::chrono::steady_clock::now();
+                    double t = std::chrono::duration<double>(now - start_time).count();
 
-                        if (t > cfg.duration)
+                    // Handle looping vs stopping
+                    if (t > cfg.duration)
+                    {
+                        if (cfg.loop_animation)
                         {
                             t = std::fmod(t, cfg.duration);
+                            start_time = now - std::chrono::duration_cast<std::chrono::steady_clock::duration>(
+                                                   std::chrono::duration<double>(t));
                         }
+                        else
+                        {
+                            // Non-looping: stop after duration
+                            break;
+                        }
+                    }
 
-                        fig.clear();
-                        fig.set_time(t);
+                    fig.clear();
+                    fig.set_time(t);
+
+                    auto plot_one = [&](auto &&plot_tuple)
+                    {
+                        auto &f = std::get<0>(plot_tuple);
+                        const auto &color = std::get<1>(plot_tuple);
 
-                        auto plot_one = [&](auto &&plot_tuple)
+                        if constexpr (std::tuple_size_v<std::decay_t<decltype(plot_tuple)>> >= 3)
                         {
-                            auto &f = std::get<0>(plot_tuple);
-                            const auto &color = std::get<1>(plot_tuple);
+                            const auto &label = std::get<2>(plot_tuple);
+                            fig.plot_animated(f, cfg.x_min, cfg.x_max, color, label);
+                        }
+                        else
+                        {
+                            fig.plot_animated(f, cfg.x_min, cfg.x_max, color);
+                        }
+                    };
 
-                            if constexpr (std::tuple_size_v<std::decay_t<decltype(plot_tuple)>> >= 3)
-                            {
-                                const auto &label = std::get<2>(plot_tuple);
-                                fig.plot_animated(f, cfg.x_min, cfg.x_max, color, label);
-                            }
-                            else
-                            {
-                                fig.plot_animated(f, cfg.x_min, cfg.x_max, color);
-                            }
-                        };
+                    (plot_one(plots), ...);
 
-                        (plot_one(plots), ...);
+                    std::cout << "\033[H" << fig.render_to_string();
 
-                        std::cout << "\033[H" << fig.render_to_string();
+                    // Show different message depending on loop setting
+                    if (cfg.loop_animation)
+                    {
                         std::cout << "\nt = " << std::fixed << std::setprecision(2) << t
                                   << "s (Press Ctrl+C to stop)" << std::flush;
-
-                        std::this_thread::sleep_for(frame_time);
                     }
-                }
-                catch (...)
-                {
-                }
+                    else
+                    {
+                        std::cout << "\nt = " << std::fixed << std::setprecision(2) << t
+                                  << "s / " << cfg.duration << "s" << std::flush;
+                    }
 
-                std::cout << "\033[?25h" << std::flush;
+                    std::this_thread::sleep_for(frame_time);
+                }
+                // TerminalStateGuard destructor will restore terminal state
             }
         } // namespace detail
 

plan/next.md

@@ -0,0 +1,39 @@
+🚀 Feature Ideas for Pythonic
+Based on your library's capabilities, here are some exciting feature ideas:
+
+1. Interactive Mode
+Add keyboard controls during animation (pause/resume with spacebar, speed up/slow down with +/-)
+Mouse click to inspect values at specific points
+Real-time parameter adjustment
+2. Plot Types Expansion
+Bar charts - Animated bar graphs with Braille rendering
+Scatter plots - Point clouds with different markers
+Heatmaps - 2D intensity maps using Unicode blocks
+Histograms - Real-time updating histograms
+Polar plots - Circular coordinate system
+3. Multi-Figure Layout
+Subplots - Grid of multiple independent figures (2x2, 3x1, etc.)
+Split screen - Synchronized animations side by side
+Dashboard mode - Multiple plots updating independently
+4. Export Features
+GIF export - Export animations as animated GIFs directly
+SVG export - Vector graphics output for documentation
+ANSI to HTML - Convert terminal output to styled HTML
+5. Data Source Integration
+Live data plotting - Plot from stdin, files, or sockets in real-time
+CSV/JSON import - Load data from files easily
+Streaming mode - Continuous data feed plotting
+6. Visual Enhancements
+Grid lines - Optional background grid
+Annotations - Text labels at specific points
+Markers - Highlight specific data points
+Fill/area under curve - Shaded regions between curves
+Gradient colors - Color transitions along curves
+7. Math/Scientific Features
+FFT visualization - Show frequency spectrum
+Phase space plots - 2D parametric animations
+Vector fields - Arrow plots for derivatives/gradients
+3D surface plots - Isometric projection rendering
+8. Performance & Quality
+Double buffering - Smoother animations with less flicker
+Adaptive resolution - Auto-scale based on terminal size