Monorepo for Aesthetic.Computer
aesthetic.computer
1# 🌪️ Suck Function - Complete Technical Documentation
2
3*Advanced radial pixel transformation with fluid dynamics*
4
5## Overview
6
7The `suck` function represents a major advancement in KidLisp's transformation capabilities, implementing fluid dynamics principles for organic pixel displacement. It provides smooth, physics-based radial transformations that create vortex-like effects.
8
9## Mathematical Foundation
10
11### Core Algorithm
12Based on polar coordinate transformation and irrotational vortex mathematics:
13- **Radial displacement**: Pixels move along radial lines from center point
14- **Euclidean distance**: Smooth circular patterns rather than rectilinear Manhattan distance
15- **Bilinear interpolation**: Anti-aliasing for sub-pixel precision
16- **Wrapping behavior**: Seamless edge wrapping for continuous loops
17- **Accumulation system**: Continuous evolution through threshold-based execution
18
19### Physics Implementation
20The function implements irrotational vortex flow:
21```
22displacement = strength × (distance / maxDistance)
23newRadius = currentRadius + displacement
24```
25
26This creates natural, fluid-like motion that feels organic and responsive.
27
28## Usage Patterns
29
30### Basic Syntax
31```lisp
32(suck strength) ; Radial effect from screen center
33(suck strength centerX centerY) ; Radial effect from custom point
34```
35
36### Parameter Details
37- **strength**: Positive = inward motion, negative = outward motion
38- **centerX, centerY**: Optional center point (defaults to screen center)
39
40### Example Effects
41
42#### Static Effects
43```lisp
44(suck 1) ; Strong inward vortex
45(suck -0.5) ; Gentle outward flow
46(suck 0.1) ; Subtle breathing effect
47```
48
49#### Animated Sequences
50```lisp
51; Pulsing vortex
52(s1 (suck 0.5)) ; Gentle pulse every second
53(s0.1 (suck 0.1)) ; Rapid micro-movements
54
55; Complex timing patterns
56["2s..." 1 0 -1] ; Multi-phase timing with varying strength
57```
58
59#### Layered Compositions
60```lisp
61; Combined with other transformations
62(blur 1) ; Soften edges first
63(suck 0.2) ; Add subtle vortex
64(contrast 1.2) ; Enhance final result
65```
66
67#### Masked Applications
68```lisp
69; Selective area effects
70(mask 64 64 128 128) ; Define rectangular region
71(suck 2) ; Strong effect only in masked area
72(unmask) ; Remove mask
73```
74
75## Technical Implementation
76
77### Performance Optimizations
78- **Accumulation thresholds**: Prevents excessive computation
79- **Bilinear sampling**: Smooth anti-aliased results
80- **Deferred execution**: Compatible with embedded layer system
81- **Memory efficiency**: In-place pixel manipulation
82
83### Integration Features
84- **Embedded layer support**: Works with `embed` command
85- **Mask compatibility**: Respects drawing masks
86- **Timing integration**: Works with `s()` timing expressions
87- **API consistency**: Follows KidLisp function patterns
88
89## Advanced Use Cases
90
91### Fluid Simulations
92```lisp
93; Simulated fluid dynamics
94(def vortex_strength (sin (* frame 0.1)))
95(suck vortex_strength)
96```
97
98### Interactive Effects
99```lisp
100; Mouse-driven vortex
101(suck 0.5 mouse_x mouse_y)
102```
103
104### Complex Animations
105```lisp
106; Multi-center vortex system
107(repeat 3 i
108 (suck 0.3 (* i 100) (* i 80)))
109```
110
111## Implementation History
112
113### Development Timeline
114- **2025-09-06**: ✅ Core implementation with polar coordinate mathematics
115- **2025-09-06**: ✅ Bilinear interpolation for anti-aliasing
116- **2025-09-06**: ✅ Edge wrapping and accumulation system
117- **2025-09-06**: ✅ KidLisp integration and deferred execution
118- **2025-09-06**: ✅ Embedded layer compatibility
119
120### Design Decisions
1211. **Euclidean vs Manhattan distance**: Chose Euclidean for smooth circular patterns
1222. **Bilinear vs nearest neighbor**: Chose bilinear for quality anti-aliasing
1233. **Accumulation system**: Enables continuous evolution and performance control
1244. **Polar coordinates**: Natural fit for radial transformations
125
126## Comparison with Other Transforms
127
128| Transform | Type | Complexity | Physics | Quality |
129|-----------|------|------------|---------|---------|
130| `scroll` | Linear | Simple | Basic | High |
131| `zoom` | Scale | Medium | Geometric | High |
132| `spin` | Rotation | Medium | Angular | High |
133| `suck` | **Radial** | **Complex** | **Fluid** | **Highest** |
134
135The suck function represents the most mathematically sophisticated transformation in KidLisp, incorporating real physics principles for natural, organic motion.
136
137---
138
139*For usage examples and integration patterns, see the main KidLisp documentation and the zoom-vs-suck implementation report.*