イメジ ー Images for the terminal
imeji is a lightweight alternative to the awesome chafa. It is written in go and can be easily embedded into tools. imeji takes a image as input and creates a sequence of characters and ansi color sequences resulting in a terminal printable images.
Why not use chafa?
If you can install chafa it should be preferred, as it is more advanced, faster and just awesome! But if you want to include terminal image output in your go application and don't want to ship chafa as external dependency imeji might be worth a try.
イメジ :: Images for the terminal ー by BigJk _ _ _ (_)_ __ ___ ___ (_|_) | | '_ ` _ \ / _ \| | | | | | | | | | __/| | | |_|_| |_| |_|\___|/ |_| |__/ _________________________________________ -font-scale float vertical font scaling value (default: 0.8) -force-full-color forces full color output -help print help -input string input image path -max-width int sets the max width of the output (in cells) and keeps the aspect ratio -size string size in terminal cells (e.g. 100x20) -symbols string which symbole sets to use (blocks, blocks_simple, blocks_adv, ascii, misc) (default "blocks")
go install github.com/BigJk/imeji/cmd/imeji@latest
go get github.com/BigJk/imeji
// Print directly to stdout and detect terminal capabilities: imeji.File(os.Stdout, "./image.png", imeji.WithMaxWidth(100)) // Convert to string with full color support: text, _ := imeji.FileString("./image.png", imeji.WithTrueColor()) fmt.Println(text)
I didn't find a good written reference on the technique used by Chafa and other tools so here is a basic overview. Its important to know that in the terminal we are limited to a single foreground and background color per character. That means for each cell in the terminal we need to find the best character and foreground, background pair with the least "error" (difference) to the real picture.
The basic idea is that you can map a single character in terminal to 8x8 pixels of a real image. For each character that wants to be used in a terminal picture the pattern needs to be created. A pattern can easily be defined by an 8 line string. The pattern defines which pixels are set to the foreground color and which to the background color.
/charmaps/blocks.go and you will quickly get the idea.
- Char: █ (Full Block -> All pixel set)
XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX
- Char: !
________ ___X____ ___X____ ___X____ ___X____ ________ ___X____ ________
Now that we know how to define the pattern for a character we can convert a image to terminal printable characters.
- Chunk the image into 8x8 pixel chunks
- For each pixel chunk:
- Randomly select a few (foreground, background) pairs from the pixels in the chunk
- For all the pairs test all characters and calculate the error to the real pixels
- Return the pair and character with the least error
- For each chunk print the selected character with the chosen foreground and background
- Better handling of alpha channel
- Use assembler with SIMD instructions to improve pixel to pattern diffing performance