Add example scripts for major functions

examples/06_audio_reactive_simulation.py

@@ -0,0 +1,122 @@
+import sys
+import os
+import math
+import random
+import bpy
+
+# 1. Resolve path to include workspace root so pr3tz can be imported
+dir_path = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if dir_path not in sys.path:
+    sys.path.append(dir_path)
+
+import pr3tz
+
+# 2. Register pr3tz addon
+try:
+    if "pr3tz" in sys.modules:
+        import importlib
+        importlib.reload(pr3tz)
+    else:
+        import pr3tz
+
+    pr3tz.register()
+    print("[Pr3tz] Registered successfully!")
+except Exception as e:
+    print(f"[Pr3tz] Failed to register: {e}")
+    sys.exit(1)
+
+# 3. Configure the scene (camera, lights, timeline, etc.)
+pr3tz.setup_scene()
+
+# 4. Clear existing playlist
+scene = bpy.context.scene
+scene.knot_list.clear()
+
+# 5. Add a base knot configuration
+item = scene.knot_list.add()
+item.name = "Audio Reactive Knot"
+item.shape_type = 'TORUS_KNOT'
+item.torus_p = 3
+item.torus_q = 7
+item.torus_R = 2.0
+item.torus_r = 0.8
+item.geo_bDepth = 0.05
+
+# We will modulate minor radius and bevel depth using attenuverters.
+# These variables will act as targets for our keyframed modulators.
+item.mod_torus_r = 0.0  # Starts flat
+item.mod_geo_bDepth = 0.0
+
+item.material_mode = 'PRESET'
+item.shader_id = 'NEON_GLOW'
+item.preset_color = (1.0, 0.0, 0.5)  # Magenta
+item.preset_emission_strength = 2.0
+
+# 6. Fit timeline
+scene.frame_start = 1
+scene.frame_end = 240
+scene.render.fps = 24
+
+# Set up prewarmed materials
+pr3tz.materials.prewarm_materials_and_blends(scene)
+
+# 7. Generate a simulated audio track (bass peaks on beats, high-hat noise)
+# We will write keyframes to global properties to drive the animation.
+glob = scene.knot_globals
+
+# Clear any existing animation on globals
+if glob.animation_data:
+    glob.animation_data.clear()
+if item.animation_data:
+    item.animation_data.clear()
+
+print("Simulating audio analysis and writing keyframes...")
+
+# Loop over the frames and compute simulated audio values
+for frame in range(scene.frame_start, scene.frame_end + 1):
+    # Beat occurs every 24 frames (1 second at 24fps)
+    beat_timer = (frame - 1) % 24
+    
+    # Bass amplitude: sharp spike decaying exponentially
+    bass_amp = math.exp(-beat_timer * 0.15) if beat_timer < 20 else 0.0
+    
+    # High frequency noise (high-hats/snares)
+    random.seed(frame)  # Deterministic per frame
+    treble_amp = 0.15 * random.random() if (frame % 8) < 3 else 0.02
+    
+    # Total reactivity scales the spin/rates
+    glob.reactivity_factor = 1.0 + bass_amp * 4.0
+    glob.keyframe_insert(data_path="reactivity_factor", frame=frame)
+    
+    # Bevel depth thickness spikes with the bass beat
+    glob.global_master_thickness = 1.0 + bass_amp * 0.8
+    glob.keyframe_insert(data_path="global_master_thickness", frame=frame)
+    
+    # Emission spikes on treble highlights
+    glob.global_emission_multiplier = 1.0 + treble_amp * 20.0
+    glob.keyframe_insert(data_path="global_emission_multiplier", frame=frame)
+    
+    # Turbulence (noise) peaks on beats
+    glob.global_turbulence = bass_amp * 0.25
+    glob.keyframe_insert(data_path="global_turbulence", frame=frame)
+    
+    # Hue shifts continuously, jumping slightly on beats
+    glob.global_hue_shift = (frame * 0.002 + bass_amp * 0.05) % 1.0
+    glob.keyframe_insert(data_path="global_hue_shift", frame=frame)
+
+# 8. Force instant geometry generation for current frame
+pr3tz.knot_frame_handler(scene)
+
+print("\n=====================================================================")
+print("Example 6: Audio-Reactive Simulation Loaded!")
+print("=====================================================================")
+print("Generated a 240-frame animation simulating audio beat sync:")
+print(" - 'reactivity_factor' & 'global_turbulence' spike on bass beats (every 24 frames).")
+print(" - 'global_master_thickness' swells on beats.")
+print(" - 'global_emission_multiplier' flashes on high-frequency treble ticks.")
+print(" - 'global_hue_shift' rotates colors over time.")
+print("=====================================================================")
+print("Interact with it in Blender:")
+print(" - Press Space to play.")
+print(" - Look at the Graph Editor to see the custom audio curves keyframed.")
+print("=====================================================================\n")