ansiart

README

ansiart

A Go library for converting images to ANSI art. Renders images as colored terminal text using ASCII characters, Unicode block characters, or custom character sets.

Install

go get github.com/Zebbeni/ansiart

Usage

package main

import (
	"fmt"
	"image/color"

	"github.com/Zebbeni/ansiart"
	"github.com/lucasb-eyer/go-colorful"
)

func main() {
	// Render with default settings (Unicode half-blocks, true color, fit 50x40)
	result, err := ansiart.RenderFile("photo.png", ansiart.DefaultOptions())
	if err != nil {
		panic(err)
	}
	fmt.Print(result)
}

With a palette

opts := ansiart.DefaultOptions()
opts.TrueColor = false
opts.Palette = color.Palette{
	colorful.MustParseHex("#000000"),
	colorful.MustParseHex("#626262"),
	colorful.MustParseHex("#ffffff"),
}

result, _ := ansiart.RenderFile("photo.png", opts)
fmt.Print(result)

ASCII mode

opts := ansiart.DefaultOptions()
opts.CharacterMode = ansiart.Ascii
opts.AsciiCharSet = ansiart.AsciiAll
opts.ColorMode = ansiart.OneColor

result, _ := ansiart.RenderFile("photo.png", opts)
fmt.Print(result)

Custom characters

opts := ansiart.DefaultOptions()
opts.CharacterMode = ansiart.Custom
opts.CustomChars = []rune(".:+#@")
opts.SelectionMode = ansiart.DarkToLight // map by brightness
// opts.SelectionMode = ansiart.Repeat   // cycle through chars
// opts.SelectionMode = ansiart.Random   // pick at random

result, _ := ansiart.RenderFile("photo.png", opts)
fmt.Print(result)

From an image.Image

img, _, _ := image.Decode(reader)
result, err := ansiart.Render(img, ansiart.DefaultOptions())

Options

Field	Type	Default	Description
SizeMode	SizeMode	Fit	Fit preserves aspect ratio, Stretch fills exact dimensions
Width	int	50	Output width in characters
Height	int	40	Output height in characters
CharRatio	float64	0.46	Terminal character width-to-height ratio
CharacterMode	CharacterMode	Unicode	Ascii, Unicode, or Custom
AsciiCharSet	AsciiCharSet	AsciiAZ	AsciiAZ, AsciiNums, AsciiSpec, AsciiAll
UnicodeCharSet	UnicodeCharSet	UnicodeHalf	UnicodeFull, UnicodeHalf, UnicodeQuarter, UnicodeShadeLight/Med/Heavy
CustomChars	[]rune	nil	Characters for custom mode
ColorMode	ColorMode	TwoColor	OneColor (fg only) or TwoColor (fg + bg)
SelectionMode	SelectionMode	DarkToLight	How custom chars map to pixels: DarkToLight, Repeat, Random
TrueColor	bool	true	Use 24-bit RGB. Set false for palette mode
Palette	color.Palette	nil	Color palette for palette mode
Brightness	int	0	Brightness adjustment (-100 to 100)
Contrast	int	0	Contrast adjustment (-100 to 100)
Sampling	SamplingFunction	NearestNeighbor	Resize interpolation: NearestNeighbor, Bicubic, Bilinear, Lanczos2, Lanczos3, MitchellNetravali
Dithering	bool	false	Enable error diffusion dithering (palette mode only)
Serpentine	bool	false	Use serpentine scanning for dithering
DitherMatrix	DitherMatrix	FloydSteinberg	Dithering algorithm (14 options including Atkinson, Burkes, Stucki, etc.)
OutputAlpha	bool	true	Preserve transparent pixels as spaces
TrimAlpha	bool	false	Crop transparent borders from output

Dependencies

• go-colorful — color space math
• resize — image resampling
• dither — error diffusion dithering

No terminal UI dependencies. Output is raw ANSI escape sequences.

Documentation

Index

• Constants
• func Render(img image.Image, opts Options) (string, error)
• func RenderFile(path string, opts Options) (string, error)
• type AsciiCharSet
• type CharacterMode
• type ClusteredDotMatrix
• type DitherMatrix
• type DitherMode
• type Frame
  • func RenderGIF(path string, opts Options) ([]Frame, error)
• type Options
  • func DefaultOptions() Options
• type SamplingFunction
• type SelectionMode
• type SizeMode
• type UnicodeCharSet

Constants

const (
	// AlphaPlaceholder marks transparent pixels in the output.
	AlphaPlaceholder string = " "
)

Functions

func Render

func Render(img image.Image, opts Options) (string, error)

Render converts an image.Image to an ANSI art string using the given options.

func RenderFile

func RenderFile(path string, opts Options) (string, error)

RenderFile opens an image file, decodes it, and renders it to an ANSI art string.

Types

type AsciiCharSet

type AsciiCharSet int

AsciiCharSet selects which ASCII characters to use.

const (
	AsciiAZ   AsciiCharSet = iota // Letters only
	AsciiNums                     // Numbers only
	AsciiSpec                     // Special characters only
	AsciiAll                      // All ASCII characters
)

type CharacterMode

type CharacterMode int

CharacterMode selects the character set family.

const (
	Ascii   CharacterMode = iota // ASCII characters mapped by brightness
	Unicode                      // Unicode block characters
	Custom                       // User-defined characters
)

type ClusteredDotMatrix

type ClusteredDotMatrix int

ClusteredDotMatrix selects the ordered dither matrix for clustered dot dithering.

const (
	ClusteredDot4x4 ClusteredDotMatrix = iota
	ClusteredDot6x6
	ClusteredDot6x6_2
	ClusteredDot6x6_3
	ClusteredDot8x8
	ClusteredDotDiagonal6x6
	ClusteredDotDiagonal8x8
	ClusteredDotDiagonal8x8_2
	ClusteredDotDiagonal8x8_3
	ClusteredDotDiagonal16x16
	ClusteredDotHorizontalLine
	ClusteredDotVerticalLine
	ClusteredDotSpiral5x5
)

type DitherMatrix

type DitherMatrix int

DitherMatrix selects the error diffusion matrix for dithering.

const (
	FloydSteinberg DitherMatrix = iota
	Atkinson
	Burkes
	FalseFloydSteinberg
	JarvisJudiceNinke
	Sierra
	Sierra2
	Sierra3
	SierraLite
	TwoRowSierra
	Sierra2_4A
	Simple2D
	Stucki
	StevenPigeon
)

type DitherMode

type DitherMode int

DitherMode selects the dithering algorithm family.

const (
	DitherModeMatrix       DitherMode = iota // Error diffusion matrix
	DitherModeBayer                          // Bayer ordered dithering
	DitherModeClusteredDot                   // Clustered dot ordered dithering
)

type Frame

type Frame struct {
	Content string
	Delay   time.Duration
}

Frame holds one rendered animation frame.

func RenderGIF

func RenderGIF(path string, opts Options) ([]Frame, error)

RenderGIF decodes an animated GIF, composites frames, and renders each to an ANSI art string. Returns up to 100 frames. Single-frame GIFs return a 1-element slice.

type Options

type Options struct {
	// Size
	SizeMode  SizeMode
	Width     int
	Height    int
	CharRatio float64 // terminal character width-to-height ratio

	// Characters
	CharacterMode  CharacterMode
	AsciiCharSet   AsciiCharSet   // used when CharacterMode == Ascii
	UnicodeCharSet UnicodeCharSet // used when CharacterMode == Unicode
	CustomChars    []rune         // used when CharacterMode == Custom
	ColorBg        bool           // true = use foreground and background; false = foreground only
	SelectionMode  SelectionMode  // used when CharacterMode == Custom

	// Color
	TrueColor      bool          // true = 24-bit RGB; false = use Palette
	Palette        color.Palette // used when TrueColor == false
	AdaptToPalette bool          // remap image color range to palette color range before matching

	// Adjustments
	Brightness int // -100..100
	Contrast   int // -100..100

	// Advanced
	Sampling           SamplingFunction
	Dithering          bool
	Serpentine         bool
	DitherMode         DitherMode
	DitherMatrix       DitherMatrix       // used when DitherMode == DitherModeMatrix
	BayerSize          uint               // used when DitherMode == DitherModeBayer (must be power of 2)
	DitherStrength     float32            // strength for Bayer/ClusteredDot (default 1.0)
	ClusteredDotMatrix ClusteredDotMatrix // used when DitherMode == DitherModeClusteredDot

	// Alpha
	OutputAlpha bool
	TrimAlpha   bool
}

Options configures how an image is rendered to ANSI art.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns sensible defaults matching the ansizalizer TUI defaults.

type SamplingFunction

type SamplingFunction int

SamplingFunction selects the image resize interpolation method.

const (
	NearestNeighbor SamplingFunction = iota
	Bicubic
	Bilinear
	Lanczos2
	Lanczos3
	MitchellNetravali
)

type SelectionMode

type SelectionMode int

SelectionMode controls how custom characters are assigned to pixels.

const (
	DarkToLight SelectionMode = iota // Map by brightness (darkest char first)
	Repeat                           // Cycle through chars sequentially
	Random                           // Pick chars at random
)

type SizeMode

type SizeMode int

SizeMode controls how the image dimensions are calculated.

const (
	Fit     SizeMode = iota // Fit within Width x Height preserving aspect ratio
	Stretch                 // Stretch to exactly Width x Height
	Fill                    // Fill Width x Height preserving aspect ratio (may crop)
)

type UnicodeCharSet

type UnicodeCharSet int

UnicodeCharSet selects which Unicode block characters to use.

const (
	UnicodeFull       UnicodeCharSet = iota // Full block █
	UnicodeHalf                             // Half blocks ▀▄
	UnicodeQuarter                          // Quarter blocks ▞▟
	UnicodeShadeLight                       // Light shade ░
	UnicodeShadeMed                         // Medium shade ▒
	UnicodeShadeHeavy                       // Heavy shade ▓
)