ansee

A command-line tool for converting ANSI-escaped text to images. Supports 256 colors, RGB colors, and custom fonts.

Features

• Convert ANSI-escaped text to PNG images
• Support for standard ANSI colors (16 colors)
• Extended color support (256 colors)
• True color support (RGB)
• Custom font support
• Configurable font size and line height
• Input from file or stdin
• Output to file or stdout

Installation

Make sure you have Rust installed on your system. Then:

# Clone the repository
git clone https://github.com/codersauce/ansee
cd ansee

# Build and install
cargo install --path .

Usage

# Convert ANSI text from stdin
echo -e "\033[31mHello\033[0m \033[32mWorld\033[0m" | ansee -f "Fira Code"

Basic Usage

# Convert ANSI text from a file
ansee input.txt -o output.png

# Use a specific font
ansee input.txt -f "Fira Code" -o output.png

# Customize font size and line height
ansee input.txt -s 24 -e 1.5 -o output.png

Available Fonts

To know which fonts your system support for the -f option, use the list-fonts command:

> $ ansee list-fonts
.SF NS Mono
  .SF NS Mono Light
  .SF NS Mono Light Italic

(...)

Fira Code
  Fira Code Bold
  Fira Code Regular

Fira Code Light
  Fira Code Light

Fira Code Medium
  Fira Code Medium

Fira Code Retina
  Fira Code Retina

Fira Code SemiBold
  Fira Code SemiBold

(...)

Available Options

Usage: ansee [OPTIONS] [INPUT] [COMMAND]

Arguments:
  [INPUT]  Input file to render or stdin if not present

Options:
  -o, --output <OUTPUT>        Output file to write to or stdout if not present
  -f, --font <FONT>           Font used for rendering the image
  -s, --font-size <SIZE>      Font size in pixels [default: 20.0]
  -e, --line-height <HEIGHT>  Line height in a factor of height [default: 1.1]
  -h, --help                  Print help
  -V, --version              Print version

Commands:
  list-fonts  List available font families that can be used
  help        Print this message or help for given subcommand

Font Management

To list all available monospace fonts on your system:

ansee list-fonts

ANSI Support

The tool supports the following ANSI escape sequences:

• Standard colors (30-37, 40-47)
• Bright colors (90-97, 100-107)
• 256 colors (38;5;n, 48;5;n)
• RGB colors (38;2;r;g;b, 48;2;r;g;b)
• Reset (0)
• Italic (3)
• Reverse color (7)

Examples

Basic Text Coloring

echo -e "\033[31mRed Text\033[0m \033[42mGreen Background\033[0m" | ansee -o colors.png

Using 256 Colors

echo -e "\033[38;5;82mBright Green\033[0m \033[48;5;25mBlue Background\033[0m" \
    | ansee -f "FantasqueSansM Nerd Font" -o 256colors.png

Using RGB Colors

echo -e "\033[38;2;255;128;0mOrange Text\033[0m" | ansee -s 40 -f "Iosevka Heavy" -o rgb.png

Library Usage

You can use ansee as a library in your Rust projects. Add it to your Cargo.toml:

[dependencies]
ansee = { git = "https://github.com/codersauce/ansee" }

Example

use ansee::draw_image;

fn main() -> anyhow::Result<()> {
    // Create ANSI-escaped text
    let input = "\x1b[31mHello\x1b[0m \x1b[32mWorld\x1b[0m";

    // Generate the image with the specified system font, you can use a string
    // with font_name:font_size:line_height and convert it to a Font with
    // `.try_into` like below
    let image = draw_image(input, "FantasqueSansM Nerd Font:18".try_into()?)?;

    // Save to file
    image.save("output.png")?;

    Ok(())
}

API Reference

draw_image

pub fn draw_image(
    input: &str,
    font_info: Font
) -> anyhow::Result<ImageBuffer<Rgba<u8>, Vec<u8>>>

Converts ANSI-escaped text to an image. Returns an ImageBuffer that can be saved or manipulated further.

Font struct

pub struct Font {
    pub name: Option<String>,     // Font name (uses system monospace if None)
    pub size: f32,                // Font size in pixels
    pub line_height: f32,         // Line height as a factor of font size
}

Or you can convert from a colon delimited &str, like FantasqueSansM:18.0:1.2 and try_into:

draw_image("\x1b[31mHello\x1b[0m \x1b[32mWorld\x1b[0m", "FantasqueSansM:18.0:1.2".try_into()?);

The library provides full access to the same functionality as the CLI tool, allowing you to:

• Render ANSI-escaped text with color support
• Customize fonts and text appearance
• Generate images programmatically
• Integrate with existing Rust applications

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Uses ab_glyph for font rendering
• Uses image for image processing
• Uses ansi-parser for ANSI escape sequence parsing