imretro

README

Imretro

This is the Go implementation of the imretro image format.

Import

import "github.com/imretro/go" // Imports the "imretro" package

Documentation

Overview

Package imretro supports encoding and decode retro-style images in the imretro format.

Example (Decode)

var reader io.Reader = bytes.NewBuffer(ImgBytes)
img, format, err := image.Decode(reader)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("Format: %s\n", format)

bounds := img.Bounds()

for y := bounds.Min.Y; y < bounds.Max.Y; y++ {
	for x := bounds.Min.X; x < bounds.Max.X; x++ {
		r, g, b, _ := img.At(x, y).RGBA()
		fmt.Printf("r = %04X, g = %04X, b = %04X\n", r, g, b)
	}
}

Output:

Format: imretro
r = FFFF, g = FFFF, b = FFFF
r = 0000, g = 0000, b = 0000
r = 0000, g = 0000, b = 0000
r = FFFF, g = FFFF, b = FFFF

Example (Decode_config)

var reader io.Reader = bytes.NewBuffer(ImgBytes)
config, format, err := image.DecodeConfig(reader)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Format: %s\n", format)
fmt.Printf("width: %d\nheight: %d\n", config.Width, config.Height)

Output:

Format: imretro
width: 2
height: 2

Index

• Constants
• Variables
• func DecodeConfig(r io.Reader, customModels CustomModel) (image.Config, error)
• func Encode(w io.Writer, m image.Image, pixelMode PixelMode) error
• func IsBitCountSupported(count PixelMode) bool
• type ColorModel
  • func NewOneBitColorModel(off color.Color, on color.Color) ColorModel
  • func NewTwoBitColorModel(off, light, strong, full color.Color) ColorModel
  • func (model ColorModel) BitsPerPixel() int
  • func (model ColorModel) ColorModel(PixelMode) (self color.Model, ok bool)
  • func (model ColorModel) Convert(c color.Color) color.Color
  • func (model ColorModel) Index(c color.Color) uint8
  • func (model ColorModel) PixelMode() PixelMode
• type CustomModel
• type DecodeError
  • func (e DecodeError) Error() string
• type DimensionsTooLargeError
  • func (e DimensionsTooLargeError) Error() string
• type Image
  • func Decode(r io.Reader, customModels CustomModel) (Image, error)
• type MissingModelError
  • func (mode MissingModelError) Error() string
• type ModeFlag
• type ModelMap
  • func (m ModelMap) ColorModel(mode PixelMode) (model color.Model, ok bool)
• type PixelMode
• type UnsupportedBitModeError
  • func (e UnsupportedBitModeError) Error() string

Examples

• Package (Decode)
• Package (Decode_config)
• CustomModel (Model_map)
• CustomModel (Single_model)

Constants

const EightBitColors byte = 1 << colorAccuracyIndex

EightBitColors sets the mode byte to signify that each color channel should use a byte, instead of 2 bits for each color channel.

const ImretroSignature = "IMRETRO"

ImretroSignature is the "magic string" used for identifying an imretro file.

const MaximumDimension int = 0xFFF

MaximumDimension is the maximum size of an image's boundary in the imretro format.

const WithPalette byte = 1 << paletteIndex

WithPalette can be used with a union with the bit count when setting the header.

Variables

var (
	Default1BitColorModel = NewOneBitColorModel(black, white)
	Default2BitColorModel = NewTwoBitColorModel(black, darkGray, lightGray, white)
	Default8BitColorModel = make(ColorModel, 256)
)

Default color models/palettes adhering to the defaults defined in the format documentation.

var DefaultModelMap = ModelMap{
	OneBit:   Default1BitColorModel,
	TwoBit:   Default2BitColorModel,
	EightBit: Default8BitColorModel,
}

DefaultModelMap maps bit modes to the default color models.

var ErrUnknownModel = errors.New("Color model not recognized")

ErrUnknownModel is raised when an unknown color model is interpreted.

Functions

func DecodeConfig

func DecodeConfig(r io.Reader, customModels CustomModel) (image.Config, error)

DecodeConfig returns the color model and dimensions of an imretro image without decoding the entire image.

Custom color models can be used instead of the default model.

func Encode

func Encode(w io.Writer, m image.Image, pixelMode PixelMode) error

Encode writes the image m to w in imretro format.

func IsBitCountSupported

func IsBitCountSupported(count PixelMode) bool

IsBitCountSupported checks if the bit count is supported by the imretro format.

Types

type ColorModel

type ColorModel color.Palette

ColorModel is color model for imretro images.

func NewOneBitColorModel

func NewOneBitColorModel(off color.Color, on color.Color) ColorModel

NewOneBitColorModel creates a new color model for 1-bit-pixel images.

func NewTwoBitColorModel

func NewTwoBitColorModel(off, light, strong, full color.Color) ColorModel

NewTwoBitColorModel creates a new color model for 2-bit-pixel images.

func (ColorModel) BitsPerPixel

func (model ColorModel) BitsPerPixel() int

BitsPerPixel returns the number of bits used for each pixel.

func (ColorModel) ColorModel

func (model ColorModel) ColorModel(PixelMode) (self color.Model, ok bool)

ColorModel will always return itself and ok.

func (ColorModel) Convert

func (model ColorModel) Convert(c color.Color) color.Color

Convert maps a color to the best color defined in the model. This is not necessarily the closest color. For example, RGBA 255, 255, 255, 0 would always map to the "off" color of a 1-bit model, even if the "on" color is RGBA 255, 255, 255, 0. This is because a transparent color is considered to be off.

func (ColorModel) Index

func (model ColorModel) Index(c color.Color) uint8

Index returns the index of the palette color.

func (ColorModel) PixelMode

func (model ColorModel) PixelMode() PixelMode

PixelMode gets the bits-per-pixel according to the color model.

type CustomModel

type CustomModel interface {
	// ColorModel gets a color.Model from a PixelMode. Ok should be true if the
	// color.Model could be returned, and false if it couldn't.
	ColorModel(PixelMode) (model color.Model, ok bool)
}

CustomModel is a type that converts a pixel mode to a color.Model. It should be used to override default palettes/color models.

Example (Model_map)

Custom models can be used when decoding to define your own palette. In this example, instead of using the default black & white 1-bit-pixel palette, black and green palettes are passed.

black := color.Gray{0}
green := color.RGBA{0, 0xFF, 0, 0xFF}
custom := imretro.ModelMap{
	imretro.OneBit: imretro.ColorModel{black, green},
	imretro.TwoBit: imretro.ColorModel{
		black, color.RGBA{0, 0x55, 0, 0}, color.RGBA{0, 0xAA, 0, 0}, black,
	},
	imretro.EightBit: make(imretro.ColorModel, 256),
}
var reader io.Reader = bytes.NewBuffer(ImgBytes)
img, err := imretro.Decode(reader, custom)
if err != nil {
	log.Fatal(err)
}

bounds := img.Bounds()

for y := bounds.Min.Y; y < bounds.Max.Y; y++ {
	for x := bounds.Min.X; x < bounds.Max.X; x++ {
		r, g, b, _ := img.At(x, y).RGBA()
		fmt.Printf("r = %04X, g = %04X, b = %04X\n", r, g, b)
	}
}

Output:

r = 0000, g = FFFF, b = 0000
r = 0000, g = 0000, b = 0000
r = 0000, g = 0000, b = 0000
r = 0000, g = FFFF, b = 0000

Example (Single_model)

If the pixel mode is predictable, a single ColorModel can be passed. In this example, it is assumed that the image will always be in 1-bit-pixel mode (two colors).

black := color.Gray{0}
green := color.RGBA{0, 0xFF, 0, 0xFF}
custom := imretro.ColorModel{black, green}
var reader io.Reader = bytes.NewBuffer(ImgBytes)
img, err := imretro.Decode(reader, custom)
if err != nil {
	log.Fatal(err)
}

bounds := img.Bounds()

for y := bounds.Min.Y; y < bounds.Max.Y; y++ {
	for x := bounds.Min.X; x < bounds.Max.X; x++ {
		r, g, b, _ := img.At(x, y).RGBA()
		fmt.Printf("r = %04X, g = %04X, b = %04X\n", r, g, b)
	}
}

Output:

r = 0000, g = FFFF, b = 0000
r = 0000, g = 0000, b = 0000
r = 0000, g = 0000, b = 0000
r = 0000, g = FFFF, b = 0000

type DecodeError

type DecodeError string

DecodeError is an error signifying that something unexpected happened when decoding the imretro reader.

func (DecodeError) Error

func (e DecodeError) Error() string

Error reports that the format could not be decoded as imretro.

type DimensionsTooLargeError

type DimensionsTooLargeError int

DimensionsTooLargeError should be returned when an encoded image would have boundaries that are not valid in the encoding.

func (DimensionsTooLargeError) Error

func (e DimensionsTooLargeError) Error() string

Error makes a string representation of the too-large error.

type Image

type Image interface {
	image.PalettedImage
	// Palette gets the palette of the image.
	Palette() color.Palette
	// PixelMode returns the pixel mode of the image.
	PixelMode() PixelMode
	// BitsPerPixel returns the number of bits used for each pixel.
	BitsPerPixel() int
}

Image is an image decoded from the imretro format.

func Decode

func Decode(r io.Reader, customModels CustomModel) (Image, error)

Decode decodes an image in the imretro format.

Custom color models can be used instead of the default color models. For simplicity's sake, a single ColorModel can be passed as the CustomModel. If multiple PixelMode values are expected, it is recommended to use a ModelMap for the CustomModel. See the documentation for the model types for more details. If the decoded image contains an in-image palette, the model will be generated from that instead of the custom value passed or the default models.

type MissingModelError

type MissingModelError PixelMode

MissingModelError is raised when there is no model for the given pixel bit mode.

func (MissingModelError) Error

func (mode MissingModelError) Error() string

Error reports the pixel mode lacking the color model.

type ModeFlag

type ModeFlag = byte

ModeFlag is the type for enabling a feature by setting a flag in the mode byte.

const (
	Grayscale ModeFlag = iota << colorChannelIndex
	RGB
	RGBA
)

Feature flags for setting the number of color channels each color will have in the palette. Ignored if the WithPalette flag is not set.

type ModelMap

type ModelMap map[PixelMode]color.Model

ModelMap maps bit modes to color models.

func (ModelMap) ColorModel

func (m ModelMap) ColorModel(mode PixelMode) (model color.Model, ok bool)

ColorModel gets the mapped color model.

type PixelMode

type PixelMode = ModeFlag

PixelMode is the type for managing the number of bits per pixel.

const (
	OneBit PixelMode = iota << pixelBitsIndex
	TwoBit
	EightBit
)

Mode flags for picking the number of bits each pixel will have.

type UnsupportedBitModeError

type UnsupportedBitModeError byte

UnsupportedBitModeError should be returned when an unexpected number of bits is received.

func (UnsupportedBitModeError) Error

func (e UnsupportedBitModeError) Error() string

Error converts to an error string.