accumimage

README

accumimage and accumcolor

Description

accumimage and accumcolor are packages for the Go programming language that provide the ability to accumulate and average colors. accumcolor.AccumNRGBA is the accumulating analogue of the Go standard library's color.NRGBA (a single pixel of non-alpha-premultiplied red, green, blue, and alpha channels), and accumimage.AccumNRGBA is the accumulating analogue of the Go standard library's image.NRGBA (a 2-D array of NRGBA pixels).

In addition to three color channels and an alpha channel, an accumcolor.AccumNRGBA contains a tally of the number of colors that have been added together. The Add method adds another color to the existing one, both weighted by their tally. The NRGBA method divides each channel by the tally to produce an ordinary color.NRGBA.

accumimage and accumcolor can be useful for blending multiple overlapping images, for mapping a large number of pixels to a smaller number (e.g., when scaling an image), and for distinguishing pixels in an image that are truly empty (e.g., unvisited in an algorithm that visits all pixels) from pixels that have a color, even one that is fully transparent.

Usage

Assuming you are using the Go module system, simply import accumimage and accumimage/accumcolor:

import (
        "github.com/spakin/accumimage"
        "github.com/spakin/accumimage/accumcolor"
)

Then run go mod tidy to download and install the package files.

Documentation

See the pkg.go.dev documentation for accumimage and accumcolor.

Author

Scott Pakin, scott-accum@pakin.org

Documentation

Overview

Package accumimage provides support for images whose colors that can be accumulated and averaged. It is based on the color types defined in accumimage/accumcolor. The core data type that accumimage defines is an AccumNRGBA, which implements the image.Image interface as well as the standard set of methods provided by the image package's image types. In addition, each AccumNRGBA.Set* method has a corresponding AccumNRGBA.Add* method, which adds color to a pixel rather than replacing the pixel's color with a given color.

Example

Scale down an arbitrary image (img) to given dimensions (newBnds), averaging colors that map to the same target pixel. The result is smoother than if newImg.Set were used instead of newImg.Add.

package main

import (
	"image"
	"image/png"
	"log"
	"os"

	"github.com/spakin/accumimage"
)

// readImage reads an image from a named file.
func readImage(fn string) (image.Image, error) {
	r, err := os.Open(fn)
	if err != nil {
		return nil, err
	}
	img, _, err := image.Decode(r)
	if err != nil {
		return nil, err
	}
	return img, nil
}

// writeImage writes an image to a named file in PNG format.
func writeImage(fn string, img image.Image) error {
	w, err := os.Create(fn)
	if err != nil {
		return err
	}
	err = png.Encode(w, img)
	return err
}

func main() {
	// Read an image from a file.
	if len(os.Args) != 2 {
		return
	}
	img, err := readImage(os.Args[1])
	if err != nil {
		log.Fatal(err)
	}

	// Choose (arbitrarily) to scale to 1/3 of the size in each of x and y.
	bnds := img.Bounds()
	wd, ht := bnds.Dx(), bnds.Dy()
	newBnds := image.Rect(0, 0, wd/3, ht/3)

	// Create an AccumNRGBA image.
	newImg := accumimage.NewAccumNRGBA(newBnds)
	nwd, nht := newBnds.Dx(), newBnds.Dy()

	// Copy the image pixel-by-pixel, from (x, y) in the input image to
	// (nx, ny) in the output image.
	for y := bnds.Min.Y; y < bnds.Max.Y; y++ {
		ny := (nht*(y-bnds.Min.Y))/ht + newBnds.Min.Y
		for x := bnds.Min.X; x < bnds.Max.X; x++ {
			nx := (nwd*(x-bnds.Min.X))/wd + newBnds.Min.X
			c := img.At(x, y)
			newImg.Add(nx, ny, c) // Accumulate multiple colors into a single pixel.
		}
	}

	// Write the downscaled image to a file.
	err = writeImage("image.png", newImg)
	if err != nil {
		log.Fatal(err)
	}
}

Index

• type AccumNRGBA
  • func NewAccumNRGBA(r image.Rectangle) *AccumNRGBA
  • func (p *AccumNRGBA) AccumNRGBAAt(x, y int) accumcolor.AccumNRGBA
  • func (p *AccumNRGBA) Add(x, y int, c color.Color)
  • func (p *AccumNRGBA) AddAccumNRGBA(x, y int, c accumcolor.AccumNRGBA)
  • func (p *AccumNRGBA) AddRGBA64(x, y int, c color.RGBA64)
  • func (p *AccumNRGBA) At(x, y int) color.Color
  • func (p *AccumNRGBA) Bounds() image.Rectangle
  • func (p *AccumNRGBA) ColorModel() color.Model
  • func (p *AccumNRGBA) NRGBAAt(x, y int) color.NRGBA
  • func (p *AccumNRGBA) Opaque() bool
  • func (p *AccumNRGBA) PixOffset(x, y int) int
  • func (p *AccumNRGBA) RGBA64At(x, y int) color.RGBA64
  • func (p *AccumNRGBA) Set(x, y int, c color.Color)
  • func (p *AccumNRGBA) SetAccumNRGBA(x, y int, c accumcolor.AccumNRGBA)
  • func (p *AccumNRGBA) SetRGBA64(x, y int, c color.RGBA64)
  • func (p *AccumNRGBA) SubImage(r image.Rectangle) image.Image

Examples

• Package
• AccumNRGBA.Add

Types

type AccumNRGBA

type AccumNRGBA struct {
	// Pix holds the image's pixels, in R, G, B, A, Tally order. The pixel
	// at (x, y) starts at Pix[(y-Rect.Min.Y)*Stride + (x-Rect.Min.X)*5].
	Pix []uint64
	// Stride is the Pix stride (in uint64s) between vertically adjacent
	// pixels.
	Stride int
	// Rect is the image's bounds.
	Rect image.Rectangle
}

An AccumNRGBA is an in-memory image whose At method returns accumcolor.NRGBA values.

func NewAccumNRGBA

func NewAccumNRGBA(r image.Rectangle) *AccumNRGBA

NewAccumNRGBA returns a new AccumNRGBA image with the given bounds.

func (*AccumNRGBA) AccumNRGBAAt

func (p *AccumNRGBA) AccumNRGBAAt(x, y int) accumcolor.AccumNRGBA

AccumNRGBAAt returns the color of the pixel at (x, y) as an accumcolor.AccumNRGBA.

func (*AccumNRGBA) Add

func (p *AccumNRGBA) Add(x, y int, c color.Color)

Add accumulates a given color of any type to the pixel at (x, y).

Example

Blend two images to produce a third image.

package main

import (
	"image"
	"image/png"
	"log"
	"os"

	"github.com/spakin/accumimage"
)

// readImage reads an image from a named file.
func readImage(fn string) (image.Image, error) {
	r, err := os.Open(fn)
	if err != nil {
		return nil, err
	}
	img, _, err := image.Decode(r)
	if err != nil {
		return nil, err
	}
	return img, nil
}

// writeImage writes an image to a named file in PNG format.
func writeImage(fn string, img image.Image) error {
	w, err := os.Create(fn)
	if err != nil {
		return err
	}
	err = png.Encode(w, img)
	return err
}

func main() {
	// Read two images from files.
	if len(os.Args) != 3 {
		return
	}
	imgA, err := readImage(os.Args[1])
	if err != nil {
		log.Fatal(err)
	}
	imgB, err := readImage(os.Args[2])
	if err != nil {
		log.Fatal(err)
	}

	// Create an AccumNRGBA image imgC that's large enough to hold the
	// overlap of input images imgA and imgB.
	bndsA := imgA.Bounds()
	bndsB := imgB.Bounds()
	bndsC := bndsA.Union(bndsB)
	imgC := accumimage.NewAccumNRGBA(bndsC)

	// Blend image A with image C.
	for y := bndsA.Min.Y; y < bndsA.Max.Y; y++ {
		for x := bndsA.Min.X; x < bndsA.Max.X; x++ {
			imgC.Add(x, y, imgA.At(x, y))
		}
	}

	// Blend image B with image C.
	for y := bndsB.Min.Y; y < bndsB.Max.Y; y++ {
		for x := bndsB.Min.X; x < bndsB.Max.X; x++ {
			imgC.Add(x, y, imgB.At(x, y))
		}
	}

	// Write the blended image to a file.
	err = writeImage("image.png", imgC)
	if err != nil {
		log.Fatal(err)
	}
}

func (*AccumNRGBA) AddAccumNRGBA

func (p *AccumNRGBA) AddAccumNRGBA(x, y int, c accumcolor.AccumNRGBA)

AddAccumNRGBA accumulates a given color of type accumcolor.AccumNRGBA to the pixel at (x, y).

func (*AccumNRGBA) AddRGBA64

func (p *AccumNRGBA) AddRGBA64(x, y int, c color.RGBA64)

AddRGBA64 accumulates a given color of type color.RGBA64 to the pixel at (x, y).

func (*AccumNRGBA) At

func (p *AccumNRGBA) At(x, y int) color.Color

At returns the color of the pixel at (x, y) as a color.Color.

func (*AccumNRGBA) Bounds

func (p *AccumNRGBA) Bounds() image.Rectangle

Bounds returns the domain for which At can return non-zero color.

func (*AccumNRGBA) ColorModel

func (p *AccumNRGBA) ColorModel() color.Model

ColorModel returns the AccumNRGBA's color model (always accumcolor.AccumNRGBAModel).

func (*AccumNRGBA) NRGBAAt

func (p *AccumNRGBA) NRGBAAt(x, y int) color.NRGBA

NRGBAAt returns the color of the pixel at (x, y) as a color.NRGBA.

func (*AccumNRGBA) Opaque

func (p *AccumNRGBA) Opaque() bool

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

func (*AccumNRGBA) PixOffset

func (p *AccumNRGBA) PixOffset(x, y int) int

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

func (*AccumNRGBA) RGBA64At

func (p *AccumNRGBA) RGBA64At(x, y int) color.RGBA64

RGBA64At returns the color of the pixel at (x, y) as a color.RGBA64.

func (*AccumNRGBA) Set

func (p *AccumNRGBA) Set(x, y int, c color.Color)

Set sets the pixel at (x, y) to a given color of any type.

func (*AccumNRGBA) SetAccumNRGBA

func (p *AccumNRGBA) SetAccumNRGBA(x, y int, c accumcolor.AccumNRGBA)

SetAccumNRGBA sets the pixel at (x, y) to a given color of type accumcolor.AccumNRGBA.

func (*AccumNRGBA) SetRGBA64

func (p *AccumNRGBA) SetRGBA64(x, y int, c color.RGBA64)

SetRGBA64 sets the pixel at (x, y) to a given color of type color.RGBA64.

func (*AccumNRGBA) SubImage

func (p *AccumNRGBA) 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.