ascii

README

ascii-creator

This Go module converts an image to ascii art.

This module was initially used as a personal learning space, to explore the concepts and capabilities of Golang.

It continues to evolve, and must be considered work-in-progress.

Example use

To use the module, create a simple application which loads an image from file. Create a new Generator using a builder, and provide the character set you would like for the conversion and the loaded image. Finally call Generate to generate the ascii output. Here is a small example:

package main

import (
	"fmt"
	creator "github.com/faakern/ascii-creator"
	"image"
	"image/jpeg"
	"image/png"
	"os"
	"strconv"
	"strings"
)

func main() {
	// Parse arguments and place them in a map for later look-up
	var argMap map[string]string
	argMap = make(map[string]string)
	argMap["-g"] = "1" // Place defaults in the map, if you like

	args := os.Args[1:]
	for i := 0; i < len(args); i++ {
		key := args[i][:2]
		value := args[i][2:]
		argMap[key] = value
	}

	if argMap["-i"] == "" {
		fmt.Println("No input file specified. Please provide the following argument '-i<filename>'")
		os.Exit(1)
	}

	// Register supported image types
	image.RegisterFormat("png", "png", png.Decode, png.DecodeConfig)
	image.RegisterFormat("jpg", "jpg", jpeg.Decode, jpeg.DecodeConfig)
	fmt.Printf("Converting image '%s'...\n", argMap["-i"])

	// Open the input file and decode the image
	file, err := os.Open(argMap["-i"])
	img, _, err := image.Decode(file)

	if err != nil {
		fmt.Printf("Could not find or open file: %s\n", err)
		os.Exit(1)
	}

	// Create a builder for ascii conversion/creation
	builder := creator.NewBuilder()

	// Provide a list of characters - these should be arranged from 'darker' to 'lighter' values,
	// an input image, and build a generator to be used as basis for the conversion.
	gamma, err := strconv.ParseFloat(argMap["-g"], 32)
	if err != nil {
		fmt.Println("Gamma correction value is invalid")
		os.Exit(1)
	}

	generator := builder.WithCharSet(creator.CharSet{
		Characters: []byte{' ', '.', ',', ':', ';', '+', '*', '?', '%', '&', '#', '@'},
	}).WithGammaCorrection(float32(gamma)).WithInput().Image(img).Build()

	// Do the actual conversion/ascii generation
	var out creator.Result
	err = generator.Generate(&out)
	if err != nil {
		fmt.Printf("Error converting image: %s\n", err)
		os.Exit(1)
	}

	// Write the result to an output file
	file, err = os.Create(fmt.Sprintf("%s.txt", strings.Split(argMap["-i"], ".")[0]))
	if err != nil {
		fmt.Println("Could not create output file")
		os.Exit(1)
	}

	size, err := file.Write(out.Ascii)
	if err != nil {
		fmt.Println("Could not write output to file")
		os.Exit(1)
	}

	fmt.Printf("Wrote %d bytes to %s\n", size, file.Name())

	err = file.Close()
	if err != nil {
		os.Exit(1)
	}
}

The example application parses a command line argument for the file name, and will provide the converted ascii art file with the same name, only with '.txt' ending. The command line parsing is rudimentary, but serves its purpose for this use. You may find modules handling command line parsing better - such as the flag module.

For convenience's sake, the input file should not be too large. This will create an output which may be difficult to portray, as font size plays a role in its presentation.

Output

The following image displays the output of the conversion, compared to the input:

Gamma Correction

The ascii generation may produce an output which doesn't satisfy your aesthetic preferences. Maybe it contains too much noise or has too dark values.

To allow for a cleaner output, the ascii generator can be specified with a gamma correction value:

	generator := builder.WithCharSet(creator.CharSet{
		Characters: []byte{' ', '.', ',', ':', ';', '+', '*', '?', '%', '&', '#', '@'},
	}).WithGammaCorrection(1.5).WithInput().Image(img).Build()

Documentation

Index

• type Builder
  • func NewBuilder() *Builder
  • func (b *Builder) Build() *Generator
  • func (b *Builder) WithAlphaThreshold(threshold int) *Builder
  • func (b *Builder) WithAlphaValue(value byte) *Builder
  • func (b *Builder) WithCharSet(charset CharSet) *Builder
  • func (b *Builder) WithGammaCorrection(correction float32) *Builder
  • func (b *Builder) WithInput() *InputBuilder
• type CharSet
• type Generator
  • func (gen *Generator) Generate(result *Result) error
• type InputBuilder
  • func (b *InputBuilder) Image(image image.Image) *InputBuilder
• type Result

Types

type Builder

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

func NewBuilder

func NewBuilder() *Builder

NewBuilder will create a builder style construct, which provides you with a default Generator. The builder 'object' provides convenience functions for specifying generator properties, e.g. what character set to use for the ascii generation, and what input image to use.

func (*Builder) Build

func (b *Builder) Build() *Generator

func (*Builder) WithAlphaThreshold

func (b *Builder) WithAlphaThreshold(threshold int) *Builder

func (*Builder) WithAlphaValue

func (b *Builder) WithAlphaValue(value byte) *Builder

func (*Builder) WithCharSet

func (b *Builder) WithCharSet(charset CharSet) *Builder

func (*Builder) WithGammaCorrection

func (b *Builder) WithGammaCorrection(correction float32) *Builder

func (*Builder) WithInput

func (b *Builder) WithInput() *InputBuilder

type CharSet

type CharSet struct {
	Characters []byte
}

type Generator

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

Generator provides parameters for generating ascii output. The alphaThreshold specifies what threshold should be used to return a replacement alphaValue. Charset specifies what characters to be used for the ascii conversion. These should be ordered from 'darker' to 'lighter' values - ex. [' ', '.', '*', '@'], for a 'natural' look, but you can experiment with this range, for various artistic expressions!! The more characters used, the more nuances the ascii image will gain. img holds the image to be used an input for the ascii generation.

func (*Generator) Generate

func (gen *Generator) Generate(result *Result) error

Generate returns an ascii (byte array) representation, based on a parameterized generator consisting of an image and a charset.

type InputBuilder

type InputBuilder struct {
	Builder
}

func (*InputBuilder) Image

func (b *InputBuilder) Image(image image.Image) *InputBuilder

type Result

type Result struct {
	Ascii []byte
}