Ascim is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install ascim

It will make the ascim command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall ascim uninstalls.

Adding `ascim` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add ascim

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

ascim = "1.0.0"

The ascim library will be automatically available globally. Read the ascim library documentation.

Back to the crate overview.

Readme

ascim

A small Rust command-line tool and library for converting images to ASCII art. Useful for quick previews, terminal wallpapers, demos, or embedding simple text-based representations of images.

Installation

cargo install ascim

Usage

Basic CLI usage:

# print image.png to ASCII on stdout
ascim  image.png

As Library

  use ascim::{AsciImage, Arguments};
    
     fn main() -> Result<(), Box<dyn std::error::Error>> {
         let args = Arguments {
             file_path: String::from("examples/image.png"),
             max_width: 80,
             max_height: 40,
            character_ratio: 2.0,
            edge_threshold: 1.0,
         };
    
         let ascii = AsciImage::from_args(&args);
    
         ascii.print();
    
         Ok(())
     }

Features

Convert images to ASCII art with configurable width and character set
Support for color output (ANSI) and plain monochrome output
Library API for integration into other Rust projects
Fast, memory-efficient processing using Rust image crates

Configuration

Common options:

width: target output width in characters
color: enable ANSI color output
charset: character set to use for density mapping
invert: invert brightness mapping

Contributing

Contributions are welcome. Open issues for bugs or feature requests and submit PRs for fixes or improvements. Keep changes small and include tests where applicable.

License

MIT OR Apache-2.0 — see LICENSE file for details.

Acknowledgements & Inspiration

This project was inspired by and builds upon ideas from the ascii-view project:

Original inspiration: gouwsxander/ascii-view
Why it inspired this work:
- Clear approach to mapping pixel brightness to ASCII density characters.
- Practical techniques for terminal-friendly resizing and aspect-ratio correction.
- Useful examples of combining color (ANSI) with character-based rendering.

Credit and differences:

Credit: many of the algorithmic ideas and mapping choices were inspired by the linked project; thanks to the original author for the clear, educational implementation.
Differences in ascim:
- Exposes a small library API (AsciImage / Arguments) for integration in other Rust programs.
- Adds configurable edge-detection options and slightly different character sets.
- Focuses on producing compact, publishable crate documentation and examples.

If you'd like your repository acknowledged differently (additional attribution, direct quote, or a link to a specific file/commit), tell me what to include and I'll update this section.

Installing the command-line executable

Adding ascim library as a dependency

Adding `ascim` library as a dependency