File: README.md
A mesmerizing 18x18 LED matrix display featuring beautiful animations, games, an
## 🌟 Features
-- **13 Stunning Animation Modules**: From serene water ripples to dynamic plasma effects (15 total animation sequences including flag variations)
-- **Interactive Games**: Self-playing Snake and Conway's Game of Life
+- **35+ Stunning Animation Modules**: From serene water ripples to dynamic plasma effects, mathematical visualizations, and particle systems
+- **Interactive Games**: Self-playing Snake, Strategic Snake AI, and Conway's Game of Life
- **Flag Displays**: Pride, Trans, Ukraine, and USA flags with realistic wave effects
-- **Particle Systems**: Fish schooling, bug swarms, and Matrix rain
-- **Optimized Performance**: Efficient serpentine wiring support and batch pixel updates
+- **Particle Systems**: Fish schooling, bug swarms, Matrix rain, bubbles, and starfields
+- **Mathematical Art**: Mandelbrot/Julia fractals, Lissajous curves, plasma effects, and tunnel visualization
+- **Retro Demoscene Effects**: C64-style copper bars, raster bars, rotozoomer, and lens flare
+- **Ultra-Optimized Performance**: CPU overclocking, lookup tables, and efficient serpentine wiring support
## 🛠️ Hardware Requirements
Raspberry Pi Pico W NeoPixel Strip
## 🎨 Animation Modules
-### 🔦 **search_light**
-Three searchlights hunt for a hidden 2×2 target block. When all lights find the target, the screen erupts in a rainbow celebration!
-- **Parameters**: `delay` (speed), `max_cycles` (number of rounds)
-- **Features**: Dynamic movement, collision detection, growing rainbow effect
-
-### 🌊 **water_ripples**
-Soothing water simulation with gentle ripples spreading across the surface.
-- **Parameters**: `delay` (animation speed), `max_frames` (duration)
-- **Features**: Realistic ripple physics, depth-based coloring, random ripple generation
-
-### 🐛 **bug_swarm**
-A leader bug guides a swarm of followers using flocking behavior.
-- **Parameters**: `delay` (speed), `max_frames` (duration)
-- **Features**: Boids algorithm, trail effects, collision avoidance
-
-### 🐟 **fish_schooling**
-Realistic fish schooling behavior with multiple species swimming together.
-- **Parameters**: `delay` (speed), `max_frames` (duration)
-- **Features**: Species-based coloring, coordinated movement, 3D-like depth effects
-
-### 🏳️ **flag_wave**
-Animated flags with realistic wave motion and lighting effects.
-- **Parameters**: `mode` (pride/trans/ukraine/usa), `delay`, `duration`
-- **Features**: Sine wave distortion, dynamic lighting, smooth color transitions
-
-### 🌈 **plasma** & **plasma_two**
-Mesmerizing plasma effects using mathematical functions.
-- **Parameters**: `delay` (speed), `max_frames` (duration)
-- **Features**: Multiple wave interference, color cycling, blob physics
-
-### ❄️ **blizzard**
-Snowfall animation with wind effects and accumulation.
-- **Parameters**: `delay` (speed), `max_frames` (duration)
-- **Features**: Wind gusts, varying snowflake sizes, ground accumulation
-
-### 💊 **the_matrix**
-The iconic Matrix digital rain effect.
-- **Parameters**: `delay` (speed), `max_frames` (duration)
-- **Features**: Trailing fade, random character changes, varying drop speeds
-
-### 📀 **dvd_screen_saver**
-Classic bouncing DVD logo that changes color on each wall hit.
-- **Parameters**: `delay` (speed), `max_frames` (duration)
-- **Features**: Physics simulation, spin effects, color cycling
-
-### 🧱 **falling_blocks**
-Tetris-inspired falling blocks that stack and clear when reaching the top.
-- **Parameters**: `delay` (speed), `max_frames` (duration)
-- **Features**: Collision detection, stacking physics, auto-reset
-
-### 🐍 **snake_game**
-Self-playing Snake game with intelligent AI.
-- **Parameters**: `delay` (speed), `show_log` (debug output)
-- **Features**: Pathfinding AI, wall avoidance, oscillation prevention
-
-### 🧬 **john_conways_game_of_life**
-Conway's Game of Life with colorful mutations and visitor system.
-- **Parameters**: `delay`, `allow_mutations`, `allow_visitors`, `max_generations`
-- **Features**: Color inheritance, mutation system, automatic restart, visitor injection
+### **Particle & Natural Effects**
+
+#### 🌊 **water_ripples**
+Soothing underwater scene with gentle ripples spreading across the surface. Features realistic ripple physics, depth-based blue-green coloring, and random ripple generation for a peaceful aquatic atmosphere.
+
+#### 🫧 **bubbles**
+Endless floating bubbles rising through water with realistic physics. Bubbles vary in size and speed, with natural horizontal drift and shimmer effects. Includes occasional surface bubble bursts.
+
+#### ❄️ **blizzard**
+Immersive snowfall animation with wind effects and ground accumulation. Features dynamic wind gusts, varying snowflake sizes, realistic physics, and snow buildup patterns.
+
+#### 🔥 **fire**
+Realistic fire simulation with turbulent flames and ember particles. Uses cellular automata for natural flame behavior with heat diffusion and particle physics.
+
+#### ⭐ **starfield**
+Ultra-optimized 3D starfield with stars moving toward the viewer. Features parallax motion, varying star brightness, and smooth depth-based movement for a space travel effect.
+
+#### 🌋 **lava_lamp**
+Relaxing lava lamp effect with realistic blob physics. Features temperature-based buoyancy, organic blob shapes, merging/splitting behavior, and warm ambient colors.
+
+### **Aquatic & Marine Life**
+
+#### 🐟 **fish_schooling**
+Realistic fish schooling behavior with multiple species swimming in coordinated groups. Features boids flocking algorithm, species-based coloring, and 3D-like depth effects.
+
+#### 🐠 **fishtank**
+Complete aquarium simulation with sandy bottom, shimmering blue water, rising bubbles, and fish swimming by. Non-uniform fish patterns create a realistic underwater environment.
+
+#### 🐛 **bug_swarm**
+A leader bug guides a swarm of followers using advanced flocking behavior. Features boids algorithm, dynamic trail effects, collision avoidance, and emergent group behaviors.
+
+### **Games & Interactive**
+
+#### 🐍 **snake_game**
+Classic self-playing Snake game with intelligent pathfinding AI. Features wall avoidance, food-seeking behavior, and oscillation prevention for extended gameplay.
+
+#### 🐍 **strategic_snake**
+Advanced AI Snake that uses edge-following pathfinding to build the longest possible tail. Features A* pathfinding, trap avoidance, and strategic movement for maximum scores.
+
+#### 🧬 **john_conways_game_of_life**
+Conway's Game of Life with colorful mutations and visitor injection system. Features color inheritance, dynamic mutation rates, automatic restart, and population management.
+
+### **Mathematical & Fractal Art**
+
+#### 🌀 **mandelbrot_julia**
+Beautiful Mandelbrot and Julia set fractals with smooth color transitions. Features deep ocean color themes, zooming effects, and mathematically precise rendering.
+
+#### 🌊 **plasma** & **plasma_two** & **diamond_plasma** & **ripple_plasma** & **spiral_plasma**
+Multiple plasma effect variations using mathematical wave functions. Each features unique interference patterns, color cycling, blob physics, and hypnotic visual effects.
+
+#### 📐 **lissajous_curves**
+Animated Lissajous curves showing mathematical relationships between sine waves. Features parametric equations, color trails, and smooth curve evolution.
+
+#### 🌀 **moire_patterns**
+Hypnotic moiré interference patterns created by overlapping mathematical grids. Features rotation effects, scaling animations, and optical illusion phenomena.
+
+#### 🧬 **dna_helix**
+Double helix DNA structure with rotating base pairs and genetic code visualization. Features scientifically accurate structure, smooth rotation, and nucleotide coloring.
+
+### **Classic Demoscene Effects**
+
+#### 🌈 **tunnel**
+Classic 3D tunnel effect with rainbow colors and smooth animation. Features perspective transformation, texture mapping, and psychedelic color cycling.
+
+#### 🔧 **rotozoomer**
+Rotating and zooming texture effects inspired by classic demos. Features mathematical transformation matrices, texture sampling, and smooth motion.
+
+#### 🌈 **copper_bars**
+C64-style horizontal copper bars with smooth color gradients. Features classic demoscene aesthetics, color interpolation, and nostalgic 8-bit styling.
+
+#### 📺 **raster_bars**
+Retro raster bar effects with sine wave motion and color cycling. Features smooth gradients, wave distortion, and classic computer demo aesthetics.
+
+#### ✨ **lens_flare**
+Realistic lens flare effects with multiple light sources and optical artifacts. Features bloom effects, chromatic aberration, and cinematic lighting.
+
+#### 💻 **c64_demoscene**
+Comprehensive Commodore 64 demoscene tribute with multiple classic effects. Features authentic color palettes, bitmap fonts, and retro visual styling.
+
+### **Text & Communication**
+
+#### 📜 **sine_scrollers**
+Smooth scrolling text with sine wave motion displaying "hello world! hello apple! oh hi mark!" Features classic demo-style text animation and wave distortion.
+
+#### 📱 **qr_renderer**
+QR code generation and display with error correction. Features dynamic code generation, proper formatting, and scannable output.
+
+#### 🍎 **apple_event_sep_2025**
+Special Apple-themed animation for events. Features Apple logo aesthetics, smooth transitions, and corporate branding elements.
+
+### **Abstract & Artistic**
+
+#### 🎯 **vector_balls**
+Animated vector balls with physics simulation and trail effects. Features collision detection, momentum conservation, and smooth particle motion.
+
+#### 🔦 **search_light**
+Three searchlights hunting for hidden targets with celebration effects. Features dynamic movement patterns, collision detection, and rainbow victory animations.
+
+#### 📀 **dvd_screen_saver**
+Classic bouncing DVD logo with color changes on wall hits. Features accurate physics simulation, spin effects, and nostalgia-inducing movement.
+
+#### 🧱 **falling_blocks**
+Tetris-inspired falling blocks that stack and clear. Features collision detection, block rotation, stacking physics, and automatic reset functionality.
+
+#### 💊 **the_matrix**
+Iconic Matrix digital rain effect with trailing characters. Features authentic green color scheme, random character generation, and fade effects.
+
+#### 🏳️ **flag_wave**
+Animated flags (Pride, Trans, Ukraine, USA) with realistic wave physics. Features sine wave distortion, dynamic lighting, and smooth patriotic color transitions.
## 📁 Project Structure
```
/CIRCUITPY/
-├── code.py # Main entry point
-├── lib/ # CircuitPython libraries
+├── code.py # Main entry point with animation orchestrator
+├── lib/ # CircuitPython libraries
│ ├── neopixel.mpy
│ └── adafruit_pixelbuf.mpy
-└── matrix_modules/ # Animation modules
+└── matrix_modules/ # 35+ Animation modules
├── __init__.py
- ├── utils.py # Shared utilities
- ├── blizzard.py
- ├── bug_swarm.py
- ├── dvd_screen_saver.py
- ├── falling_blocks.py
- ├── fish_schooling.py
- ├── flag_wave.py
- ├── john_conways_game_of_life.py
- ├── plasma.py
- ├── plasma_two.py
- ├── search_light.py
- ├── snake_game.py
- ├── the_matrix.py
- └── water_ripples.py
+ ├── constants.py # Ultra-optimized lookup tables & CPU overclocking
+ ├── utils.py # Shared utilities & performance functions
+ │
+ ├── # Particle & Natural Effects
+ ├── water_ripples.py # Soothing water simulation
+ ├── bubbles.py # Floating bubbles with physics
+ ├── blizzard.py # Snow simulation with wind
+ ├── fire.py # Realistic fire simulation
+ ├── starfield.py # 3D star travel effect
+ ├── lava_lamp.py # Relaxing lava lamp physics
+ │
+ ├── # Aquatic & Marine Life
+ ├── fish_schooling.py # Boids flocking algorithm
+ ├── fishtank.py # Complete aquarium simulation
+ ├── bug_swarm.py # Leader-follower swarm behavior
+ │
+ ├── # Games & Interactive
+ ├── snake_game.py # Classic AI Snake game
+ ├── strategic_snake.py # Advanced pathfinding Snake
+ ├── john_conways_game_of_life.py # Game of Life with mutations
+ │
+ ├── # Mathematical & Fractal Art
+ ├── mandelbrot_julia.py # Fractal visualization
+ ├── plasma.py # Classic plasma effect
+ ├── plasma_two.py # Alternative plasma algorithm
+ ├── diamond_plasma.py # Diamond-pattern plasma
+ ├── ripple_plasma.py # Ultra-optimized ripples
+ ├── spiral_plasma.py # Spiral interference patterns
+ ├── lissajous_curves.py # Parametric curve animation
+ ├── moire_patterns.py # Optical interference effects
+ ├── dna_helix.py # Double helix visualization
+ │
+ ├── # Classic Demoscene Effects
+ ├── tunnel.py # 3D tunnel with rainbow colors
+ ├── rotozoomer.py # Rotating/zooming textures
+ ├── copper_bars.py # C64-style color gradients
+ ├── raster_bars.py # Retro raster effects
+ ├── lens_flare.py # Cinematic lighting effects
+ ├── c64_demoscene.py # Comprehensive C64 tribute
+ │
+ ├── # Text & Communication
+ ├── sine_scrollers.py # Wave-distorted scrolling text
+ ├── qr_renderer.py # QR code generation
+ ├── apple_event_sep_2025.py # Apple-themed animation
+ │
+ └── # Abstract & Artistic
+ ├── vector_balls.py # Physics-based particle motion
+ ├── search_light.py # Target-hunting searchlights
+ ├── dvd_screen_saver.py # Classic bouncing logo
+ ├── falling_blocks.py # Tetris-inspired blocks
+ ├── the_matrix.py # Matrix digital rain
+ └── flag_wave.py # Animated flags with physics
```
## 🔧 Customization
def my_animation(pixels, width, height, delay=0.1, **kwargs):
```
3. Import and add to the main loop in `code.py`
-## ⚡ Performance Tips
+## ⚡ Performance Optimizations
+
+This system implements **ultra-aggressive performance optimizations**:
+
+### **Hardware Overclocking**
+- **CPU Speed**: Overclocked from 125MHz to **350MHz** (2.8x boost!)
+- **Memory**: Optimized memory access patterns for maximum bandwidth
+- **Real-time Performance**: Achieving 50+ FPS on most animations
+
+### **Software Optimizations**
+- **Ultra-Fast Lookup Tables**: Pre-calculated sine, cosine, and square root functions
+- **Serpentine Pixel Mapping**: Pre-calculated LED coordinate transformations
+- **Batch Pixel Updates**: Use `auto_write=False` and single `pixels.show()` calls
+- **Mathematical Optimizations**: Integer math where possible, avoiding floating-point operations
+
+### **Animation Tuning**
+- Keep `delay=0.0` for maximum frame rates
+- Use `max_frames` parameters to control animation duration
+- Pre-calculate complex values outside render loops
+- Leverage the ultra-fast utility functions: `ultra_sin()`, `ultra_cos()`, `ultra_sqrt()`
-- Keep `delay` low (0.0-0.01) for smooth animations
-- Use `auto_write=False` for batch updates
-- Call `pixels.show()` once per frame
-- Pre-calculate values outside animation loops
+### **Performance Monitoring**
+All animations include start/finish logging with:
+- Frame count tracking
+- Duration measurement
+- Automatic FPS calculation
+- Performance regression detection
## 🐛 Troubleshooting
This project is licensed under the MIT License - see the LICENSE file for detail
---
-*Built with ❤️ for the LED art community*
+*Built with ❤️ for the LED art community*
\
