ascii

Documentation

Index

• func ApplyFilter(img image.Image, filter FilterType, intensity float64) image.Image
• func Convert(img image.Image, opts ConvertOptions) [][]AsciiChar
• func FormatChar(ch rune, r, g, b uint8, mode ColorMode) string
• func FormatChar16(ch rune, r, g, b uint8) string
• func FormatChar256(ch rune, r, g, b uint8) string
• func FormatCharNone(ch rune) string
• func FormatCharTrue(ch rune, r, g, b uint8) string
• func GetPreset(name string) string
• func IsAnimatedGIF(path string) (bool, error)
• func ListPresets() []string
• func LoadFromFile(path string) (image.Image, error)
• func LoadFromStdin() (image.Image, error)
• func LoadFromURL(url string) (image.Image, error)
• func PlayAnimatedGIF(path string, opts ConvertOptions) error
• func PrintToTerminal(art [][]AsciiChar, mode ...ColorMode)
• func RGBTo16(r, g, b uint8) uint8
• func RGBTo256(r, g, b uint8) uint8
• func SaveToANSI(art [][]AsciiChar, path string, mode ...ColorMode) error
• func SaveToHTML(art [][]AsciiChar, path string) error
• func SaveToSVG(art [][]AsciiChar, path string, fontSize float64) error
• func SaveToText(art [][]AsciiChar, path string) error
• type AsciiChar
• type ColorMode
• type ConvertOptions
• type FilterType

Functions

func ApplyFilter

func ApplyFilter(img image.Image, filter FilterType, intensity float64) image.Image

ApplyFilter applies the specified filter to the image with the given intensity. Returns a new image with the filter applied.

func Convert

func Convert(img image.Image, opts ConvertOptions) [][]AsciiChar

Convert transforms an image into a 2D grid of AsciiChar. Each pixel is mapped to a character based on its luminance, and retains its RGB color for true-color terminal output.

func FormatChar

func FormatChar(ch rune, r, g, b uint8, mode ColorMode) string

FormatChar formats a character using the specified color mode.

func FormatChar16

func FormatChar16(ch rune, r, g, b uint8) string

FormatChar16 formats a character with 16-color ANSI escape.

func FormatChar256

func FormatChar256(ch rune, r, g, b uint8) string

FormatChar256 formats a character with 256-color ANSI escape.

func FormatCharNone

func FormatCharNone(ch rune) string

FormatCharNone formats a character with no color escape.

func FormatCharTrue

func FormatCharTrue(ch rune, r, g, b uint8) string

FormatCharTrue formats a character with 24-bit true color ANSI escape.

func GetPreset

func GetPreset(name string) string

GetPreset returns the character set for a given preset name. Falls back to "simple" if the name is unknown.

func IsAnimatedGIF

func IsAnimatedGIF(path string) (bool, error)

IsAnimatedGIF checks whether a GIF file contains multiple frames.

func ListPresets

func ListPresets() []string

ListPresets returns all available preset names.

func LoadFromFile

func LoadFromFile(path string) (image.Image, error)

LoadFromFile loads an image from a local file path. Supports JPEG, PNG, GIF (first frame), BMP, and WebP.

func LoadFromStdin

func LoadFromStdin() (image.Image, error)

LoadFromStdin reads an image from standard input.

func LoadFromURL

func LoadFromURL(url string) (image.Image, error)

LoadFromURL downloads an image from an HTTP/HTTPS URL and decodes it. Uses a 30-second timeout and limits response body to 50MB.

func PlayAnimatedGIF

func PlayAnimatedGIF(path string, opts ConvertOptions) error

PlayAnimatedGIF decodes all frames of a GIF, converts each to ASCII art, and plays them in the terminal with the original frame delays. It loops indefinitely until interrupted with Ctrl+C.

func PrintToTerminal

func PrintToTerminal(art [][]AsciiChar, mode ...ColorMode)

PrintToTerminal renders the ASCII art to stdout with ANSI color. The color mode determines the escape sequence format used.

func RGBTo16

func RGBTo16(r, g, b uint8) uint8

RGBTo16 maps an RGB color to the nearest 16-color ANSI index using Euclidean distance in RGB space.

func RGBTo256

func RGBTo256(r, g, b uint8) uint8

RGBTo256 maps an RGB color to the nearest 256-color palette index. The 256-color palette:

0-7:     standard colors
8-15:    bright colors
16-231:  6x6x6 color cube
232-255: grayscale ramp

func SaveToANSI

func SaveToANSI(art [][]AsciiChar, path string, mode ...ColorMode) error

SaveToANSI writes the ASCII art with ANSI escape codes to a file. The resulting file can be displayed with `cat` in a true-color terminal.

func SaveToHTML

func SaveToHTML(art [][]AsciiChar, path string) error

SaveToHTML writes the ASCII art as an HTML file with inline color styles. Each character is wrapped in a <span> with its RGB color.

func SaveToSVG

func SaveToSVG(art [][]AsciiChar, path string, fontSize float64) error

SaveToSVG writes the ASCII art as an SVG file with colored monospace text. Each character is rendered as a <text> element with its original RGB color.

func SaveToText

func SaveToText(art [][]AsciiChar, path string) error

SaveToText writes the ASCII art as plain text (no colors) to a file.

Types

type AsciiChar

type AsciiChar struct {
	Char    rune
	R, G, B uint8
}

AsciiChar represents a single character in the ASCII art output, holding both the character to display and its original pixel color.

type ColorMode

type ColorMode string

ColorMode defines the color output mode.

const (
	ColorTrue ColorMode = "true" // 24-bit true color
	Color256  ColorMode = "256"  // 256-color ANSI
	Color16   ColorMode = "16"   // 16-color ANSI
	ColorNone ColorMode = "none" // No color (characters only)
)

type ConvertOptions

type ConvertOptions struct {
	Width           int
	Charset         string
	Grayscale       bool
	Brightness      float64
	Contrast        float64
	Dither          bool
	Filter          FilterType
	FilterIntensity float64
	Color           ColorMode
}

ConvertOptions controls how an image is converted to ASCII art.

type FilterType

type FilterType string

FilterType defines the available image filter types.

const (
	FilterNone      FilterType = "none"
	FilterEdge      FilterType = "edge"
	FilterNegative  FilterType = "negative"
	FilterSepia     FilterType = "sepia"
	FilterBlur      FilterType = "blur"
	FilterSharpen   FilterType = "sharpen"
	FilterPixelate  FilterType = "pixelate"
	FilterGrayscale FilterType = "grayscale"
)