Repository files navigation

イメジ ー Images for the terminal

imeji is a lightweight alternative to the awesomechafa. 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.

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.

See/charmaps/blocks.go and you will quickly get the idea.

Examples:

• Char: █ (Full Block -> All pixel set)

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• 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.

1. Chunk the image into 8x8 pixel chunks
2. For each pixel chunk:
   1. Randomly select a few (foreground, background) pairs from the pixels in the chunk
   2. For all the pairs test all characters and calculate the error to the real pixels
   3. Return the pair and character with the least error
3. 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