binimg

README

binimg - Binary images in Go

binimg package proposes an in-memory binary image format, that is an image that has only two possible values for each pixel. In this package, we refer to those 2 colors as binimg.On and binimg.Off, that respectively convert (via binimg.Model) to the standard Go colors color.White and color.Black. binimg.Model implements the color.Model interface.

Such images are also referred to as bi-level, or two-level.

binimg.Binary implements the standard Go image.Image and draw.Image.

A pixel could be stored as a single bit, but as the main goal of this package is fast manipulation of binary images, binimg.Bit, the underlying pixel data type manipulated by binimg.Binary image, is 1 byte wide.

Binary are instantiated by the following functions:

func New(r image.Rectangle, p Palette) *Binary
func NewFromImage(src image.Image, p Palette) *Binary

---

TODO: REMOVE (there is no more palette, but show an exemple of conversion from a color image to a binary one, with standard color model and maybe how to use a custom color model by subclassing/composition and providing a new color model... if that seems useful) remove all references to binimg.Black and binimg.White

BlackAndWhite predefined Palette

BlackAndWhiteHighThreshold predefined Palette

Custom Palette

---

Usage

• Create and modify new binary image

package main

import (
	"image"
	"image/color"

	"github.com/arl/imgtools/binimg"
)

func main() {
	// create a new image (prefilled with OffColor: black)
	bin := binimg.New(image.Rect(0, 0, 128, 128), binimg.BlackAndWhite)

	// set a pixel to OnColor: White
	bin.SetBit(10, 0, binimg.On)

	// set a pixel, converting original color with BlackAndWhite Palette
	bin.Set(10, 0, color.RGBA{127, 23, 98, 255})

	// set rectangular region to White
	bin.SetRect(image.Rect(32, 32, 64, 64), binimg.On)
}

• Convert an existing image.Image into black and white binary image

package main

import "github.com/arl/binimg"

func main() {
	// load image ("color-gopher.png")
	// ...
	bin := binimg.NewFromImage(img)

	// save image ("black&white-gopher.png")
	// ...
}

• Use a custom binimg.Palette (i.e color.Model)

import (
	"image"
	"image/color"

	"github.com/arl/imgtools/binimg"
)

func main() {
	var img image.Image

	// ... decode image

	// create
	palette := binimg.Palette{
		OnColor:   color.RGBA{255, 0, 0, 255},
		OffColor:  color.RGBA{0, 0, 255, 255},
		Threshold: 97,
	}
	bin := binimg.NewFromImage(img, palette)

	// ... encode image
}

Documentation

Overview

Package binimg proposes an in-memory binary image format, implementing the image.Image interface, alongside a set of efficient tools to scan rectangular regions of such images. A binary image has only two possible colors for each pixel, generally Black and White, though any two colors can be used.

Though the information represented by each pixel could be stored as a single bit, and thus has a reduced memory footprint, choice has been made to represent Bit pixels as byte values, that can either be 0 (Black or Off) or 255 (White or On), mostly for simplicity reasons.

binimg.Image images are created either by calling functions such as New and NewFromImage.

Index

• Variables
• type Bit
  • func (c Bit) Other() Bit
  • func (c Bit) RGBA() (r, g, b, a uint32)
• type Image
  • func New(r image.Rectangle) *Image
  • func NewFromImage(src image.Image) *Image
  • func (b *Image) At(x, y int) color.Color
  • func (b *Image) BitAt(x, y int) Bit
  • func (b *Image) Bounds() image.Rectangle
  • func (b *Image) ColorModel() color.Model
  • func (b *Image) Opaque() bool
  • func (b *Image) PixOffset(x, y int) int
  • func (b *Image) Set(x, y int, c color.Color)
  • func (b *Image) SetBit(x, y int, c Bit)
  • func (b *Image) SetRect(r image.Rectangle, c Bit)
  • func (b *Image) SubImage(r image.Rectangle) image.Image

Variables

var (
	Black = Bit{0}
	White = Bit{255}
)

Black and White are the only colors that a Binary image pixel can have.

var (
	Off = Black
	On  = White
)

Alias colors for Black and White

var Model = color.ModelFunc(model)

Model is the color model for binary images.

Types

type Bit

type Bit struct{ V byte }

Bit represents a Black or White only binary color.

func (Bit) Other

func (c Bit) Other() Bit

Other returns a Bit with the other value.

func (Bit) RGBA

func (c Bit) RGBA() (r, g, b, a uint32)

RGBA returns the red, green, blue and alpha values for a Bit color.

alpha is always 0xffff (fully opaque) and r, g, b are all 0 or all 0xffff.

type Image

type Image struct {
	// Pix holds the image's pixels, as 0 or 1 uint8 values. The pixel at
	// (x, y) starts at Pix[(y-Rect.Min.Y)*Stride + (x-Rect.Min.X)*1].
	Pix []uint8
	// Stride is the Pix stride (in bytes) between vertically adjacent pixels.
	Stride int
	// Rect is the image's bounds.
	Rect image.Rectangle
}

Image is an in-memory image whose At method returns Bit values.

func New

func New(r image.Rectangle) *Image

New returns a new binary image with the given bounds.

func NewFromImage

func NewFromImage(src image.Image) *Image

NewFromImage returns a new binary image that is the conversion of src image.

func (*Image) At

func (b *Image) At(x, y int) color.Color

At returns the color of the pixel at (x, y). At(Bounds().Min.X, Bounds().Min.Y) returns the upper-left pixel of the grid. At(Bounds().Max.X-1, Bounds().Max.Y-1) returns the lower-right one.

func (*Image) BitAt

func (b *Image) BitAt(x, y int) Bit

BitAt returns the Bit color of the pixel at (x, y). BitAt(Bounds().Min.X, Bounds().Min.Y) returns the upper-left pixel of the grid. BitAt(Bounds().Max.X-1, Bounds().Max.Y-1) returns the lower-right one.

func (*Image) Bounds

func (b *Image) Bounds() image.Rectangle

Bounds returns the domain for which At can return non-zero color. The bounds do not necessarily contain the point (0, 0).

func (*Image) ColorModel

func (b *Image) ColorModel() color.Model

ColorModel returns the image.Image's color model.

func (*Image) Opaque

func (b *Image) Opaque() bool

Opaque scans the entire image and reports whether it is fully opaque.

func (*Image) PixOffset

func (b *Image) PixOffset(x, y int) int

PixOffset returns the index of the first element of Pix that corresponds to the pixel at (x, y).

func (*Image) Set

func (b *Image) Set(x, y int, c color.Color)

Set sets the color of the pixel at (x, y).

c is converted to Bit using the image color model.

func (*Image) SetBit

func (b *Image) SetBit(x, y int, c Bit)

SetBit sets the Bit of the pixel at (x, y).

func (*Image) SetRect

func (b *Image) SetRect(r image.Rectangle, c Bit)

SetRect sets all the pixels in the rectangle defined by given rectangle.

func (*Image) SubImage

func (b *Image) SubImage(r image.Rectangle) image.Image

SubImage returns an image representing the portion of the image p visible through r. The returned value shares pixels with the original image.