blue-noise 0.2.2

High-quality blue noise generation and dithering using the void-and-cluster algorithm
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

# Blue Noise

A Rust library and CLI for generating blue noise textures and dithering images using the void-and-cluster algorithm.

[![Crates.io](https://img.shields.io/crates/v/blue-noise.svg)](https://crates.io/crates/blue-noise)
[![Documentation](https://docs.rs/blue-noise/badge.svg)](https://docs.rs/blue-noise)

## Installation

```bash
cargo install blue-noise
```

Or build from source:

```bash
git clone https://github.com/mblode/blue-noise.git
cd blue-noise
cargo build --release
```

## Usage

### Generate a texture

```bash
blue-noise generate --size 128 --output blue-noise.png
blue-noise generate --width 256 --height 128 --output blue-noise-wide.png
```

Options:
- `--size` - Texture size in pixels (default: 128)
- `--width` - Texture width in pixels (overrides `--size`)
- `--height` - Texture height in pixels (overrides `--size`)
- `--output` - Output file path
- `--sigma` - Gaussian sigma, 1.0-3.0 (default: 1.9)
- `--seed` - Random seed for reproducibility
- `--verbose` - Show progress

### Dither an image

```bash
blue-noise dither -i input.jpg -o output.png
```

Options:
- `--input` - Input image
- `--output` - Output image
- `--noise` - Blue noise texture (default: blue-noise.png)
- `--foreground` - Foreground color as hex (default: #000000)
- `--background` - Background color as hex (default: #ffffff)
- `--width` - Output width
- `--height` - Output height
- `--contrast` - Contrast adjustment (default: 1.0)

## Library

Add to your `Cargo.toml`:

```toml
[dependencies]
blue-noise = "0.2"
```

Generate a texture:

```rust
use blue_noise::{BlueNoiseGenerator, BlueNoiseConfig, save_blue_noise_to_png};

let config = BlueNoiseConfig {
    width: 128,
    height: 128,
    sigma: 1.9,
    seed: Some(42),
    ..Default::default()
};

let generator = BlueNoiseGenerator::new(config)?;
let result = generator.generate()?;
save_blue_noise_to_png(&result, "blue-noise.png")?;
```

Apply dithering:

```rust
use blue_noise::{BlueNoiseTexture, Color, DitherOptions, apply_dithering};

let noise = BlueNoiseTexture::load("blue-noise.png")?;
let options = DitherOptions {
    foreground: Color::from_hex("#000000")?,
    background: Color::from_hex("#ffffff")?,
    width: Some(800),
    height: None,
    contrast: Some(1.2),
};

apply_dithering("input.jpg", "output.png", &noise, options)?;
```

## Examples

![Input dark](/img/dark.png)
![Output dark](/img/dark-noise.jpg)

![Input light](/img/light.png)
![Output light](/img/light-noise.jpg)

## References

- Ulichney, R. (1993). "Void-and-cluster method for dither array generation"
- Ulichney, R. (1988). "Dithering with blue noise"

## License

MIT