gomp

README

gomp

Go library for image blending and alpha compositing using advanced features like the Porter-Duff operator and blending modes.

About

The reason why this package has been developed is because the image/draw package from Go's standard library defines only one operation: drawing a source image onto the destination image, through an optional image mask. This is performed pixel by pixel and it's based on the classic "Compositing Digital Images" paper by Porter and Duff. This paper presented 12 different composition operation, but the Draw method uses only two of them: source over destination and source.

When dealing with image composition this is simply not enough. This library aims to overcome this deficiency by integrating the missing operators.

Alpha compositing

Blending modes

For convenience, this package implements also some of the most used blending modes in Photoshop. Similarly to the alpha compositing, blending modes defines the result of compositing a source and a destination but without being constrained to the alpha channel. The implementation follows the blending formulas presented in the W3C document: Compositing and Blending. These blending modes are not covered by Porter and Duff, but have been included into this package for convenience.

Blending modes

Installation

$ go install github.com/esimov/gomp@latest

API

The API of the library is inspired by the PorterDuff.Mode class from the Android SDK.

Alpha compositing

op := gomp.InitOp()
op.Set(gomp.SrcOver)
bmp := gomp.NewBitmap(image.Rect(0, 0, size, size))
imop.Draw(bmp, source, backdrop, nil)

Blending modes

op := gomp.NewBlend()
op.Set(gomp.Multiply)
bmp := gomp.NewBitmap(image.Rect(0, 0, size, size))
imop.Draw(bmp, source, backdrop, op)

You can combine the alpha compositing with blending modes at the same step, you just need to replace the last parameter of the Draw method with the initialized blending operation.

Alpha compositing and blending modes combined

imop := gomp.InitOp()
blop := gomp.NewBlend()
blop.Set(gomp.Multiply)
imop.Set(gomp.SrcOver)
bmp := gomp.NewBitmap(image.Rect(0, 0, size, size))
imop.Draw(bmp, srcImg, bgr, blop)

Operators

Image compositing	Separable blending modes	Non-separable blending modes
Clear	Normal	Hue
Copy	Darken	Saturation
Dst	Lighten	ColorMode
SrcOver	Multiply	Luminosity
DstOver	Screen
SrcIn	Overlay
DstIn	SoftLight
SrcOut	HardLight
DstOut	ColorDodge
SrcAtop	ColorBurn
DstAtop	Difference
	Exclusion

Examples

The images used in this document for visualizing the alpha compositing operation and the blending modes have been generated using this library. They can be found in the examples folder.

Author

• Endre Simo (@simo_endre)

License

Copyright © 2022 Endre Simo

This software is distributed under the MIT license. See the LICENSE file for the full license text.

Documentation

Overview

Package gomp implements the Porter-Duff composition operations used for mixing a graphic element with its backdrop. Porter and Duff presented in their paper 12 different composition operation, but the core image/draw core package implements only the source-over-destination and source. This package implements all of the 12 composite operation together with some blending modes.

Package gomp implements the Porter-Duff composition operations used for mixing a graphic element with its backdrop. Porter and Duff presented in their paper 12 different composition operation, but the core image/draw core package implements only the source-over-destination and source. This package implements all of the 12 composite operation together with some blending modes.

Index

• Constants
• func Abs[T constraints.Signed | constraints.Float](x T) T
• func Contains[T comparable](collection []T, value T) bool
• func ImgToNRGBA(img image.Image) *image.NRGBA
• func Max[T constraints.Ordered](values ...T) T
• func Min[T constraints.Ordered](values ...T) T
• type Bitmap
  • func NewBitmap(rect image.Rectangle) *Bitmap
• type Blend
  • func NewBlend() *Blend
  • func (bl *Blend) AlphaCompose(...) float64
  • func (bl *Blend) Get() string
  • func (bl *Blend) Lum(rgb Color) float64
  • func (bl *Blend) Sat(rgb Color) float64
  • func (bl *Blend) Set(blendType string) error
  • func (bl *Blend) SetLum(rgb Color, l float64) Color
  • func (bl *Blend) SetSat(rgb Color, s float64) Color
• type Color
• type Comp
  • func InitOp() *Comp
  • func (op *Comp) Draw(bitmap *Bitmap, src, dst *image.NRGBA, bl *Blend)
  • func (op *Comp) Get() string
  • func (op *Comp) Set(cop string) error

Constants

const (
	Normal     = "normal"
	Darken     = "darken"
	Lighten    = "lighten"
	Multiply   = "multiply"
	Screen     = "screen"
	Overlay    = "overlay"
	SoftLight  = "soft_light"
	HardLight  = "hard_light"
	ColorDodge = "color_dodge"
	ColorBurn  = "color_burn"
	Difference = "difference"
	Exclusion  = "exclusion"

	// Non-separable blend modes
	Hue        = "hue"
	Saturation = "saturation"
	ColorMode  = "color"
	Luminosity = "luminosity"
)

const (
	Clear   = "clear"
	Copy    = "copy"
	Dst     = "dst"
	SrcOver = "src_over"
	DstOver = "dst_over"
	SrcIn   = "src_in"
	DstIn   = "dst_in"
	SrcOut  = "src_out"
	DstOut  = "dst_out"
	SrcAtop = "src_atop"
	DstAtop = "dst_atop"
	Xor     = "xor"
)

Functions

func Abs

func Abs[T constraints.Signed | constraints.Float](x T) T

Abs returns the absolut value of x.

func Contains

func Contains[T comparable](collection []T, value T) bool

Contains returns true if a value is available in the collection.

func ImgToNRGBA

func ImgToNRGBA(img image.Image) *image.NRGBA

ImgToNRGBA converts any image type to *image.NRGBA with min-point at (0, 0).

func Max

func Max[T constraints.Ordered](values ...T) T

Max returns the biggest value from the provided parameters.

func Min

func Min[T constraints.Ordered](values ...T) T

Min returns the lowest value from the provided parameters.

Types

type Bitmap

type Bitmap struct {
	Img *image.NRGBA
}

Bitmap holds an image type as a placeholder for the Porter-Duff composition operations which can be used as a source or destination image.

func NewBitmap

func NewBitmap(rect image.Rectangle) *Bitmap

NewBitmap initializes a new Bitmap.

type Blend

type Blend struct {
	Current string
	Modes   []string
}

Blend struct contains the currently active blend mode and all the supported blend modes.

func NewBlend

func NewBlend() *Blend

NewBlend initializes a new Blend.

func (*Blend) AlphaCompose

func (bl *Blend) AlphaCompose(
	backdropAlpha,
	sourceAlpha,
	compositeAlpha,
	backdropColor,
	sourceColor,
	compositeColor float64,
) float64

Applies the alpha blending formula for a blend operation. See: https://www.w3.org/TR/compositing-1/#blending

func (*Blend) Get

func (bl *Blend) Get() string

Get returns the active blend mode.

func (*Blend) Lum

func (bl *Blend) Lum(rgb Color) float64

Lum gets the luminosity of a color.

func (*Blend) Sat

func (bl *Blend) Sat(rgb Color) float64

Sat gets the saturation of a color.

func (*Blend) Set

func (bl *Blend) Set(blendType string) error

Set activate one of the supported blend modes.

func (*Blend) SetLum

func (bl *Blend) SetLum(rgb Color, l float64) Color

SetLum set the luminosity on a color.

func (*Blend) SetSat

func (bl *Blend) SetSat(rgb Color, s float64) Color

type Color

type Color struct {
	R, G, B float64
}

Color represents the RGB channel of a specific color.

type Comp

type Comp struct {
	CurrentOp string
	Ops       []string
}

Comp struct contains the currently active composition operation and all the supported operations.

func InitOp

func InitOp() *Comp

InitOp initializes a new composition operation.

func (*Comp) Draw

func (op *Comp) Draw(bitmap *Bitmap, src, dst *image.NRGBA, bl *Blend)

Draw applies the currently active Ported-Duff composition operation formula, taking as parameter the source and the destination image and draws the result into the bitmap. If a blend mode is activated it will plug in the alpha blending formula also into the equation.

func (*Comp) Get

func (op *Comp) Get() string

Set changes the current composition operation.

func (*Comp) Set

func (op *Comp) Set(cop string) error

Set changes the current composition operation.