imeji

README

imeji

イメジ ー 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.

CLI

イメジ :: 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")

Install imeji command

go install github.com/BigJk/imeji/cmd/imeji@latest

Go Library

go get github.com/BigJk/imeji

Example

// 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)

Technique

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.

Pattern

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)

XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX

• Char: !

________
___X____
___X____
___X____
___X____
________
___X____
________

Procedure

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

Further Work

• Better handling of alpha channel
• Use assembler with SIMD instructions to improve pixel to pattern diffing performance

Documentation

Index

• func BasicSelection(options *OptionData, pixel []color.Color) (string, color.Color, color.Color)
• func File(out io.Writer, path string, options ...Option) error
• func FileString(path string, options ...Option) (string, error)
• func Image(out io.Writer, img image.Image, options ...Option) error
• func ImageString(img image.Image, options ...Option) (string, error)
• type Option
  • func WithANSI() Option
  • func WithANSI256() Option
  • func WithBrightness(change float64) Option
  • func WithColorPairMax(pairs int) Option
  • func WithContrast(change float64) Option
  • func WithCrop(x int, y int, width int, height int) Option
  • func WithFlip(h bool, v bool) Option
  • func WithFontScaling(scale float64) Option
  • func WithGrayScale() Option
  • func WithMaxRoutines(routines int) Option
  • func WithMaxWidth(width int) Option
  • func WithPattern(pattern ...[]charmaps.Pattern) Option
  • func WithResize(width int, height int) Option
  • func WithSaturation(change float64) Option
  • func WithSharpen(times int) Option
  • func WithTrueColor() Option
• type OptionData

Functions

func BasicSelection

func BasicSelection(options *OptionData, pixel []color.Color) (string, color.Color, color.Color)

BasicSelection finds the best character, foreground and background pair matching the 8x8 pixel grid.

func File

func File(out io.Writer, path string, options ...Option) error

File decodes the image from a file and builds a terminal printable image of it.

func FileString

func FileString(path string, options ...Option) (string, error)

FileString decodes the image from a file and builds a terminal printable image of it. Returns the ansi string.

func Image

func Image(out io.Writer, img image.Image, options ...Option) error

Image decodes the images and builds a terminal printable image of it.

func ImageString

func ImageString(img image.Image, options ...Option) (string, error)

ImageString decodes the images and builds a terminal printable image of it. Returns the ansi string.

Types

type Option

type Option func(data *OptionData)

func WithANSI

func WithANSI() Option

WithANSI enables basic ansi color support. This is important if you don't output to os.Stdout and no terminal detection can be done or if you want to force a color mode.

func WithANSI256

func WithANSI256() Option

WithANSI256 enables 256 color support. This is important if you don't output to os.Stdout and no terminal detection can be done or if you want to force a color mode.

func WithBrightness

func WithBrightness(change float64) Option

WithBrightness changes the brightness of the image.

func WithColorPairMax

func WithColorPairMax(pairs int) Option

WithColorPairMax specifies how many color pair possibilities the algorithm will try per 8x8 pixel chunk. Lower value results in better performance but colors and selected symbols might be suboptimal. Values between 1 and 12 are sensible. Default is 6.

func WithContrast

func WithContrast(change float64) Option

WithContrast changes the contrast of the image.

func WithCrop

func WithCrop(x int, y int, width int, height int) Option

WithCrop crops a part of the image. This uses the normal image coordinates.

func WithFlip

func WithFlip(h bool, v bool) Option

WithFlip flips the picture vertically or horizontal.

func WithFontScaling

func WithFontScaling(scale float64) Option

WithFontScaling sets the vertical font scaling size, as most terminal fonts are taller than wider.

func WithGrayScale

func WithGrayScale() Option

WithGrayScale changes the image to grayscale.

func WithMaxRoutines

func WithMaxRoutines(routines int) Option

WithMaxRoutines specifies how many go routines are allowed to be spawned for calculating the image.

func WithMaxWidth

func WithMaxWidth(width int) Option

WithMaxWidth specifies a max width in cells for the output. This will keep the aspect ratio of the input picture and scale based on specified font ratio.

func WithPattern

func WithPattern(pattern ...[]charmaps.Pattern) Option

WithPattern specifies the character patterns that are usable in the algorithms. More patterns decrease the performance.

func WithResize

func WithResize(width int, height int) Option

func WithSaturation

func WithSaturation(change float64) Option

WithSaturation changes the saturation of the image.

func WithSharpen

func WithSharpen(times int) Option

WithSharpen sharpens the images before conversion.

func WithTrueColor

func WithTrueColor() Option

WithTrueColor enables true color support. This is important if you don't output to os.Stdout and no terminal detection can be done or if you want to force a color mode.

type OptionData

type OptionData struct {
	// contains filtered or unexported fields
}