ascii-image-converter

Convert an image into ASCII

$ ascii-image-converter [path/to/image|URL]

$ ascii-image-converter [[-C|--color]] [path/to/image|URL]

$ ascii-image-converter [[-b|--braille]] [path/to/image|URL]

$ ascii-image-converter [[-b|--braille]] --dither [path/to/image|URL]

$ ascii-image-converter [[-Cn|--color --negative]] [path/to/image|URL]

$ ascii-image-converter [[-c|--complex]] [path/to/image|URL]

ascii-image-converter [OPTIONS] <IMAGE_PATH>...

Example:
ascii-image-converter --color -d 80x40 image.jpg
ascii-image-converter -t -S output.txt my_pic.png another_pic.gif

<IMAGE_PATH>...
    One or more paths to the image files to be converted. Supports various common image formats.

-c, --color
    Enables color output using terminal's ANSI color codes, attempting to match original image colors.

-g, --grayscale
    Converts the image to grayscale ASCII art. Mutually exclusive with --color.

-r, --reverse
    Reverses the character mapping, using darker characters for brighter pixels and vice versa.

-H <rows>, --height <rows>
    Sets the maximum output height in characters. Width is adjusted proportionally unless --width is also specified.

-W <cols>, --width <cols>
    Sets the maximum output width in characters. Height is adjusted proportionally unless --height is also specified.

-d <WxH>, --dimensions <WxH>
    Sets both width and height simultaneously (e.g., 80x24). Overrides --width and --height.

-s, --stretched
    Stretches the output to fill the terminal's width, potentially distorting aspect ratio.

-t, --term-size
    Adjusts the output dimensions to fit the current terminal window size, maintaining aspect ratio.

-S <path>, --save-output <path>
    Saves the generated ASCII art to the specified file instead of printing to standard output.

-C <chars>, --custom-charset <chars>
    Uses a custom string of characters (e.g., " .:-=+*#%@") for ASCII conversion, ordered from darkest to lightest.

--clear
    Clears the terminal screen before displaying the ASCII art.

-h, --help
    Displays the help message and exits.

-v, --version
    Prints version information and exits.

ascii-image-converter is a versatile command-line tool designed to transform various image formats (such as JPG, PNG, GIF, and BMP) into textual representations known as ASCII art. It renders these textual images directly within the terminal, or can save them to a file for later use. The tool offers a rich set of options to customize the output, including support for color and grayscale modes, adjustable dimensions, and the ability to use custom character sets. It intelligently maps image pixel brightness to a range of ASCII characters, allowing for surprising detail and artistic effect. Users can also specify output to stretch to terminal size, reverse character mapping, or save the output to a file. This makes it ideal for quick image previews in terminal-only environments, generating unique visual content for scripts, or simply for creative expression and fun.

Optimal rendering of ASCII art in the terminal largely depends on the terminal's font being monospace.
Highly detailed or complex images may not translate perfectly due to the inherent limitations of character-based representation.
Color accuracy can vary across different terminal emulators and color schemes.

The command typically uses a default character set (e.g., ' .,:;irsXA253hMHGS#9B&@' or a similar range) for mapping pixel brightness to ASCII characters. Characters on the left are used for darker areas, and those on the right for brighter areas. The --custom-charset option allows users to define their own mapping.

ascii-image-converter is often installed via a package manager (e.g., Homebrew on macOS, or specific Linux distribution repositories) or built from source using Go (e.g., go install github.com/TheDarkBug/ascii-image-converter@latest).

jp2a(1), cowsay(6), convert(1) (ImageMagick), ffmpeg(1)