A cross-platform command-line tool to convert images into ascii art and print them on the console.
Ascii-Image-Converter: Transforming Images into Text-Based Art
Ascii-image-converter is a versatile cross-platform command-line tool designed to convert various image formats into ASCII art, displaying them directly on your console. This innovative utility now also supports Braille art, offering even more creative possibilities for text-based visualizations.
Key Features:
Multi-Format Support: Convert images in popular formats such as JPEG, PNG, BMP, WEBP, TIFF, and GIF into ASCII or Braille art with ease.
Customization Options: Utilize command-line flags to adjust color schemes, dimensions, and other settings, allowing for precise control over the output's appearance.
Cross-Platform Compatibility: Run seamlessly on Windows, Linux, and macOS, making it accessible to a wide range of users.
README
ascii-image-converter
ascii-image-converter is a command-line tool that converts images into ascii art and prints them out onto the console. Available on Windows, Linux and macOS.
VideoToAscii converts and streams any video file or webcam input as colourful ASCII characters directly in your terminal. Supports multiple conversion strategies, optional audio playback and output files.
Convert 1000s of files between more than 100 text encodings and binary formats: Unicode, ANSI, Latin, Cyrillic, ASCII, UTF8, ISO, OEM, Mac, Base-64, Bin-Hex, Quoted-Printable.
Save raw bytes from files as hex, dec, or bin ASCII byte code representations, and convert them back to bytes.
Includes automatic encoding detection, Big Endian, and Unicode support.
Process 1000s of files using multiple CPU cores in manual, automatic, scheduled, console modes, or directly from Windows Explorer right-click menu.
Save files to output directory specified using either absolute or relative path, with original or new name defined by a mask.
Select files for processing based on their name, dates, size, and contents using advanced file search supporting RegEx and advanced wildcards.
Perform different operations on different files with conditional processing and process branching.
Detailed processing logs are available in both user interface and log files.
Run multiple program instances simultaneously.
VideoToAscii converts and streams any video file or webcam input as colourful ASCII characters directly in your terminal. Supports multiple conversion strategies, optional audio playback and output files.
Convert 1000s of files between more than 100 text encodings and binary formats: Unicode, ANSI, Latin, Cyrillic, ASCII, UTF8, ISO, OEM, Mac, Base-64, Bin-Hex, Quoted-Printable.
Save raw bytes from files as hex, dec, or bin ASCII byte code representations, and convert them back to bytes.
Includes automatic encoding detection, Big Endian, and Unicode support.
Process 1000s of files using multiple CPU cores in manual, automatic, scheduled, console modes, or directly from Windows Explorer right-click menu.
Save files to output directory specified using either absolute or relative path, with original or new name defined by a mask.
Select files for processing based on their name, dates, size, and contents using advanced file search supporting RegEx and advanced wildcards.
Perform different operations on different files with conditional processing and process branching.
Detailed processing logs are available in both user interface and log files.
Run multiple program instances simultaneously.
VideoToAscii converts and streams any video file or webcam input as colourful ASCII characters directly in your terminal. Supports multiple conversion strategies, optional audio playback and output files.
Convert 1000s of files between more than 100 text encodings and binary formats: Unicode, ANSI, Latin, Cyrillic, ASCII, UTF8, ISO, OEM, Mac, Base-64, Bin-Hex, Quoted-Printable.
Save raw bytes from files as hex, dec, or bin ASCII byte code representations, and convert them back to bytes.
Includes automatic encoding detection, Big Endian, and Unicode support.
Process 1000s of files using multiple CPU cores in manual, automatic, scheduled, console modes, or directly from Windows Explorer right-click menu.
Save files to output directory specified using either absolute or relative path, with original or new name defined by a mask.
Select files for processing based on their name, dates, size, and contents using advanced file search supporting RegEx and advanced wildcards.
Perform different operations on different files with conditional processing and process branching.
Detailed processing logs are available in both user interface and log files.
Run multiple program instances simultaneously.
Braille Art Support: Create Braille art with adjustable thresholds and dithering options, enhancing visual clarity in text-based environments.
Package Manager Integration: Install via winget or other package managers for convenient setup across different operating systems.
Audience & Benefits:
Ideal for developers, designers, and creative enthusiasts seeking to incorporate ASCII or Braille art into their projects, ascii-image-converter offers a flexible toolset for generating visually appealing text-based images. Its command-line interface allows for quick integration into workflows, making it perfect for both casual use and professional applications.
Whether you're crafting artistic visualizations or need a reliable method for image processing in terminal environments, ascii-image-converter provides a powerful solution tailored to your needs.
go install github.com/TheZoraiz/ascii-image-converter@latest
For physically installing the binaries, follow the steps with respect to your OS.
Linux
Download the archive for your distribution's architecture here, extract it, and open the extracted directory.
Now, open a terminal in the same directory and execute this command:
sudo cp ascii-image-converter /usr/local/bin/
Now you can use ascii-image-converter in the terminal. Execute ascii-image-converter -h for more details.
Windows
You will need to set an Environment Variable to the folder the ascii-image-converter.exe executable is placed in to be able to use it in the command prompt. Follow the instructions in case of confusion:
Download the archive for your Windows architecture here, extract it, and open the extracted folder. Now, copy the folder path from the top of the file explorer and follow these instructions:
In Search, search for and then select: Advanced System Settings
Click Environment Variables. In the section User Variables find the Path environment variable and select it. Click "Edit".
In the Edit Environment Variable window, click "New" and then paste the path of the folder that you copied initially.
Click "Ok" on all open windows.
Now, restart any open command prompt and execute ascii-image-converter -h for more details.
CLI Usage
> Note: Decrease font size or increase terminal width (like zooming out) for maximum quality ascii art
The basic usage for converting an image into ascii art is as follows. You can also supply multiple image paths and urls as well as a GIF.
ascii-image-converter [image paths/urls]
Example:
ascii-image-converter myImage.jpeg
> Note: Piped binary input is also supported
> > cat myImage.png | ascii-image-converter - >
Flags
--color OR -C
> Note: Your terminal must support 24-bit or 8-bit colors for appropriate results. If 24-bit colors aren't supported, 8-bit color escape codes will be used
Display ascii art with the colors from original image.
ascii-image-converter [image paths/urls] -C
# Or
ascii-image-converter [image paths/urls] --color
--braille OR -b
> Note: Braille pattern display heavily depends on which terminal or font you're using. In windows, try changing the font from command prompt properties if braille characters don't display
Use braille characters instead of ascii. For this flag, your terminal must support braille patters (UTF-8) properly. Otherwise, you may encounter problems with colored or even uncolored braille art.
ascii-image-converter [image paths/urls] -b
# Or
ascii-image-converter [image paths/urls] --braille
--threshold
Set threshold value to compare for braille art when converting each pixel into a dot. Value must be between 0 and 255.
Apply dithering on image to make braille art more visible. Since braille dots can only be on or off, dithering images makes them more visible in braille art.
If any of the coloring flags is passed, this flag will transfer its color to each character's background. instead of foreground. However, this option isn't available for --save-img and --save-gif
> Note: Don't immediately append another flag with -W
Set width of ascii art. Height is calculated according to aspect ratio.
ascii-image-converter [image paths/urls] -W
# Or
ascii-image-converter [image paths/urls] --width
Example:
ascii-image-converter [image paths/urls] -W 60
--height OR -H
> Note: Don't immediately append another flag with -H
Set height of ascii art. Width is calculated according to aspect ratio.
ascii-image-converter [image paths/urls] -H
# Or
ascii-image-converter [image paths/urls] --height
Example:
ascii-image-converter [image paths/urls] -H 60
--map OR -m
> Note: Don't immediately append another flag with -m
Pass a string of your own ascii characters to map against. Passed characters must start from darkest character and end with lightest. There is no limit to number of characters.
Empty spaces can be passed if string is passed inside quotation marks. You can use both single or double quote for quotation marks. For repeating quotation mark inside string, append it with \ (such as \").
> Note: This is an experimental feature and may not result in the finest quality GIFs, because all GIFs still aren't supported by ascii-image-converter.
Saves the passed GIF as an ascii art GIF with the name -ascii-art.gif in the directory path passed to the flag.
--save-bg
> Note: This flag will be ignored if --save-img or --save-gif flags are not set
This flag takes an RGBA value that sets the background color in saved png and gif files. The fourth value (alpha value) is the measure of background opacity ranging between 0 and 100.
ascii-image-converter [image paths/urls] -s . --save-bg 255,255,255,100 # For white background
--font
> Note: This flag will be ignored if --save-img or --save-gif flags are not set
This flag takes path to a font .ttf file that will be used to set font in saved png or gif files.
> Note: The library may throw errors during Go tests due to some unresolved bugs with the consolesize-go package (Only during tests, not main program execution).
First, install the library with:
go get -u github.com/TheZoraiz/ascii-image-converter/aic_package
For an image:
package main
import (
"fmt"
"github.com/TheZoraiz/ascii-image-converter/aic_package"
)
func main() {
// If file is in current directory. This can also be a URL to an image or gif.
filePath := "myImage.jpeg"
flags := aic_package.DefaultFlags()
// This part is optional.
// You can directly pass default flags variable to aic_package.Convert() if you wish.
// There are more flags, but these are the ones shown for demonstration
flags.Dimensions = []int{50, 25}
flags.Colored = true
flags.SaveTxtPath = "."
flags.SaveImagePath = "."
flags.CustomMap = " .-=+#@"
flags.FontFilePath = "./RobotoMono-Regular.ttf" // If file is in current directory
flags.SaveBackgroundColor = [4]int{50, 50, 50, 100}
// Note: For environments where a terminal isn't available (such as web servers), you MUST
// specify atleast one of flags.Width, flags.Height or flags.Dimensions
// Conversion for an image
asciiArt, err := aic_package.Convert(filePath, flags)
if err != nil {
fmt.Println(err)
}
fmt.Printf("%v\n", asciiArt)
}
> Note: GIF conversion is not advised as the function may run infinitely, depending on the GIF. More work needs to be done on this to make it more library-compatible.
You can fork the project and implement any changes you want for a pull request. However, for major changes, please open an issue first to discuss what you would like to implement.
