orhnk / 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 use 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 your PATH to run rascii directly.

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 buffer = String::new();
                                                            
    render_to(
        r"/path/to/image.png",
        &mut buffer,
        &RenderOptions::new()
            .width(100)
            .colored(true)
            .charset(&[".", ",", "-", "*", "£", "$", "#"]),
    )
    .unwrap();
}

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 (or -C) CLI option to provide a custom 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 charset similar to the above charset is available as a builtin named block.

Contributors

---

Note

There is a python script at repository root that can be used to generate the above contributor ASCII Art.

python contributors.py

rascii's Issues

Unable to build on Windows 11?

Attempted to run with the recommended usage of cargo install rascii_art. However, code errors out at expanduser crate. Attached error message is included below:

   ...Other Packages/Crates
   Compiling serde v1.0.183                                                                                             
   Compiling parking_lot v0.12.1
   Compiling ahash v0.7.6
   Compiling time v0.1.45
   Compiling dirs v1.0.5                                                                                                
   Compiling pwd v1.4.0
   Compiling byteorder v1.4.3                                                                                           
   Compiling expanduser v1.2.2
   Compiling chrono v0.4.26
error[E0432]: unresolved import `pwd::Passwd`
  --> C:\Users\MyUser\.cargo\registry\src\index.crates.io-6f17d22bba15001f\expanduser-1.2.2\src\lib.rs:10:5
   |
10 | use pwd::Passwd;
   |     ^^^^^^^^^^^ no `Passwd` in the root

For more information about this error, try `rustc --explain E0432`.
error: could not compile `expanduser` (lib) due to previous error
warning: build failed, waiting for other jobs to finish...

Is there a suggested fix for this? Thanks again!

Redundant method

rascii_art::render(_image) and rascii_art::render(_image)_to accomplish the same thing, and introduce confusing.

The code is also duplicated in the library making it longer to compile and not great in code quality.

Default character set contains characters that are length 2?

In the default character set:

pub const DEFAULT: &[&str] = &[
    " ", ".", "`", "^", "\"", "\\", ",", ":", ";", "I", "l", "!", "i", ">", "<", "~", "+", "_",
    "-", "?", "]", "[", "}", "{", "1", ")", "(", "|", "\\", "\\/", "/", "t", "f", "j", "r", "x",
    "n", "u", "v", "c", "z", "X", "Y", "U", "J", "C", "L", "Q", "0", "O", "Z", "m", "w", "q", "p",
    "d", "b", "k", "h", "a", "o", "*", "#", "M", "W", "&", "8", "%", "B", "$", "@",
];

Doesn't "\\/" result in two characters? When I send this sample image into it:

This causes the line to not be a uniform length: