dotmax 0.1.4

High-performance terminal braille rendering for images, animations, and graphics
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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

# dotmax

Render anything in terminal braille. Images, GIFs, videos, webcam - one line of code.

[![Crates.io](https://img.shields.io/crates/v/dotmax.svg)](https://crates.io/crates/dotmax)
[![Documentation](https://docs.rs/dotmax/badge.svg)](https://docs.rs/dotmax)
[![License](https://img.shields.io/crates/l/dotmax.svg)](https://github.com/newjordan/dotmax#license)

## Install

```bash
cargo add dotmax --features image
```

## One-Line Usage

```rust
use dotmax::quick;

quick::show_file("photo.png")?;    // Any image
quick::show_file("cat.gif")?;      // Animated GIF (plays automatically)
quick::show_file("movie.mp4")?;    // Video (requires 'video' feature)
quick::show_webcam()?;             // Live webcam (requires 'video' feature)
```

## Features

| Feature | What it enables | Install |
|---------|-----------------|---------|
| `image` | PNG, JPG, GIF, APNG, BMP, WebP, TIFF | `cargo add dotmax --features image` |
| `svg` | SVG vector graphics | `cargo add dotmax --features svg` |
| `video` | Video + webcam (needs FFmpeg) | `cargo add dotmax --features video` |

```toml
# Cargo.toml - pick what you need
[dependencies]
dotmax = { version = "0.1", features = ["image"] }           # Images only
dotmax = { version = "0.1", features = ["image", "svg"] }    # Images + SVG
dotmax = { version = "0.1", features = ["video"] }           # Video + webcam
```

**Video feature requires FFmpeg installed on your system.**

## Quick API Reference

```rust
use dotmax::quick;

// Display (blocks until keypress or video ends)
quick::show_file("any.png")?;           // Auto-detect format
quick::show_image("photo.jpg")?;        // Static image only
quick::show_webcam()?;                  // Default webcam
quick::show_webcam_device(0)?;          // Webcam by index
quick::show_webcam_device("/dev/video1")?;  // Webcam by path

// Load without displaying
let grid = quick::load_image("photo.png")?;  // Returns BrailleGrid
quick::show(&grid)?;                         // Display manually

// Create empty grid
let mut grid = quick::grid()?;  // Terminal-sized
```

## Drawing Primitives

```rust
use dotmax::prelude::*;

let mut grid = grid()?;
draw_line(&mut grid, 0, 0, 100, 50)?;
draw_circle(&mut grid, 50, 25, 20)?;
draw_rectangle(&mut grid, 10, 10, 80, 40)?;
show(&grid)?;
```

## Animation Loop

```rust
use dotmax::animation::AnimationLoop;

AnimationLoop::new(80, 24)
    .fps(30)
    .on_frame(|frame, grid| {
        grid.clear();
        grid.set_dot((frame * 2) % 160, 48)?;
        Ok(true)  // Return false to stop
    })
    .run()?;
```

## Examples

```bash
# Basic (no features needed)
cargo run --example hello_braille
cargo run --example bouncing_ball
cargo run --example shapes_demo

# Images
cargo run --example load_image --features image
cargo run --example dither_comparison --features image

# Animated GIF/APNG
cargo run --example animated_gif --features image -- your.gif
cargo run --example animated_apng --features image -- your.apng

# Video (needs FFmpeg)
cargo run --example video_player --features video -- your.mp4

# Webcam (needs FFmpeg + camera)
cargo run --example webcam_viewer --features video
cargo run --example webcam_tuner --features video   # Interactive settings
```

## Tuners

Tuners let you **find the best render settings visually**. Adjust dithering, brightness, contrast, etc. in real-time and see the results instantly.

### Why use a tuner?

Different images/videos look best with different settings. Instead of guessing values in code, use the tuner to experiment live, then copy the settings you like.

### Webcam Tuner

```bash
cargo run --example webcam_tuner --features video
```

### Video/Image Tuner

```bash
cargo run --example render_tuner --features video -- your_video.mp4
cargo run --example render_tuner --features image -- your_image.png
```

### Tuner Controls

| Key | Action |
|-----|--------|
| D | Cycle dithering (Floyd/Bayer/Atkinson/None) |
| T | Toggle threshold (Auto/Manual) |
| +/- | Adjust threshold ±10 |
| [/] | Adjust threshold ±1 |
| B/b | Brightness +/- |
| C/c | Contrast +/- |
| G/g | Gamma +/- |
| M | Toggle color mode (Mono/Color) |
| R | Reset all settings |
| H | Help |
| Q | Quit |

### What the settings do

- **Dithering**: How dots are distributed. Floyd-Steinberg = smooth gradients, Bayer = patterned, Atkinson = high contrast, None = pure threshold
- **Threshold**: Brightness cutoff for black vs white. Auto (Otsu) calculates optimal value. Manual lets you pick 0-255
- **Brightness/Contrast/Gamma**: Standard image adjustments. Useful for dark or washed-out sources

## Performance

| Operation | Time |
|-----------|------|
| Frame render (80×24) | ~2μs |
| Image load + render | ~10ms |
| 60fps animation budget | 16.6ms (we use 1.6μs) |

## License

MIT OR Apache-2.0