dotmax

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

Browse the live style catalog: dotmax-sable.vercel.app

664 loading animations, built in

dotmax::progress ships 664 loading bars, spinners, borders, wipes and meters across 59 themes (matrix rain, synthwave, demoscene, aurora, fire, glitch, fireworks, fractals, cellular automata, sacred geometry, retro consoles, ...). Every style is a stateless pure function of (progress, time) — preview them all running live on the site, then take any of them home as a dotmax snippet, a dependency-free standalone .rs file, or a plain shell script.

use dotmax::progress::{styles_for_theme, render_string, BarContext, Easing};

let styles = styles_for_theme("matrix");
let ctx = BarContext::new(0.42, 1.5, 44, 4).with_easing(Easing::CubicInOut);
println!("{}", render_string(styles[0].as_ref(), &ctx).unwrap());

Gallery

Color Rendering

Full-color image rendering with braille dots	Color rendering with tuner overlay
High-detail color closeup	Medium-resolution color render

Monochrome & Pixel Sizes

8px monochrome braille	Small pixel density
Small pixel snake render	Large pixel with shading enabled
Large pixel monochrome	Animated GIF playback in terminal

3D, Audio & More

3D sphere wireframe (OBJ rendering)	Sphere with I/O overlay
3D snake head model	Audio spectrograph visualization
Grid/oscilloscope formation

Install

cargo add dotmax --features image

One-Line Usage

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

# 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

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

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

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

# 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

cargo run --example webcam_tuner --features video

Video/Image Tuner

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

Tuner Controls

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

License

MIT OR Apache-2.0