Add 3d realtim viz example

Author: 1-Bart-1

docs/src/examples.md

@@ -196,8 +196,65 @@ default model, at a much better performance.
 
 ![Oscillating steering input response, simple system](assets/oscillating_steering_simple.png)
 
+## Real-Time 3D Visualization
+
+The `realtime_visualization.jl` example demonstrates how to create a custom simulation loop with real-time 3D visualization. This is useful for:
+- Watching system behavior as it evolves
+- Debugging dynamics issues visually
+- Creating demonstrations and videos
+- Better understanding system response
+
+**Key Features:**
+- Observable-based updates for smooth animation
+- Proper sleep timing to maintain real-time speed
+- Interactive camera control during simulation
+- Configurable visualization frame rate and speed
+
+**Usage:**
+```julia
+include("examples/realtime_visualization.jl")
+```
+
+**How It Works:**
+
+The example creates `Observable` objects for dynamic data (point positions, wing orientations, etc.) and updates them during the simulation loop:
+
+```julia
+# Create observables
+point_positions = Observable([Point3f(p.pos_w) for p in sys_struct.points])
+
+# In simulation loop:
+for step in 1:steps
+    # Run simulation step
+    next_step!(sam; ...)
+
+    # Update visualization
+    if step % plot_interval == 0
+        point_positions[] = [Point3f(p.pos_w) for p in sys_struct.points]
+        sleep(0.001)  # Allow Makie to process events
+    end
+
+    # Sleep to maintain real-time pacing
+    sleep(max(0.0, target_time - elapsed_time))
+end
+```
+
+**Configuration:**
+- `realtime_factor`: Set to 2.0 for 2x speed, 0.5 for half speed, etc.
+- `plot_interval`: Update plot every N steps (higher = better performance)
+- `dt`: Simulation time step
+
+**When to Use:**
+- Use **real-time visualization** when you want to observe behavior as it happens
+- Use **post-simulation plotting** (`plot(sys_struct, log)`) when you want to:
+  - Run simulations faster than real-time
+  - Analyze results in detail after completion
+  - Create publication-quality plots
+
+See: [`realtime_visualization.jl`](https://github.com/OpenSourceAWE/SymbolicAWEModels.jl/blob/main/examples/realtime_visualization.jl)
+
 ## Linearization
-The following example creates a nonlinear system model, finds a steady-state operating point, 
+The following example creates a nonlinear system model, finds a steady-state operating point,
 linearizes the model around this operating point and creates bode plots from inputs (torques)
 to output (heading).
 ```julia

examples/Project.toml

@@ -1,4 +1,6 @@
 [deps]
+ControlSystemsBase = "aaaaaaaa-a6ca-5380-bf3e-84a91bcd477e"
 GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
 KiteUtils = "90980105-b163-44e5-ba9f-8b1c83bb0533"
+ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
 SymbolicAWEModels = "9c9a347c-5289-41db-a9b9-25ccc76c3360"

examples/realtime_visualization.jl

@@ -0,0 +1,206 @@
+# Copyright (c) 2025 Bart van de Lint
+# SPDX-License-Identifier: MPL-2.0
+
+"""
+Real-Time 3D Visualization Example
+
+This example demonstrates how to create a custom simulation loop with real-time
+3D visualization using Makie's Observable system and the existing plot functions.
+
+Key features:
+- Real-time 3D updates using Observables
+- Proper sleep timing to maintain real-time speed
+- Interactive camera control during simulation (hover, click-to-zoom)
+- Configurable visualization frame rate
+- Uses existing plot() functions for consistency
+"""
+
+using GLMakie
+using SymbolicAWEModels
+using KiteUtils
+using LinearAlgebra
+using Printf
+
+# ============================================================================
+# SIMULATION PARAMETERS
+# ============================================================================
+
+dt = 0.05                    # Time step [s]
+total_time = 20.0           # Total simulation time [s]
+vsm_interval = 3            # VSM update interval
+realtime_factor = 1.0       # 1.0 = realtime, 2.0 = 2x speed, 0.5 = half speed
+plot_interval = 1           # Update plot every N steps (1 = every step)
+vector_scale = 1.0         # Scale for wing orientation arrows
+
+# Steering parameters
+steering_freq = 0.5         # Hz - full left-right cycle frequency
+steering_magnitude = 10.0   # Magnitude of steering input [Nm]
+bias = 0.2                  # Steering bias
+
+# ============================================================================
+# INITIALIZE MODEL
+# ============================================================================
+
+println("Initializing model...")
+set_data_path("data")
+set = Settings("system.yaml")
+set.profile_law = 3
+sam = SymbolicAWEModel(set)
+init!(sam)
+find_steady_state!(sam)
+
+sys_struct = sam.sys_struct
+steps = Int(round(total_time / dt))
+num_winches = length(sys_struct.winches)
+
+# ============================================================================
+# CREATE OBSERVABLES AND PLOT SCENE
+# ============================================================================
+
+println("Creating 3D visualization window with observables...")
+
+# Create observables for dynamic visualization
+# Initialize with current system state
+segment_points_obs = Observable(Point3f[])
+point_positions_obs = Observable(Point3f[])
+wing_origins_obs = Observable(Point3f[])
+wing_directions_obs = Observable(Vec3f[])
+
+# Initialize observables with current state
+update_plot_observables!(
+    segment_points_obs, point_positions_obs,
+    wing_origins_obs, wing_directions_obs,
+    sys_struct; vector_scale
+)
+
+# Create 3D scene using existing plot function with observables
+scene = plot(sys_struct;
+             segment_points_obs,
+             point_positions_obs,
+             wing_origins_obs,
+             wing_directions_obs,
+             vector_scale,
+             size=(1400, 900))
+
+# Add text overlays for time and progress directly on the scene
+sim_time_text = Observable("Time: 0.00 s")
+progress_text = Observable("Progress: 0%")
+
+# Add text labels to scene (top-left and top-right)
+text!(scene, sim_time_text, position = Point2f(20, 20), space = :pixel,
+      fontsize = 24, color = :black, align = (:left, :top))
+text!(scene, progress_text, position = Point2f(1380, 20), space = :pixel,
+      fontsize = 20, color = :black, align = (:right, :top))
+
+# Display the scene (non-blocking)
+display(scene)
+
+# ============================================================================
+# PREPARE CONTROL INPUTS
+# ============================================================================
+
+println("Preparing control inputs...")
+set_values = zeros(Float64, steps, num_winches)
+
+for step in 1:steps
+    t = (step-1) * dt
+    steering = steering_magnitude * cos(2π * steering_freq * t + bias)
+    set_values[step, :] = [0.0, steering, -steering]
+end
+
+# ============================================================================
+# RUN REAL-TIME SIMULATION
+# ============================================================================
+
+println("\nStarting real-time simulation...")
+println("  Total time: $(total_time)s")
+println("  Time step: $(dt)s")
+println("  Realtime factor: $(realtime_factor)x")
+println("  Plot update interval: every $(plot_interval) step(s)")
+println("\nSimulation running... (you can interact with the 3D view)\n")
+
+# Initialize state
+logger = SymbolicAWEModels.Logger(length(sys_struct.points), steps+1)
+sys_state = SysState(sam)
+sys_state.time = 0.0
+SymbolicAWEModels.log!(logger, sys_state)
+
+steady_torque = SymbolicAWEModels.calc_steady_torque(sam)
+torque_damp = 0.9
+set_torques = similar(set_values)
+
+# Simulation loop with real-time visualization
+start_time = time()
+for step in 1:steps
+    global steady_torque  # Declare that we're modifying the global variable
+    t = step * dt
+    target_elapsed = t / realtime_factor
+
+    # Calculate control torques
+    steady_torque = torque_damp * steady_torque + (1-torque_damp) * SymbolicAWEModels.calc_steady_torque(sam)
+    set_torques[step, :] = steady_torque .+ set_values[step, :]
+
+    # Simulation step
+    try
+        next_step!(sam; set_values=set_torques[step, :], dt, vsm_interval)
+    catch e
+        if e isa AssertionError
+            @warn "Simulation crashed at t=$t"
+            break
+        else
+            rethrow(e)
+        end
+    end
+
+    # Update system state and log
+    SymbolicAWEModels.update_sys_state!(sys_state, sam)
+    sys_state.time = t
+    SymbolicAWEModels.log!(logger, sys_state)
+
+    # Update visualization
+    if step % plot_interval == 0
+        # Update observables from current system state
+        update_plot_observables!(
+            segment_points_obs, point_positions_obs,
+            wing_origins_obs, wing_directions_obs,
+            sys_struct; vector_scale
+        )
+
+        # Update text overlays
+        sim_time_text[] = @sprintf("Time: %.2f s", t)
+        progress_text[] = @sprintf("Progress: %d%%", round(Int, 100 * step / steps))
+
+        # Force Makie to process events and update display
+        sleep(0.001)
+    end
+
+    # Sleep to maintain real-time pacing
+    actual_elapsed = time() - start_time
+    sleep_time = max(0.0, target_elapsed - actual_elapsed)
+    sleep(sleep_time)
+
+    # Print progress every 10%
+    if step % (steps ÷ 10) == 0
+        @printf("  %.0f%% complete (t=%.1fs)\n", 100 * step / steps, t)
+    end
+end
+
+total_elapsed = time() - start_time
+println("\nSimulation complete!")
+println("  Total runtime: $(round(total_elapsed, digits=2))s")
+println("  Speedup: $(round(total_time / total_elapsed, digits=2))x realtime")
+
+# ============================================================================
+# SAVE AND PLOT RESULTS
+# ============================================================================
+
+println("\nSaving results...")
+mkpath(get_data_path())
+SymbolicAWEModels.save_log(logger, "tmp_realtime_run")
+lg = load_log("tmp_realtime_run")
+
+println("Creating post-simulation plots...")
+fig_results = plot(sam.sys_struct, lg; plot_default=false, plot_heading=true, plot_aoa=true)
+display(fig_results)
+
+println("\nDone! Close the windows to exit.")