# Dithering Studio

## Overview

The Dithering Studio is a professional tool for applying various dithering algorithms to images. Dithering is a technique used to create the illusion of color depth and smooth gradients using a limited color palette. This tool includes 11 different algorithms ranging from classic error diffusion to ordered dithering patterns.

## Access

**Menu**: Tools → Tool Scripts → "Dithering Studio"
**Keyboard**: Ctrl+Shift+T, then select "Dithering Studio"

## What is Dithering?

Dithering is the process of creating the illusion of color depth in images with a limited color palette. By strategically placing pixels of available colors, dithering can simulate colors and gradients that aren't directly available in the palette.

**Common Uses:**
- Color reduction for retro aesthetics
- Preparing images for limited color modes
- Creating artistic stippling effects
- Simulating analog display artifacts
- Halftone printing effects

## Dithering Algorithms

### Error Diffusion Algorithms

These algorithms propagate quantization error to neighboring pixels, creating smooth gradients.

#### 1. **Floyd-Steinberg** (Default)
The most famous and widely-used dithering algorithm. Distributes error to 4 neighboring pixels.

**Best For:**
- General purpose dithering
- Photographs and gradients
- Good balance of quality and speed

**Characteristics:**
- Smooth gradients
- Some directional bias
- Fast processing

#### 2. **Atkinson**
Used in early Macintosh computers and HyperCard. Distributes error more conservatively.

**Best For:**
- High contrast images
- Preserving detail
- Retro Mac aesthetic

**Characteristics:**
- Sharper than Floyd-Steinberg
- Less error diffusion (maintains brightness)
- Distinctive vintage look

#### 3. **Jarvis-Judice-Ninke**
Distributes error to 12 neighboring pixels in a wider pattern.

**Best For:**
- Very smooth gradients
- Large images
- When quality is priority over speed

**Characteristics:**
- Excellent gradient quality
- Minimal artifacts
- Slower processing

#### 4. **Stucki**
Similar to Jarvis but with different weight distribution.

**Best For:**
- Photographs
- Complex images
- High-quality output

**Characteristics:**
- Very smooth results
- Good detail preservation
- Medium-slow processing

#### 5. **Burkes**
Faster alternative to Jarvis with 7-pixel distribution.

**Best For:**
- Good balance of speed and quality
- Medium-sized images

**Characteristics:**
- Faster than Jarvis
- Still produces smooth gradients
- Good general-purpose choice

#### 6. **Sierra**
Three-row error diffusion with good performance.

**Best For:**
- Balanced quality and speed
- General images

**Characteristics:**
- Smooth gradients
- Minimal directional bias
- Good performance

### Ordered Dithering Algorithms

These use pre-defined patterns (matrices) to determine pixel placement. Results are more geometric.

#### 7. **Bayer 2×2**
The smallest Bayer matrix, creates a distinct crosshatch pattern.

**Best For:**
- Low-resolution images
- Retro game aesthetics
- When you want visible patterns

**Characteristics:**
- Very fast
- Obvious repeating pattern
- Suitable for pixel art

#### 8. **Bayer 4×4**
Standard Bayer matrix, good balance of pattern size and quality.

**Best For:**
- General ordered dithering
- Medium resolution images
- Classic halftone look

**Characteristics:**
- Fast processing
- Regular pattern
- Good for printing simulation

#### 9. **Bayer 8×8**
Larger matrix for finer patterns.

**Best For:**
- Higher resolution images
- More subtle patterns
- Smoother gradients

**Characteristics:**
- Fine pattern
- Less obvious repetition
- Slower than smaller matrices

### Special Algorithms

#### 10. **Random Dithering**
Adds random noise for dithering effect.

**Best For:**
- Artistic effects
- Breaking up banding
- Quick color reduction

**Characteristics:**
- Very fast
- No directional bias
- Can look grainy

#### 11. **Pattern Dithering**
Uses a simple 2×2 checkerboard pattern.

**Best For:**
- Hard-edged artistic effects
- Retro computer graphics
- Bold stylization

**Characteristics:**
- Extremely fast
- Very geometric look
- High contrast

## Parameters

### Dithering Algorithm
Select from 11 different algorithms (see above).

### Color Reduction
Control how many colors are used:

- **None (16 colors)**: Use all available C64 colors
- **2 Colors**: Monochrome (black & white)
- **4 Colors**: Limited palette (black, grays, white)
- **8 Colors**: Classic 8-color palette
- **Use Color Range**: Use colors from selected color range

### Color Range
If "Use Color Range" is selected, choose which color range (0-31) to use.

### Threshold (0-255)
Controls the brightness threshold for ordered and random dithering.
- **Lower values**: Darker overall result
- **128 (default)**: Balanced
- **Higher values**: Lighter overall result

*Note: Only affects ordered, random, and pattern dithering.*

### Dithering Strength (0-200%)
Controls how much error is diffused in error diffusion algorithms.
- **0%**: No dithering (posterization)
- **50%**: Subtle dithering
- **100% (default)**: Full dithering
- **150-200%**: Exaggerated dithering for artistic effects

*Note: Only affects error diffusion algorithms and random dithering.*

### Serpentine Scan
Alternates scanning direction on each row (left-to-right, then right-to-left).
- **Enabled (default)**: Reduces directional artifacts
- **Disabled**: Traditional left-to-right scanning

*Note: Only affects error diffusion algorithms.*

### Apply to Selection Only
If you have an active selection, only dither the selected area.

## Usage Examples

### Example 1: Convert Photo to 2-Color
1. Open Dithering Studio
2. Algorithm: Floyd-Steinberg
3. Color Reduction: 2 Colors
4. Keep other defaults
5. Click Run
6. **Result**: Classic black & white dithered image

### Example 2: Retro Mac Look
1. Open Dithering Studio
2. Algorithm: Atkinson
3. Color Reduction: 2 Colors
4. Serpentine: Disabled
5. Click Run
6. **Result**: Authentic early Macintosh aesthetic

### Example 3: Halftone Effect
1. Open Dithering Studio
2. Algorithm: Bayer 4×4
3. Color Reduction: 2 Colors
4. Threshold: 128
5. Click Run
6. **Result**: Newspaper halftone effect

### Example 4: Artistic Color Reduction
1. Setup a color range with your desired palette
2. Open Dithering Studio
3. Algorithm: Jarvis-Judice-Ninke
4. Color Reduction: Use Color Range
5. Select your color range
6. Click Run
7. **Result**: Smooth dithered image in custom palette

### Example 5: Pixel Art Style
1. Open Dithering Studio
2. Algorithm: Bayer 2×2
3. Color Reduction: 8 Colors
4. Click Run
5. **Result**: Retro game aesthetic

## Tips & Best Practices

### Algorithm Selection
- **Photographs**: Floyd-Steinberg, Jarvis, or Stucki
- **Graphics/UI**: Atkinson or Sierra
- **Retro games**: Bayer 2×2 or Pattern
- **Printing**: Bayer 4×4 or 8×8
- **Artistic**: Random with high strength

### Color Reduction
- Start with "None" to see how image looks with full palette
- Use "2 Colors" for high contrast effects
- "Use Color Range" for custom palettes
- More colors = smoother gradients

### Performance
- Error diffusion: Slower, higher quality
- Ordered dithering: Faster, more geometric
- Random: Fastest, but can be noisy

### Workflow
1. **Test first**: Try on small area or selection
2. **Try multiple algorithms**: Different images work better with different methods
3. **Adjust strength**: Subtle dithering (50-75%) often looks better than 100%
4. **Use serpentine**: Usually produces better results
5. **Save variations**: Try different color reductions with same algorithm

## Technical Details

### Error Diffusion Process
1. For each pixel, calculate the difference between original and quantized color
2. Distribute this "error" to neighboring unprocessed pixels
3. When those pixels are processed, the accumulated error influences their quantization
4. Results in perceptually smooth gradients

### Ordered Dithering Process
1. Compare each pixel's luminance to a threshold from the Bayer matrix
2. Matrix tiles across the image
3. Creates regular, predictable patterns
4. Very fast but less smooth than error diffusion

### Color Matching
The tool uses luminance-based color matching:
- Converts each color to brightness value
- Finds closest color in allowed palette by luminance
- Works well for grayscale-like images
- May not preserve hue in colorful images

## Troubleshooting

### Problem: Image too dark
- **Solution**: Increase Threshold (ordered dithering) or use brighter color palette

### Problem: Too much noise/grain
- **Solution**: Reduce Dithering Strength to 50-75%

### Problem: Visible horizontal streaks
- **Solution**: Enable Serpentine Scan

### Problem: Pattern too obvious
- **Solution**: Switch from Bayer to error diffusion algorithm

### Problem: Processing too slow
- **Solution**: Use Bayer or Random dithering instead of error diffusion

### Problem: Colors look wrong
- **Solution**: The tool uses luminance matching. For color images, consider using Color Range with similar hues

## Historical Context

**Floyd-Steinberg (1976)**: Revolutionized digital image processing
**Atkinson (1984)**: Created for original Macintosh computers
**Bayer (1973)**: Ordered dithering for printing and displays
**Jarvis/Stucki (1976)**: Improved error diffusion methods

## References

- Floyd, R.W. & Steinberg, L. (1976). "An Adaptive Algorithm for Spatial Greyscale"
- Bayer, B.E. (1973). "An Optimum Method for Two-Level Rendition of Continuous-Tone Pictures"
- Jarvis, J.F., Judice, C.N., & Ninke, W.H. (1976). "A Survey of Techniques for the Display of Continuous Tone Pictures"

Happy dithering! 🎨
