image2ascii Documentation

You can install the command-line tool using go install to convert images to ASCII directly from your terminal.

go install github.com/qeesung/image2ascii@latest

To use image2ascii within a Go application, import the convert package. You can create a new converter using convert.NewImageConverter() and use it to transform image files into ASCII strings.

package main

import (
	"fmt"
	"github.com/qeesung/image2ascii/convert"
	_ "image/jpeg"
	_ "image/png"
)

func main() {
	// Create convert options
	convertOptions := convert.DefaultOptions
	convertOptions.FixedWidth = 100
	convertOptions.FixedHeight = 40

	// Create the image converter
	converter := convert.NewImageConverter()
	// Note: replace imageFilename with your actual file path
	fmt.Print(converter.ImageFile2ASCIIString("path/to/image.jpg", &convertOptions))
}

The Converter interface provides the core methods for transforming images into ASCII representations, either as a matrix of strings or as a single joined string.

type Converter interface {
	// convert a image object to ascii matrix
	Image2ASCIIMatrix(image image.Image, imageConvertOptions *Options) []string
	// convert a image object to ascii matrix and then join the matrix to a string
	Image2ASCIIString(image image.Image, options *Options) string
	// convert a image object by input a string to ascii matrix
	ImageFile2ASCIIMatrix(imageFilename string, option *Options) []string
	// convert a image object by input a string to ascii matrix then join the matrix to a string
	ImageFile2ASCIIString(imageFilename string, option *Options) string
}

Available flags for the image2ascii command line tool:

Options:
  -c    Colored the ascii when output to the terminal (default true)
  -f string
        Image filename to be convert (default "docs/images/lufei.jpg")
  -g int
        Expected image height, -1 for image default height (default -1)
  -i    Reversed the ascii when output to the terminal
  -r float
        Ratio to scale the image, ignored when use -w or -g (default 1)
  -s    Fit the terminal screen, ignored when use -w, -g, -r (default true)
  -t    Stretch the picture to overspread the screen
  -w int
        Expected image width, -1 for image default width (default -1)

The Options struct defines how the image is converted. Note that some options like FitScreen, StretchedScreen, and Colored are only applicable when outputting to a terminal.

type Options struct {
	Ratio           float64 // convert ratio
	FixedWidth      int  // convert the image width fixed width
	FixedHeight     int  // convert the image width fixed height
	FitScreen       bool // only work on terminal, fit the terminal height or width
	StretchedScreen bool // only work on terminal, stretch the width and heigh to overspread the terminal screen
	Colored         bool // only work on terminal, output ascii with color
	Reversed        bool // if reverse the ascii pixels
}

The image2ascii command converts images to ASCII art. It supports various scaling modes including fitting to terminal, fixed dimensions, or using a scaling ratio.

# Fit the image to the terminal screen (default)
image2ascii -f docs/images/pikaqiu2.jpg

# Convert with fixed width and height
image2ascii -f docs/images/baozou.jpg -w 100 -g 30

# Convert using a scaling ratio (e.g., 0.3 of original size)
image2ascii -f docs/images/pikaqiu.jpg -r 0.3

# Stretch the image to overspread the terminal screen
image2ascii -f docs/images/long.jpg -t

# Convert without color
image2ascii -f docs/images/lufei.jpg -s -c=false

# Disable fitting to screen
image2ascii -f docs/images/lufei.jpg -s=false

# Reverse the ASCII characters
image2ascii -f docs/images/lufei.jpg -i