# IFS Fractal Generator

## Overview

The `ifs-fractals.js` script generates beautiful IFS (Iterated Function System) fractals. IFS fractals are created by repeatedly applying a set of affine transformations to points, producing self-similar patterns found in nature and mathematics.

## Usage

1. Open the script in a text editor
2. Modify the `FRACTAL_TYPE` variable to select a fractal:
   ```javascript
   const FRACTAL_TYPE = "barnsley-fern"; // Change this value
   ```
3. Run the script in Pixcen: **Script → Run Script** (Ctrl+Shift+R)
4. Select `scripts/examples/ifs-fractals.js`

## Available Fractal Types

### 1. **barnsley-fern** (Default)
The classic Barnsley Fern - one of the most famous IFS fractals that resembles a Black Spleenwort fern. Created by British mathematician Michael Barnsley in 1988.

**Characteristics:**
- 4 affine transformations with different probabilities
- Natural, organic appearance
- Demonstrates how simple math can create complex natural forms

### 2. **sierpinski-triangle**
The Sierpinski Triangle (or Sierpinski Gasket) - a fractal described by Wacław Sierpiński in 1915. One of the most basic geometric fractals.

**Characteristics:**
- Perfect self-similarity at all scales
- Simple geometric structure
- Related to Pascal's triangle and cellular automata

### 3. **dragon-curve**
The Heighway Dragon (or Dragon Curve) - a space-filling curve that never intersects itself. Discovered by NASA physicists in 1960s.

**Characteristics:**
- Space-filling properties
- Beautiful symmetry
- Can tile the plane

### 4. **tree**
A branching tree fractal that demonstrates natural branching patterns found in trees, blood vessels, and river networks.

**Characteristics:**
- Hierarchical branching structure
- Models natural growth patterns
- Variable branch angles

### 5. **maple-leaf**
A fractal approximation of a maple leaf shape, demonstrating how IFS can model botanical forms.

**Characteristics:**
- Resembles Canadian maple leaf
- Complex organic structure
- Multiple transformation rules

### 6. **spiral**
A logarithmic spiral fractal with beautiful curved patterns.

**Characteristics:**
- Smooth spiral structure
- Found in nature (nautilus shells, galaxies)
- Aesthetic appeal

### 7. **pentagon-fractal**
A fractal with five-fold rotational symmetry, creating intricate geometric patterns.

**Characteristics:**
- Perfect pentagonal symmetry
- Geometric precision
- Demonstrates rotational IFS systems

### 8. **koch-snowflake**
An IFS approximation of the famous Koch Snowflake, one of the earliest fractal curves.

**Characteristics:**
- Infinite perimeter, finite area
- Self-similar at all scales
- Classic fractal curve

## Configuration Options

### Iterations
```javascript
const ITERATIONS = 50000; // Number of points to plot
```

- **Lower values (5,000-10,000)**: Faster, less dense, good for testing
- **Medium values (50,000-100,000)**: Good detail, recommended
- **Higher values (200,000+)**: Very dense, slow but beautiful

### Color Gradient
```javascript
const USE_COLOR_GRADIENT = true; // Color by iteration depth
```

- **true**: Colors progress through palette based on iteration number
- **false**: Uses current drawing color for all points

## How IFS Works

An IFS fractal is defined by a set of affine transformations, each with:

1. **Transformation coefficients** [a, b, c, d, e, f]:
   - `x' = ax + by + e`
   - `y' = cx + dy + f`

2. **Probability**: How often this transformation is chosen

The algorithm:
1. Start with an initial point (usually origin)
2. Randomly select a transformation based on probabilities
3. Apply transformation to get new point
4. Plot the new point
5. Repeat thousands of times

The magic: After a "warmup" period, the points converge to create the fractal's characteristic shape!

## Tips & Tricks

1. **Experimenting with Scale**: The `scale` and `offset` parameters control how the fractal fits on screen. If your fractal appears too small or is cut off, adjust these values.

2. **Custom Fractals**: You can create your own IFS systems by adding entries to the `IFS_SYSTEMS` object. Each transformation needs 6 coefficients and a probability (totaling 1.0).

3. **Color Palette**: Change Pixcen's color palette before running to affect the gradient colors.

4. **Resolution**: Higher canvas resolutions will show more detail but take longer to render.

5. **Combining Fractals**: Run multiple fractals with different colors to create composite images.

## Mathematical Background

### Affine Transformations
Each transformation is an affine map that combines:
- **Rotation**: Controlled by a, b, c, d
- **Scaling**: Magnitude of a, b, c, d
- **Translation**: The e and f values

### Contraction Mapping
For an IFS to converge to a unique attractor (the fractal), the transformations must be contractive (scale factor < 1). This ensures points don't "escape" to infinity.

### Chaos Game
The IFS algorithm is sometimes called the "chaos game" because it uses randomness to explore the fractal's structure, yet always converges to the same shape.

## Performance Notes

- **50,000 iterations**: ~1-3 seconds on modern hardware
- **100,000 iterations**: ~2-6 seconds
- **500,000 iterations**: ~10-30 seconds

Progress is shown during generation. Press ESC to cancel if needed.

## References

- **"Fractals Everywhere"** by Michael Barnsley (1988) - The definitive text on IFS
- **"The Fractal Geometry of Nature"** by Benoit Mandelbrot (1982) - Classic fractal text
- **Wikipedia**: Search for "Iterated function system" for mathematical details

## Examples of Output

Each fractal creates unique patterns:
- **barnsley-fern**: Looks like a natural fern frond
- **sierpinski-triangle**: Perfect triangular gasket
- **dragon-curve**: Intricate self-avoiding curve
- **tree**: Branching structure like a winter tree
- **maple-leaf**: Recognizable leaf shape
- **spiral**: Beautiful curved spirals
- **pentagon-fractal**: Pentagonal star pattern
- **koch-snowflake**: Classic snowflake curve

Experiment with different types, iterations, and color settings to create unique fractal art!
