Monorepo for Aesthetic.Computer
aesthetic.computer
1# Zoom vs Suck Implementation Analysis Report
2
3## Executive Summary
4
5This document analyzes the current zoom transformation function in `graph.mjs` and provides comprehensive specifications for implementing a new "suck" function that creates radial pixel displacement effects. The suck function will provide organic, vortex-like transformations that move pixels radially toward or away from a center point with wrapping behavior, creating zooming effects without data loss.
6
7## Research Findings: Mathematical Foundations
8
9### Polar Coordinate System
10Based on research into coordinate transformation systems, the suck function will leverage polar coordinates for radial transformations:
11
12- **Conversion formulas**: `x = r cos φ`, `y = r sin φ`
13- **Inverse conversion**: `r = √(x² + y²)`, `φ = atan2(y, x)`
14- **Benefits**: Natural representation for radial motions and rotational transformations
15
16### Vortex Mathematics
17Research into fluid dynamics reveals multiple vortex models applicable to image transformation:
18
19#### Irrotational Vortex Model
20- **Velocity Profile**: v ∝ 1/r (inversely proportional to radius)
21- **Characteristics**: Preserves circulation, creates spiral flow patterns
22- **Application**: Ideal for smooth radial displacement without angular distortion
23
24#### Rankine Vortex Model
25- **Inner Core**: Solid body rotation (v ∝ r)
26- **Outer Region**: Irrotational flow (v ∝ 1/r)
27- **Application**: Allows for controlled center behavior and natural falloff
28
29### Navier-Stokes Fluid Dynamics
30Advanced research into fluid simulation algorithms provides theoretical foundation:
31
32- **Vorticity**: ω = ∇ × v (curl of velocity field)
33- **Material Derivative**: Describes how fluid elements evolve over time
34- **Incompressible Flow**: ∇ · v = 0 (divergence-free velocity field)
35- **Application**: Ensures volume-preserving transformations for data conservation
36
37## Current Zoom Implementation Analysis
38
39### Zoom Function Overview (lines 3636-3800)
40The existing zoom function in `graph.mjs` implements traditional geometric scaling with these characteristics:
41
42#### Core Functionality
43- **Purpose**: Scales pixel content by a factor with configurable anchor points
44- **Algorithm**: Traditional 2D scaling transformation with bilinear interpolation
45- **Parameters**:
46 - `level`: Zoom factor (1 = no change, >1 = zoom in, <1 = zoom out)
47 - `x`, `y`: Anchor point coordinates (default: canvas center)
48- **Behavior**: Geometric scaling that maintains aspect ratios
49
50#### Technical Implementation
51```javascript
52// Key transformation logic
53const scale = level;
54const sourceX = (targetX - anchorX) / scale + anchorX;
55const sourceY = (targetY - anchorY) / scale + anchorY;
56```
57
58#### Strengths
59- Mathematically precise scaling
60- Efficient bilinear interpolation
61- Flexible anchor point positioning
62- Clean integration with accumulation system
63- Proper edge wrapping with modulo operations
64
65#### Limitations
66- Creates empty regions at zoom levels > 1
67- Loses pixel data at zoom levels < 1
68- Geometric rather than organic transformation feel
69- No vortex or radial flow characteristics
70
71## Proposed Suck Function Implementation
72
73### Core Algorithm: Polar Radial Displacement
74
75The suck function will implement a radial displacement algorithm based on polar coordinate transformation and fluid dynamics principles:
76
77#### Mathematical Model
78```javascript
79// 1. Convert to polar coordinates
80const dx = x - centerX;
81const dy = y - centerY;
82const r = Math.sqrt(dx * dx + dy * dy);
83const theta = Math.atan2(dy, dx);
84
85// 2. Apply radial displacement with research-backed curves
86const maxRadius = Math.sqrt(centerX * centerX + centerY * centerY);
87const normalizedR = r / maxRadius;
88
89// 3. Multiple displacement curve options based on vortex research:
90
91// Option A: Irrotational Vortex (1/r falloff)
92const displacement = strength * Math.log(normalizedR + 0.01) / normalizedR;
93
94// Option B: Gaussian Vortex (smooth falloff)
95const displacement = strength * Math.exp(-normalizedR * normalizedR);
96
97// Option C: Polynomial Flow (customizable falloff)
98const displacement = strength * Math.pow(1 - normalizedR, 2);
99
100// 4. Calculate new radius with wrapping
101const newR = r + displacement;
102const wrappedR = ((newR % maxRadius) + maxRadius) % maxRadius;
103
104// 5. Convert back to Cartesian
105const newX = centerX + wrappedR * Math.cos(theta);
106const newY = centerY + wrappedR * Math.sin(theta);
107```
108
109#### Algorithm Advantages
110- **Radial Flow**: Natural vortex-like motion patterns
111- **Volume Preservation**: Maintains total pixel count through wrapping
112- **Configurable Falloff**: Multiple mathematical models for different effects
113- **Smooth Transitions**: Continuous displacement fields prevent artifacts
114- **Research-Based**: Built on proven fluid dynamics and coordinate transformation principles
115
116### Enhanced Features Based on Research
117
118#### Vorticity-Inspired Options
119- **Clockwise/Counterclockwise**: Optional angular component for spiral effects
120- **Multi-Center Vortex**: Support for multiple attraction/repulsion points
121- **Temporal Evolution**: Time-dependent parameters for animated flows
122
123#### Navier-Stokes Inspired Conservation
124- **Incompressible Flow**: Divergence-free displacement field
125- **Circulation Preservation**: Maintains rotational flow characteristics
126- **Energy Conservation**: Stable long-term behavior
127
128## Implementation TODO List
129
130### Phase 1: Core Implementation ✅ COMPLETE!
131- [x] **1.1** Add suck function to graph.mjs with basic radial displacement
132- [x] **1.2** Implement irrotational vortex algorithm (1/r falloff)
133- [x] **1.3** Add polar coordinate conversion utilities
134- [x] **1.4** Implement bilinear interpolation with wrapping
135- [x] **1.5** Add basic parameter validation and defaults
136
137### Phase 2: KidLisp Integration ✅ COMPLETE!
138- [x] **2.1** Add "suck" command parsing in kidlisp.mjs
139- [x] **2.2** Support (suck), (suck strength), (suck strength x y)
140- [x] **2.3** Add deferred execution support
141- [x] **2.4** Test integration with existing accumulation system
142
143### Phase 3: Algorithm Options
144- [ ] **3.1** Add Gaussian vortex option
145- [ ] **3.2** Add polynomial flow option
146- [ ] **3.3** Add algorithm parameter to function signature
147- [ ] **3.4** Implement algorithm selection logic
148
149### Phase 4: Testing & Optimization
150- [ ] **4.1** Basic functionality testing
151- [ ] **4.2** Edge case testing (center at edges, extreme strengths)
152- [ ] **4.3** Performance optimization (lookup tables)
153- [ ] **4.4** Integration testing with other graph functions
154
155### Phase 5: Documentation & Examples
156- [ ] **5.1** Add function documentation
157- [ ] **5.2** Create usage examples
158- [ ] **5.3** Update KidLisp reference
159- [ ] **5.4** Performance benchmarks
160
161---
162
163### Progress Log
164- **2025-09-06**: Started implementation, created TODO list
165- **2025-09-06**: ✅ COMPLETED Phase 1 & 2! Added suck function to graph.mjs with irrotational vortex algorithm, added to exports, integrated with KidLisp including deferred execution and embedded layer support
166
167### Implementation Notes
168- Start with irrotational vortex for smooth, natural-looking radial displacement
169- Follow zoom function pattern for consistency with existing codebase
170- Maintain compatibility with accumulation system and existing graph.mjs structure
171
172---
173
174## Conclusion
175
176The suck function represents a significant advancement over traditional zoom by incorporating fluid dynamics principles and polar coordinate mathematics. Research into Navier-Stokes equations, vorticity theory, and coordinate transformations provides a solid mathematical foundation for creating organic, data-preserving transformations that feel natural and fluid-like.
177
178The implementation will maintain compatibility with existing graph.mjs patterns while introducing new possibilities for artistic expression through mathematically rigorous radial displacement algorithms. This approach bridges the gap between technical precision and artistic creativity, offering users both predictable behavior and visually compelling results.