artbox

Render FIGlet text, sprites, and images into a bounded rectangle with colors and gradients.

cargo add artbox

Quick Start

use artbox::render;

let result = render("Hello", 40, 8)?;
println!("{}", result.to_plain_string());

Output:

 _   _      _ _
| | | | ___| | | ___
| |_| |/ _ \ | |/ _ \
|  _  |  __/ | | (_) |
|_| |_|\___|_|_|\___/

Gradients

use artbox::{Renderer, Fill, LinearGradient, ColorStop, Color};

let renderer = Renderer::default()
    .with_fill(Fill::Linear(LinearGradient::new(
        45.0,
        vec![
            ColorStop::new(0.0, Color::rgb(255, 0, 128)),
            ColorStop::new(1.0, Color::rgb(0, 128, 255)),
        ],
    )));

let rendered = renderer.render("Hi", 20, 6)?;
print!("{}", rendered.to_ansi_string());

Supports solid colors, linear gradients (any angle), and radial gradients.

Unified API

Artbox provides a single entrypoint for text, sprites, and images:

use artbox::{Artbox, Alignment, RenderTarget};

let art = Artbox::default().with_alignment(Alignment::Center);
let target = RenderTarget::new(80, 24);

let rendered = art.render_text("Hello", target)?;
print!("{}", rendered.to_ansi_string());

Sprites

Multi-size layered ASCII sprites with per-layer gradient fills:

use artbox::{Sprite, Fill, Color};
use artbox::sprites::{SpriteLayer, SpriteVariant};

let layer = SpriteLayer::new("\\o/").with_fill(Fill::solid(Color::rgb(255, 200, 0)));
let variant = SpriteVariant::new("small", vec![layer]);
let sprite = Sprite::new(vec![variant]);

let rendered = sprite.render(40, 10)?;
print!("{}", rendered.to_ansi_string());

Font Families

Built-in font families with size fallback:

use artbox::{Renderer, fonts};

// Blocky pixel style
let renderer = Renderer::new(fonts::family("blocky").unwrap());

// Available families: banner, blocky, script, slant
// Default stack: big -> standard -> small -> mini

Custom stacks:

let renderer = Renderer::new(fonts::stack(&["slant", "small_slant"]));

Load external fonts:

let font = Font::from_file("path/to/font.flf")?;

Alignment

use artbox::{Renderer, Alignment};

let renderer = Renderer::default()
    .with_alignment(Alignment::Center)  // or TopLeft, BottomRight, etc.
    .with_letter_spacing(-1);           // negative = overlap

Buffer Reuse

For hot paths, reuse the output buffer:

let mut buffer = String::new();
let metrics = renderer.render_into("Text", 40, 10, &mut buffer)?;

Images

Enable the images feature for image-to-ASCII and terminal image protocols:

artbox = { version = "0.2", features = ["images"] }

use artbox::{Artbox, RenderTarget};

let art = Artbox::default();
let target = RenderTarget::new(80, 24);
let rendered = art.render_image_path("image.png", target)?;
print!("{}", rendered.to_ansi_string());

ratatui Widget

Enable the ratatui feature:

artbox = { version = "0.2", features = ["ratatui"] }

use artbox::integrations::ratatui::{ArtBox, SpriteBox};

let widget = ArtBox::new(&renderer, "Hello");
frame.render_widget(widget, area);

let sprite_widget = SpriteBox::new(&sprite);
frame.render_widget(sprite_widget, area);

Examples

# Text with gradient
cargo run --example gradient -- "Hello" 60 10 --gradient diagonal --from 255,0,128 --to 0,128,255

# Unified API (text + sprites)
cargo run --example artbox

# Sprite layers with per-layer gradients
cargo run --example sprite_gradients

# Image to ASCII (defaults to ruby.svg)
cargo run --example image --features images

# ratatui TUI
cargo run --example tui --features ratatui

Docs

Hosted docs: https://dmk.github.io/artbox

Local docs:

cd docs
npm install
npm run dev