# Fractal Generator Tools

## Overview

Pixcen includes two powerful fractal generation tools available via **Tools → Tool Scripts** (Ctrl+Shift+T):

### 1. IFS Fractals
Generate nature-inspired and geometric fractals using Iterated Function Systems (IFS).

**Available Fractals:**
- Barnsley Fern (natural)
- Sierpinski Triangle (geometric)
- Dragon Curve (space-filling)
- Tree (branching)
- Maple Leaf (organic)
- Spiral (logarithmic)
- Pentagon Fractal (5-fold symmetry)
- Koch Snowflake (classic)

**Parameters:**
- **Fractal Type**: Select from 8 different fractals
- **Iterations**: 1,000 - 500,000 (default: 50,000)
- **Use Color Gradient**: Enable/disable gradient coloring
- **Color Range**: Select color range for gradient (0-31)
- **Solid Color**: Color to use when gradient disabled (0-15)
- **Clear Canvas First**: Start with blank canvas

### 2. Mandelbrot & Julia
Generate escape-time fractals including the famous Mandelbrot set and Julia sets.

**Available Fractals:**
- Mandelbrot Set (z² + c)
- Julia Set (z² + c, c fixed)
- Burning Ship (|z|² + c)
- Tricorn (conj(z)² + c)
- Multibrot-3 (z³ + c)
- Multibrot-4 (z⁴ + c)

**Parameters:**
- **Fractal Type**: Select from 6 different fractals
- **Max Iterations**: 50 - 2,000 (default: 256)
- **Color Scheme**: 7 options (smooth-gradient, banded, grayscale, fire, ice, psychedelic, classic)
- **Use Smooth Coloring**: Enable continuous coloring algorithm
- **Supersampling**: 1 (off), 2 (4x), or 3 (9x) anti-aliasing
- **Mandelbrot Zoom Level**: 0.1 - 1,000.0 (default: 1.0)
- **Mandelbrot Center X**: -2.0 to 2.0 (default: -0.5)
- **Mandelbrot Center Y**: -2.0 to 2.0 (default: 0.0)
- **Julia Constant (Real)**: -2.0 to 2.0 (default: -0.7)
- **Julia Constant (Imaginary)**: -2.0 to 2.0 (default: 0.27015)
- **Clear Canvas First**: Start with blank canvas

## How to Use

### Access via Menu
1. Go to **Tools → Tool Scripts**
2. Select "IFS Fractals" or "Mandelbrot & Julia"
3. Adjust parameters in the dialog
4. Click "Run"
5. Watch progress in the status bar
6. View results on canvas

### Access via Keyboard
1. Press **Ctrl+Shift+T**
2. Select tool from list
3. Configure parameters
4. Click "Run"

## Quick Examples

### Generate a Barnsley Fern
1. Open IFS Fractals tool (Ctrl+Shift+T)
2. Select "Barnsley Fern" from Fractal Type
3. Enable "Use Color Gradient"
4. Click Run
5. Watch beautiful fern appear in seconds!

### Generate the Mandelbrot Set
1. Open Mandelbrot & Julia tool (Ctrl+Shift+T)
2. Keep default settings (Mandelbrot selected)
3. Click Run
4. See the iconic fractal!

### Generate a Julia Dragon
1. Open Mandelbrot & Julia tool
2. Select "Julia Set" from Fractal Type
3. Set Julia Constant (Real) to -0.7
4. Set Julia Constant (Imaginary) to 0.27015
5. Click Run
6. See dragon-like patterns!

## Tips & Best Practices

### IFS Fractals
- **Dense patterns**: Use 200k+ iterations
- **Sparse artistic**: Use 10k-20k iterations
- **Sweet spot**: 50k-100k iterations
- **Color depth**: Enable gradient for more visual interest

### Mandelbrot/Julia
- **First time**: Use defaults, don't change anything
- **Deep zoom**: Increase iterations with zoom (zoom × 5 rule)
- **Best quality**: Enable smooth coloring + supersampling 2
- **Fast preview**: Use 128 iterations, supersampling 1
- **Final render**: Use 512+ iterations, supersampling 2-3

### Both Tools
- **Test first**: Use small canvas with low iterations
- **Final render**: Use full canvas with high quality settings
- **Document discoveries**: Write down interesting parameters
- **Layer fractals**: Disable "Clear Canvas" to combine multiple fractals

## Performance Notes

### IFS Fractals
- 50,000 iterations: ~1-3 seconds
- 100,000 iterations: ~2-6 seconds
- 500,000 iterations: ~10-30 seconds

### Mandelbrot/Julia
For 320×200 canvas:
- Max Iterations 256, Supersampling 1: ~2-5 seconds
- Max Iterations 256, Supersampling 2: ~8-20 seconds
- Max Iterations 512, Supersampling 3: ~45-120 seconds

Higher resolutions scale quadratically!

## Troubleshooting

### IFS: Nothing visible
- Increase Iterations to 50,000
- Try different Fractal Type

### IFS: Too sparse
- Increase Iterations to 100,000+

### Mandelbrot: All black
- Reset Center coordinates to defaults (-0.5, 0.0)
- Increase Max Iterations
- Decrease Zoom Level

### Mandelbrot: All one color
- Decrease Zoom Level
- Increase Max Iterations

### Julia: Nothing interesting
- Try famous constants (see MANDELBROT_JULIA_README.md)
- Experiment with different Julia Constant values

### Any tool: Too slow
- Reduce Max Iterations or Iterations
- Set Supersampling to 1
- Use smaller canvas

## Additional Documentation

For more detailed information:
- **IFS Fractals**: See `scripts/examples/IFS_FRACTALS_README.md`
- **Mandelbrot & Julia**: See `scripts/examples/MANDELBROT_JULIA_README.md`
- **Quick Start Guide**: See `scripts/examples/FRACTAL_QUICK_START.md`

## Technical Details

### Tool Script Format
Both tools use the `pixcen.registerTool()` API format with:
- Metadata (name, description, category, version, author)
- Progress support (real-time status updates)
- Parameters (configurable via dialog)
- Run method (main execution logic)

### Example Scripts
Example versions (non-parameterized) are still available in `scripts/examples/`:
- `ifs-fractals.js` - IFS fractal generator with hardcoded values
- `mandelbrot-julia.js` - Mandelbrot/Julia generator with hardcoded values

These can be run via **Script → Run Script** and edited to customize behavior.

## Credits

**IFS Fractals:**
- Barnsley Fern: Michael Barnsley (1988)
- Sierpinski Triangle: Wacław Sierpiński (1915)
- Dragon Curve: NASA physicists (1960s)

**Mandelbrot & Julia:**
- Julia Sets: Gaston Julia (1918)
- Mandelbrot Set: Benoit Mandelbrot (1980)
- Burning Ship: Michelitsch & Rossler (1992)
- Tricorn: John Milnor (1990s)

**Implementation:**
- Pixcen Team (2025)

Happy fractal exploring! 🎨✨
