imaging

package module
v0.0.0-...-9e6af48 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 8, 2014 License: MIT Imports: 16 Imported by: 2

README

Imaging

Package imaging provides basic image manipulation functions (resize, rotate, flip, crop, etc.). This package is based on the standard Go image package and works best along with it.

Installation

go get -u github.com/disintegration/imaging

Git and Mercurial are needed.

Documentation

http://godoc.org/github.com/disintegration/imaging

Overview

Image manipulation functions provided by the package take any image type that implements image.Image interface as an input, and return a new image of *image.NRGBA type (32bit RGBA colors, not premultiplied by alpha).

Note: some of examples below require importing standard image or image/color packages.

Parallelization

Imaging package uses parallel goroutines for faster image processing. To achieve maximum performance, make sure to allow Go to utilize all CPU cores. Use standard runtime package:

runtime.GOMAXPROCS(runtime.NumCPU())
Resize

There are three image resizing functions in the package: Resize, Fit and Thumbnail.

Resize resizes the image to the specified width and height using the specified resample filter and returns the transformed image. If one of width or height is 0, the image aspect ratio is preserved.

Fit scales down the image using the specified resample filter to fit the specified maximum width and height and returns the transformed image. The image aspect ratio is preserved.

Thumbnail scales the image up or down using the specified resample filter, crops it to the specified width and hight and returns the transformed image.

All three resizing function take ResampleFilter as the last argument. A complete list of supported filters: NearestNeighbor, Box, Linear, Hermite, MitchellNetravali, CatmullRom, BSpline, Gaussian, Lanczos, Hann, Hamming, Blackman, Bartlett, Welch, Cosine. CatmullRom (cubic filter) and Lanczos are recommended for high quality general purpose image resizing. NearestNeighbor is the fastest one but applies no anti-aliasing.

// resize srcImage to width = 800px preserving the aspect ratio
dstImage := imaging.Resize(srcImage, 800, 0, imaging.Lanczos)

// scale down srcImage to fit the 800x600px bounding box
dstImage = imaging.Fit(srcImage, 800, 600, imaging.Lanczos)

// make a 100x100px thumbnail from srcImage
dstImage = imaging.Thumbnail(srcImage, 100, 100, imaging.Lanczos)
Rotate & flip

Imaging package implements functions to rotate an image 90, 180 or 270 degrees (counter-clockwise) and to flip an image horizontally or vertically.

dstImage = imaging.Rotate90(srcImage)  // rotate 90 degrees counter-clockwise
dstImage = imaging.Rotate180(srcImage) // rotate 180 degrees counter-clockwise
dstImage = imaging.Rotate270(srcImage) // rotate 270 degrees counter-clockwise
dstImage = imaging.FlipH(srcImage)     // flip horizontally (from left to right)
dstImage = imaging.FlipV(srcImage)     // flip vertically (from top to bottom)
Crop, Paste, Overlay

Crop cuts out a rectangular region with the specified bounds from the image and returns the cropped image.

CropCenter cuts out a rectangular region with the specified size from the center of the image and returns the cropped image.

Paste pastes one image into another at the specified position and returns the combined image.

PasteCenter pastes one image to the center of another image and returns the combined image.

Overlay draws one image over another image at the specified position with the specified opacity and returns the combined image. Opacity parameter must be from 0.0 (fully transparent) to 1.0 (opaque).

// cut out a rectangular region from the image
dstImage = imaging.Crop(srcImage, image.Rect(50, 50, 100, 100)) 

// cut out a 100x100 px region from the center of the image
dstImage = imaging.CropCenter(srcImage, 100, 100)   

// paste the srcImage to the backgroundImage at the (50, 50) position
dstImage = imaging.Paste(backgroundImage, srcImage, image.Pt(50, 50))     

// paste the srcImage to the center of the backgroundImage
dstImage = imaging.PasteCenter(backgroundImage, srcImage)                   

// draw the srcImage over the backgroundImage at the (50, 50) position with opacity=0.5
dstImage = imaging.Overlay(backgroundImage, srcImage, image.Pt(50, 50), 0.5)
Blur & Sharpen

Blur produces a blurred version of the image.

Sharpen produces a sharpened version of the image.

Both functions take the sigma argument that is used in a Gaussian function. Sigma must be a positive floating point value indicating how much the image will be blurred or sharpened and how many neighbours of each pixel will be affected.

dstImage = imaging.Blur(srcImage, 4.5)
dstImage = imaging.Sharpen(srcImage, 3.0)
Adjustments

AdjustGamma performs a gamma correction on the image and returns the adjusted image. Gamma parameter must be positive. Gamma = 1.0 gives the original image. Gamma less than 1.0 darkens the image and gamma greater than 1.0 lightens it.

dstImage = imaging.AdjustGamma(srcImage, 0.7)

AdjustBrightness changes the brightness of the image using the percentage parameter and returns the adjusted image. The percentage must be in range (-100, 100). The percentage = 0 gives the original image. The percentage = -100 gives solid black image. The percentage = 100 gives solid white image.

dstImage = imaging.AdjustBrightness(srcImage, 10) // increase the brightness by 10%
dstImage = imaging.AdjustBrightness(srcImage, -15) // decrease the brightness by 15%

AdjustContrast changes the contrast of the image using the percentage parameter and returns the adjusted image. The percentage must be in range (-100, 100). The percentage = 0 gives the original image. The percentage = -100 gives solid grey image.

dstImage = imaging.AdjustContrast(srcImage, 20) // increase the contrast by 20%
dstImage = imaging.AdjustContrast(srcImage, -10) // decrease the contrast by 10%

AdjustSigmoid changes the contrast of the image using a sigmoidal function and returns the adjusted image. It's a non-linear contrast change useful for photo adjustments as it preserves highlight and shadow detail. The midpoint parameter is the midpoint of contrast that must be between 0 and 1, typically 0.5. The factor parameter indicates how much to increase or decrease the contrast, typically in range (-10, 10). If the factor parameter is positive the image contrast is increased otherwise the contrast is decreased.

dstImage = imaging.AdjustSigmoid(srcImage, 0.5, 3.0) // increase the contrast
dstImage = imaging.AdjustSigmoid(srcImage, 0.5, -3.0) // decrease the contrast

Grayscale produces grayscale version of the image.

dstImage = imaging.Grayscale(srcImage)

Invert produces inverted (negated) version of the image.

dstImage = imaging.Invert(srcImage)
Open, Save, New, Clone

Imaging package provides useful shortcuts for image loading, saving, creation and copying. Open and Save functions support JPEG, PNG, TIFF and BMP images. External libraries can be used to load other image formats.

// load an image from file
img, err := imaging.Open("src.png") 
if err != nil {
    panic(err)
}

// save the image to file
err = imaging.Save(img, "dst.jpg") 
if err != nil {
    panic(err)
}

// create a new 800x600px image filled with red color
newImg := imaging.New(800, 600, color.NRGBA{255, 0, 0, 255})

// make a copy of the image
copiedImg := imaging.Clone(img)

Code example

Here is the complete example that loades several images, makes thumbnails of them and joins them together.

package main

import (
    "image"
    "image/color"
    "runtime"
    
    "github.com/disintegration/imaging"
)

func main() {
    // use all CPU cores for maximum performance
    runtime.GOMAXPROCS(runtime.NumCPU())

    // input files
    files := []string{"01.jpg", "02.jpg", "03.jpg"}

    // load images and make 100x100 thumbnails of them
    var thumbnails []image.Image
    for _, file := range files {
        img, err := imaging.Open(file)
        if err != nil {
            panic(err)
        }
        thumb := imaging.Thumbnail(img, 100, 100, imaging.CatmullRom)
        thumbnails = append(thumbnails, thumb)
    }

    // create a new blank image
    dst := imaging.New(100*len(thumbnails), 100, color.NRGBA{0, 0, 0, 0})

    // paste thumbnails into the new image side by side
    for i, thumb := range thumbnails {
        dst = imaging.Paste(dst, thumb, image.Pt(i*100, 0))
    }

    // save the combined image to file
    err := imaging.Save(dst, "dst.jpg")
    if err != nil {
        panic(err)
    }
}

Documentation

Overview

Package imaging provides basic image manipulation functions (resize, rotate, flip, crop, etc.). This package is based on the standard Go image package and works best along with it.

Image manipulation functions provided by the package take any image type that implements `image.Image` interface as an input, and return a new image of `*image.NRGBA` type (32bit RGBA colors, not premultiplied by alpha).

Imaging package uses parallel goroutines for faster image processing. To achieve maximum performance, make sure to allow Go to utilize all CPU cores: 

runtime.GOMAXPROCS(runtime.NumCPU())

Here is the complete example that loades several images, makes thumbnails of them and joins them together. 

package main

import (
	"image"
	"image/color"
	"runtime"

	"github.com/disintegration/imaging"
)

func main() {
	// use all CPU cores for maximum performance
	runtime.GOMAXPROCS(runtime.NumCPU())

	// input files
	files := []string{"01.jpg", "02.jpg", "03.jpg"}

	// load images and make 100x100 thumbnails of them
	var thumbnails []image.Image
	for _, file := range files {
		img, err := imaging.Open(file)
		if err != nil {
			panic(err)
		}
		thumb := imaging.Thumbnail(img, 100, 100, imaging.CatmullRom)
		thumbnails = append(thumbnails, thumb)
	}

	// create a new blank image
	dst := imaging.New(100*len(thumbnails), 100, color.NRGBA{0, 0, 0, 0})

	// paste thumbnails into the new image side by side
	for i, thumb := range thumbnails {
		dst = imaging.Paste(dst, thumb, image.Pt(i*100, 0))
	}

	// save the combined image to file
	err := imaging.Save(dst, "dst.jpg")
	if err != nil {
		panic(err)
	}
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AdjustBrightness 

func AdjustBrightness(img image.Image, percentage float64) *image.NRGBA

AdjustBrightness changes the brightness of the image using the percentage parameter and returns the adjusted image. The percentage must be in range (-100, 100). The percentage = 0 gives the original image. The percentage = -100 gives solid black image. The percentage = 100 gives solid white image.

Examples: 

dstImage = imaging.AdjustBrightness(srcImage, -15) // decrease image brightness by 15%
dstImage = imaging.AdjustBrightness(srcImage, 10) // increase image brightness by 10%

func AdjustContrast 

func AdjustContrast(img image.Image, percentage float64) *image.NRGBA

AdjustContrast changes the contrast of the image using the percentage parameter and returns the adjusted image. The percentage must be in range (-100, 100). The percentage = 0 gives the original image. The percentage = -100 gives solid grey image.

Examples: 

dstImage = imaging.AdjustContrast(srcImage, -10) // decrease image contrast by 10%
dstImage = imaging.AdjustContrast(srcImage, 20) // increase image contrast by 20%

func AdjustGamma 

func AdjustGamma(img image.Image, gamma float64) *image.NRGBA

AdjustGamma performs a gamma correction on the image and returns the adjusted image. Gamma parameter must be positive. Gamma = 1.0 gives the original image. Gamma less than 1.0 darkens the image and gamma greater than 1.0 lightens it.

Example: 

dstImage = imaging.AdjustGamma(srcImage, 0.7)

func AdjustSigmoid 

func AdjustSigmoid(img image.Image, midpoint, factor float64) *image.NRGBA

AdjustSigmoid changes the contrast of the image using a sigmoidal function and returns the adjusted image. It's a non-linear contrast change useful for photo adjustments as it preserves highlight and shadow detail. The midpoint parameter is the midpoint of contrast that must be between 0 and 1, typically 0.5. The factor parameter indicates how much to increase or decrease the contrast, typically in range (-10, 10). If the factor parameter is positive the image contrast is increased otherwise the contrast is decreased.

Examples: 

dstImage = imaging.AdjustSigmoid(srcImage, 0.5, 3.0) // increase the contrast
dstImage = imaging.AdjustSigmoid(srcImage, 0.5, -3.0) // decrease the contrast

func Blur 

func Blur(img image.Image, sigma float64) *image.NRGBA

Blur produces a blurred version of the image using a Gaussian function. Sigma parameter must be positive and indicates how much the image will be blurred.

Usage example: 

dstImage := imaging.Blur(srcImage, 3.5)

func Clone 

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

Clone returns a copy of the given image.

func Crop 

func Crop(img image.Image, rect image.Rectangle) *image.NRGBA

Crop cuts out a rectangular region with the specified bounds from the image and returns the cropped image.

func CropCenter 

func CropCenter(img image.Image, width, height int) *image.NRGBA

CropCenter cuts out a rectangular region with the specified size from the center of the image and returns the cropped image.

func Fit 

func Fit(img image.Image, width, height int, filter ResampleFilter) *image.NRGBA

Fit scales down the image using the specified resample filter to fit the specified maximum width and height and returns the transformed image.

Supported resample filters: NearestNeighbor, Box, Linear, Hermite, MitchellNetravali, CatmullRom, BSpline, Gaussian, Lanczos, Hann, Hamming, Blackman, Bartlett, Welch, Cosine.

Usage example: 

dstImage := imaging.Fit(srcImage, 800, 600, imaging.Lanczos)

func FlipH 

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

FlipH flips the image horizontally (from left to right) and returns the transformed image.

func FlipV 

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

FlipV flips the image vertically (from top to bottom) and returns the transformed image.

func Grayscale 

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

Grayscale produces grayscale version of the image.

func Invert 

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

Invert produces inverted (negated) version of the image.

func New 

func New(width, height int, fillColor color.Color) *image.NRGBA

New creates a new image with the specified width and height, and fills it with the specified color.

func Open 

func Open(filename string) (img image.Image, err error)

Open loads an image from file

func Overlay 

func Overlay(background, img image.Image, pos image.Point, opacity float64) *image.NRGBA

Overlay draws the img image over the background image at given position and returns the combined image. Opacity parameter is the opacity of the img image layer, used to compose the images, it must be from 0.0 to 1.0.

Usage examples: 

// draw the sprite over the background at position (50, 50)
dstImage := imaging.Overlay(backgroundImage, spriteImage, image.Pt(50, 50), 1.0)

// blend two opaque images of the same size
dstImage := imaging.Overlay(imageOne, imageTwo, image.Pt(0, 0), 0.5)

func Paste 

func Paste(background, img image.Image, pos image.Point) *image.NRGBA

Paste pastes the img image to the background image at the specified position and returns the combined image.

func PasteCenter 

func PasteCenter(background, img image.Image) *image.NRGBA

PasteCenter pastes the img image to the center of the background image and returns the combined image.

func Resize 

func Resize(img image.Image, width, height int, filter ResampleFilter) *image.NRGBA

Resize resizes the image to the specified width and height using the specified resampling filter and returns the transformed image. If one of width or height is 0, the image aspect ratio is preserved.

Supported resample filters: NearestNeighbor, Box, Linear, Hermite, MitchellNetravali, CatmullRom, BSpline, Gaussian, Lanczos, Hann, Hamming, Blackman, Bartlett, Welch, Cosine.

Usage example: 

dstImage := imaging.Resize(srcImage, 800, 600, imaging.Lanczos)

func Rotate180 

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

Rotate180 rotates the image 180 degrees counterclockwise and returns the transformed image.

func Rotate270 

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

Rotate270 rotates the image 270 degrees counterclockwise and returns the transformed image.

func Rotate90 

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

Rotate90 rotates the image 90 degrees counterclockwise and returns the transformed image.

func Save 

func Save(img image.Image, filename string) (err error)

Save saves the image to file with the specified filename. The format is determined from the filename extension: "jpg" (or "jpeg"), "png", "tif" (or "tiff") and "bmp" are supported.

func Sharpen 

func Sharpen(img image.Image, sigma float64) *image.NRGBA

Sharpen produces a sharpened version of the image. Sigma parameter must be positive and indicates how much the image will be sharpened.

Usage example: 

dstImage := imaging.Sharpen(srcImage, 3.5)

func Thumbnail 

func Thumbnail(img image.Image, width, height int, filter ResampleFilter) *image.NRGBA

Thumbnail scales the image up or down using the specified resample filter, crops it to the specified width and hight and returns the transformed image.

Supported resample filters: NearestNeighbor, Box, Linear, Hermite, MitchellNetravali, CatmullRom, BSpline, Gaussian, Lanczos, Hann, Hamming, Blackman, Bartlett, Welch, Cosine.

Usage example: 

dstImage := imaging.Fit(srcImage, 100, 100, imaging.Lanczos)

Types

type ResampleFilter 

type ResampleFilter struct {
	Support float64
	Kernel  func(float64) float64
}

Resample filter struct. It can be used to make custom filters.

Supported resample filters: NearestNeighbor, Box, Linear, Hermite, MitchellNetravali, CatmullRom, BSpline, Gaussian, Lanczos, Hann, Hamming, Blackman, Bartlett, Welch, Cosine. 

General filter recommendations:

- Lanczos
	Probably the best resampling filter for photographic images yielding sharp results,
	but it's slower than cubic filters (see below).

- CatmullRom
	A sharp cubic filter. It's a good filter for both upscaling and downscaling if sharp results are needed.

- MitchellNetravali
	A high quality cubic filter that produces smoother results with less ringing than CatmullRom.

- BSpline
	A good filter if a very smooth output is needed.

- Linear
	Bilinear interpolation filter, produces reasonably good, smooth output. It's faster than cubic filters.

- Box
	Simple and fast resampling filter appropriate for downscaling.
	When upscaling it's similar to NearestNeighbor.

- NearestNeighbor
	Fastest resample filter, no antialiasing at all. Rarely used.

var BSpline ResampleFilter

Cubic B-spline - smooth cubic filter (BC-spline; B=1; C=0). 

var Bartlett ResampleFilter

Bartlett-windowed sinc filter (3 lobes). 

var Blackman ResampleFilter

Blackman-windowed sinc filter (3 lobes). 

var Box ResampleFilter

Box filter (averaging pixels). 

var CatmullRom ResampleFilter

Catmull-Rom - sharp cubic filter (BC-spline; B=0; C=0.5). 

var Cosine ResampleFilter

Cosine-windowed sinc filter (3 lobes). 

var Gaussian ResampleFilter

Gaussian Blurring Filter. 

var Hamming ResampleFilter

Hamming-windowed sinc filter (3 lobes). 

var Hann ResampleFilter

Hann-windowed sinc filter (3 lobes). 

var Hermite ResampleFilter

Hermite cubic spline filter (BC-spline; B=0; C=0). 

var Lanczos ResampleFilter

Lanczos filter (3 lobes). 

var Linear ResampleFilter

Linear filter. 

var MitchellNetravali ResampleFilter

Mitchell-Netravali cubic filter (BC-spline; B=1/3; C=1/3). 

var NearestNeighbor ResampleFilter

Nearest-neighbor filter, no anti-aliasing. 

var Welch ResampleFilter

Welch-windowed sinc filter (parabolic window, 3 lobes).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.