fnordpig/rascii

Advanced image to ASCII art tool & crate written in Rust 🦀🚀

Advanced ASCII Art Generator

Usage: rascii [OPTIONS] <FILENAME>

Arguments:
  <FILENAME>  Path to the image

Options:
  -w, --width <WIDTH>      Width of the output image. Defaults to 128 if width and height are not specified
  -H, --height <HEIGHT>    Height of the output image, if not specified, it will be calculated to keep the aspect ratio
  -c, --color              Whether to use colors in the output image
  -i, --invert             Inverts the weights of the characters. Useful for white backgrounds
  -C, --charset <CHARSET>  Characters used to render the image, from transparent to opaque. Built-in charsets: block, emoji, default, russian, slight [default: default]
  -h, --help               Print help
  -V, --version            Print version

Features

• Available as a crate: RASCII has a very simple API allowing you to RASCII from your programs without using the system shell.

• Colored ASCII art generation: RASCII uses ANSI color codes to generate colored ASCII art.

  Note Your terminal emulator has to support truecolor (don't worry, almost all modern terminal emulators do).

• Super efficient colored output: RASCII never repeats the same ANSI color code if it is already active.

  This makes a huge difference in images with little alternating color, up to about 1800% reduction in output size. Woah!

• Custom dimensions: RASCII allows you to give custom dimensions to the outputted ASCII art while keeping the aspect ratio (unless both dimensions are provided).

• Custom charsets: RASCII allows you to use custom charsets to generate your ASCII art.

  Note The given charset must go from transparent to opaque.

• Lots of pre-included charsets.

Installing The CLI

Via Cargo

Note this is the recommended way of installing the RASCII CLI.

Warning you must have ~/.cargo/bin/ in $PATH to call rascii

cargo install rascii_art

Manually

Warning this installation method is discouraged and only works for GNU/Linux or any other POSIX compatible systems!

git clone https://github.com/KoBruhh/RASCII && cd RASCII
chmod +x install.sh
./install.sh

Using The Crate

Instead of using the unreliable system shell to call RASCII, you can add the rascii_art crate to your project and use it in Rust!.

To do so, run cargo add rascii_art to add RASCII to your Cargo project.

Here is a code example:

use rascii_art::{
    render_to,
    RenderOptions,
};

fn main() {
    let mut implements_io_write = String::new();

    render_to(
        "ferris.png",
        &mut implements_io_write,
        RenderOptions::new()
            .width(100)
            .colored(true)
            .charset(&[".", ",", "-", "*", "£", "$", "#"]),
    )
    .unwrap();

    println!("{implements_io_write}");
}

Showcase

Japanese Charset

Emoji Charset

Note The emoji charset does not guarantee your outputs color will match the color of your image, this is just a coincidence that happened with Ferris.

Chinese Charset

Block Charset

Custom ASCII Charset

You can use the --charset CLI option to provide a charset to use when generating some ASCII art.

The value of this must option must go from transparent to opaque, like so:

rascii --charset " ░▒▓█" --color ferris.png

Note that a chaset similar to the above charset is available as a builtin named block.

Amogus

Contributors