# Mandelbrot & Julia Fractal Generator

## Overview

The `mandelbrot-julia.js` script generates stunning escape-time fractals including the famous Mandelbrot set, Julia sets, and several fascinating variants. These fractals are based on iterating complex number equations and coloring points based on how quickly they "escape" to infinity.

## Quick Start

1. Open `scripts/examples/mandelbrot-julia.js` in a text editor
2. Set the `FRACTAL_TYPE` variable (see options below)
3. Run in Pixcen: **Script → Run Script** (Ctrl+Shift+R)
4. Wait for rendering (progress shown)

## Fractal Types

### 1. **mandelbrot** (Classic Mandelbrot Set)

The most famous fractal, discovered by Benoit Mandelbrot in 1980. Each point c in the complex plane is tested using the iteration: **z = z² + c**

**Configuration:**
```javascript
const FRACTAL_TYPE = "mandelbrot";
const MANDELBROT_ZOOM = 1.0;        // Start at 1.0, increase to zoom in
const MANDELBROT_CENTER_X = -0.75;  // Real axis (centered to show full set)
const MANDELBROT_CENTER_Y = 0.0;    // Imaginary axis
```

**Famous Locations to Explore:**
- **Default view**: (-0.75, 0.0, zoom 1) - Full set
- **Seahorse Valley**: (-0.75, 0.1, zoom 10) - Spiraling tendrils
- **Elephant Valley**: (0.25, 0.0, zoom 20) - Elephant-like shapes
- **Mini Mandelbrot**: (-0.1592, 1.0317, zoom 50) - Perfect tiny replica
- **Spiral City**: (-0.7269, 0.1889, zoom 100) - Intricate spirals
- **Triple Spiral**: (-0.088, 0.654, zoom 80) - Three-fold symmetry

### 2. **julia** (Julia Sets)

Closely related to Mandelbrot, but with a fixed constant c. Each different c value creates a completely different Julia set! Uses iteration: **z = z² + c**

**Configuration:**
```javascript
const FRACTAL_TYPE = "julia";
const JULIA_C_REAL = -0.7;      // Try different values!
const JULIA_C_IMAG = 0.27015;   // Try different values!
```

**Beautiful Julia Constants:**
- **Dragon**: c = -0.7 + 0.27015i (Default - dragon-like shape)
- **Dendrite**: c = 0.285 + 0.01i (Tree-like branches)
- **Douady Rabbit**: c = -0.123 + 0.745i (Rabbit silhouette)
- **Siegel Disk**: c = -0.391 - 0.587i (Circular patterns)
- **San Marco**: c = -0.75 + 0.0i (Named after St. Mark's Basilica)
- **Cauliflower**: c = 0.285 + 0i (Vegetable-like structure)
- **Spiral**: c = -0.4 + 0.6i (Spiral arms)
- **Lightning**: c = -0.8 + 0.156i (Electric appearance)

**Relationship to Mandelbrot:**
If a point c is IN the Mandelbrot set, its Julia set is connected. If c is OUTSIDE, the Julia set is a dust of disconnected points!

### 3. **burning-ship** (Burning Ship Fractal)

A dramatic variant where we take absolute values before squaring: **z = (|Re(z)| + i|Im(z)|)² + c**

This breaks symmetry and creates ship-like structures that appear to be on fire!

```javascript
const FRACTAL_TYPE = "burning-ship";
const MANDELBROT_CENTER_X = -1.75;  // Good starting view
const MANDELBROT_CENTER_Y = -0.03;
const MANDELBROT_ZOOM = 1.0;
```

**Notable features:**
- Looks like flaming ships
- Less symmetric than Mandelbrot
- Discovered in 1992 by Michelitsch and Rossler

### 4. **tricorn** (Mandelbar/Tricorn)

Uses the complex conjugate: **z = conj(z)² + c**

Creates three-fold symmetric structures that are mirror images of Mandelbrot.

```javascript
const FRACTAL_TYPE = "tricorn";
const MANDELBROT_CENTER_X = 0.0;
const MANDELBROT_CENTER_Y = 0.0;
const MANDELBROT_ZOOM = 1.0;
```

**Characteristics:**
- Three-fold rotational symmetry
- Introduced by Milnor in 1990s
- Also called "Mandelbar" set

### 5. **multibrot-3** (Power 3 Mandelbrot)

Uses cubic iteration: **z = z³ + c**

Creates sets with three-fold symmetry.

```javascript
const FRACTAL_TYPE = "multibrot-3";
```

### 6. **multibrot-4** (Power 4 Mandelbrot)

Uses fourth-power iteration: **z = z⁴ + c**

Creates sets with four-fold symmetry.

```javascript
const FRACTAL_TYPE = "multibrot-4";
```

## Configuration Options

### Iteration Depth

```javascript
const MAX_ITERATIONS = 256;  // How many iterations before giving up
```

- **Low (50-100)**: Fast rendering, less detail
- **Medium (256-512)**: Good balance (recommended)
- **High (1000+)**: Very detailed, slow, best for deep zooms

**Rule of thumb**: Increase iterations as you zoom deeper. For zoom level 100, use at least 500 iterations.

### Color Schemes

```javascript
const COLOR_SCHEME = "smooth-gradient";
```

Available schemes:

1. **smooth-gradient**: Smooth progression through palette (best for most)
2. **banded**: Sharp color bands (classic look)
3. **grayscale**: Black and white (emphasizes structure)
4. **fire**: Black → Red → Yellow → White (hot look)
5. **ice**: Black → Blue → Cyan → White (cold look)
6. **psychedelic**: Repeating rainbow (trippy)
7. **classic**: Original Mandelbrot color scheme

### Smooth Coloring

```javascript
const USE_SMOOTH_COLORING = true;  // Eliminates banding artifacts
```

- **true**: Smooth color transitions (recommended)
- **false**: Hard color bands (faster, more retro)

Uses continuous escape-time algorithm for professional results.

### Supersampling (Anti-Aliasing)

```javascript
const SUPERSAMPLING = 1;  // 1=off, 2=4x, 3=9x
```

- **1**: No anti-aliasing (fast)
- **2**: 4x sampling (good quality, 4x slower)
- **3**: 9x sampling (excellent quality, 9x slower)

Use for final high-quality renders. Each level squares the rendering time!

## Mathematical Background

### The Mandelbrot Set

For each complex number c = x + yi:
1. Start with z₀ = 0
2. Iterate: z_(n+1) = z_n² + c
3. If |z| ever exceeds 2, c is NOT in the set
4. If |z| never exceeds 2 (after many iterations), c IS in the set

The boundary between these two regions creates the fractal!

### Julia Sets

Similar to Mandelbrot, but:
- c is fixed (chosen constant)
- z₀ = the pixel position

Each point in the Mandelbrot set corresponds to a different Julia set!

### Escape Time Coloring

Points are colored based on how quickly they escape:
- **Black**: Never escaped (in the set)
- **Colors**: Based on escape iteration count
- **Smooth coloring**: Interpolates between iterations using logarithms

### Complex Number Arithmetic

The script implements:
- **Multiplication**: (a+bi)(c+di) = (ac-bd) + (ad+bc)i
- **Squaring**: (a+bi)² = (a²-b²) + (2ab)i
- **Cubing**: (a+bi)³ = (a³-3ab²) + (3a²b-b³)i
- **Magnitude**: |a+bi| = √(a²+b²)

## Performance Tips

### Optimization Strategies

1. **Start low-res**: Test with small canvas before rendering large
2. **Fewer iterations**: Start with 128, increase only if needed
3. **Disable supersampling**: Use SUPERSAMPLING=1 for testing
4. **Simple color schemes**: "banded" is fastest

### Rendering Times (approximate)

For 320x200 canvas, MAX_ITERATIONS=256, SUPERSAMPLING=1:
- **Mandelbrot**: ~2-5 seconds
- **Julia**: ~2-5 seconds
- **With 2x supersampling**: ~8-20 seconds
- **With 3x supersampling**: ~18-45 seconds

Higher resolutions scale quadratically!

### Deep Zoom Considerations

When zooming deep (zoom > 50):
1. Increase MAX_ITERATIONS proportionally
2. May need more precision (JavaScript limit ~10^15)
3. Render times increase with iteration count

## Exploring Tips

### Finding Beautiful Regions

1. **Start with full Mandelbrot view**
2. **Look for interesting features**:
   - Tendrils and spirals
   - Mini-Mandelbrots
   - Seahorse tails
   - Needle-like projections

3. **Zoom in gradually**:
   - Start at zoom 1
   - Increase by 2-5x each step
   - Adjust center to feature of interest
   - Increase MAX_ITERATIONS as needed

4. **Document discoveries**:
   - Record center coordinates
   - Note zoom level
   - Save color scheme

### Julia Set Exploration

1. **Pick a point from Mandelbrot**:
   - Points on boundary → interesting Julia sets
   - Points inside → boring filled Julia sets
   - Points outside → dust-like Julia sets

2. **Try systematic variations**:
   - Keep real constant, vary imaginary
   - Create series of related Julia sets

3. **Use famous constants** (listed above)

## Advanced Techniques

### Creating Zoom Sequences

To create a zoom animation:

```javascript
// Render sequence of increasing zooms
for (let z = 1; z <= 100; z *= 1.2) {
    MANDELBROT_ZOOM = z;
    MAX_ITERATIONS = Math.floor(128 + z * 2);
    // Render frame...
}
```

### Comparing Fractals

Render multiple fractals with same coordinates to compare:
- Same center/zoom for Mandelbrot vs Burning Ship
- Julia set using point from Mandelbrot

### Custom Color Palettes

Modify the `getColorForIterations()` function to create custom color schemes:

```javascript
// Example: Blue to gold
if (normalized < 0.5) {
    return 6;  // Blue
} else {
    return 7;  // Yellow/Gold
}
```

## Troubleshooting

### Problem: Solid black image
- **Cause**: Zoomed too far out or wrong coordinates
- **Fix**: Use default values first

### Problem: All one color (not black)
- **Cause**: Zoomed too far in, or not enough iterations
- **Fix**: Increase MAX_ITERATIONS or zoom out

### Problem: Banding/artifacts
- **Cause**: Not enough iterations or smooth coloring disabled
- **Fix**: Enable USE_SMOOTH_COLORING and increase MAX_ITERATIONS

### Problem: Slow rendering
- **Cause**: High resolution, supersampling, or many iterations
- **Fix**: Reduce one or more of these factors

### Problem: Blocky appearance
- **Cause**: No anti-aliasing
- **Fix**: Enable SUPERSAMPLING (2 or 3)

## Scientific Context

### Historical Significance

- **1918**: Gaston Julia studies iteration of complex functions
- **1980**: Benoit Mandelbrot uses computers to visualize the set
- **1982**: "The Fractal Geometry of Nature" published
- **1985**: Scientific American article brings fractals to mainstream
- **1990s**: Various Mandelbrot variants discovered

### Applications

- **Image compression**: Fractal compression algorithms
- **Computer graphics**: Terrain and texture generation
- **Antenna design**: Fractal antennas for multiple frequencies
- **Art**: Infinite canvas for mathematical art
- **Education**: Teaching complex numbers and iteration

### Mathematical Properties

- **Self-similarity**: Zoom in forever, see similar structures
- **Infinite complexity**: Boundary has infinite detail
- **Fractal dimension**: ~2 (precisely: 2)
- **Connected**: The Mandelbrot set is proven to be connected
- **Computable**: Can calculate to arbitrary precision

## Further Reading

- **"The Beauty of Fractals"** - Peitgen & Richter (1986)
- **"Fractals Everywhere"** - Barnsley (1988)
- **"The Science of Fractal Images"** - Peitgen & Saupe (1988)
- **Wikipedia**: Comprehensive articles on all fractal types
- **Fractal Forums**: Community discussions and discoveries

## Credits

This implementation uses:
- Escape-time algorithm
- Smooth coloring (continuous potential)
- Complex number arithmetic
- Optimized iteration functions

Enjoy exploring the infinite complexity of the Mandelbrot and Julia sets!
