imgvips

README

IMGVips

Low-level bindings for libvips. For better shooting to the leg.

Implements VipsOperation builder, which allows you to call most of the existing image operations in the library.

Requirements

• livips 8+ (a higher version is usually better)
• Go 1.11+ (should work on lower versions, but I did not check)

Memory leak

To reduce memory leak and avoid possible SIGSEGV is recommended to disable libvips cache and vector calculations, i.e. use:

imgvips.VipsCacheSetMaxMem(0)
imgvips.VipsCacheSetMax(0)
imgvips.VipsVectorSetEnables(false)

Usage

See examples folder.

Load from filename

op, err := imgvips.NewOperation("webpload")
if err != nil {
    panic(err)
}
defer op.Free()

out := imgvips.GNullVipsImage()
op.AddInput("filename", imgvips.GString("path/to/image.webp"))
op.AddOutput("out", out)

if err := op.Exec(); err != nil {
    panic(err)
}

Load from bytes

op, err := imgvips.NewOperation("webpload_buffer")
if err != nil {
    panic(err)
}
defer op.Free()

out := imgvips.GNullVipsImage()
op.AddInput("buffer", imgvips.GVipsBlob(data))
op.AddOutput("out", out)

if err := op.Exec(); err != nil {
    panic(err)
}

Save to file

op, err := imgvips.NewOperation("jpegsave")
if err != nil {
    panic(err)
}
defer op.Free()

op.AddInput("in", gImage)
op.AddInput("filename", imgvips.GString("image.jpg"))

if err := op.Exec(); err != nil {
    panic(err)
}

Save to bytes

op, err := imgvips.NewOperation("jpegsave_buffer")
if err != nil {
    panic(err)
}
defer op.Free()

gData := imgvips.GNullVipsBlob()
op.AddInput("in", gImage)
op.AddOutput("buffer", gData)

if err := op.Exec(); err != nil {
    panic(err)
}

Documentation

Overview

Package imgvips provides low-level bindings for libvips: https://github.com/libvips/libvips. For better shooting to the leg.

Implements VipsOperation(https://libvips.github.io/libvips/API/current/VipsOperation.html) builder, which allows you to call most of the existing image operations in the library.

Example

nolint:funlen // For testing

package main

import (
	"errors"
	"log"

	"github.com/Arimeka/imgvips"
)

func main() {
	op, err := imgvips.NewOperation("webpload")
	if err != nil {
		log.Println(err)
		return
	}
	defer op.Free()

	out := imgvips.GNullVipsImage()
	op.AddInput("filename", imgvips.GString("./tests/fixtures/img.webp"))
	op.AddInput("scale", imgvips.GDouble(0.1))
	op.AddOutput("out", out)

	if err := op.Exec(); err != nil {
		log.Println(err)
		return
	}

	resizeOp, err := imgvips.NewOperation("resize")
	if err != nil {
		log.Println(err)
		return
	}
	defer resizeOp.Free()

	image, ok := out.Image()
	if !ok {
		log.Println(errors.New("out is not *C.VipsImage"))
		return
	}

	w := image.Width()
	h := image.Height()

	hScale := float64(350) / float64(h)
	wScale := float64(650) / float64(w)

	resizeOut := imgvips.GNullVipsImage()
	resizeOp.AddInput("in", out)
	resizeOp.AddInput("scale", imgvips.GDouble(wScale))
	resizeOp.AddInput("vscale", imgvips.GDouble(hScale))
	resizeOp.AddOutput("out", resizeOut)

	if err := resizeOp.Exec(); err != nil {
		log.Println(err)
		return
	}

	saveOp, err := imgvips.NewOperation("webpsave")
	if err != nil {
		log.Println(err)
		return
	}
	defer saveOp.Free()

	saveOp.AddInput("in", resizeOut)
	saveOp.AddInput("filename", imgvips.GString("./tests/fixtures/resized.webp"))
	saveOp.AddInput("Q", imgvips.GInt(50))
	saveOp.AddInput("strip", imgvips.GBoolean(true))

	if err := saveOp.Exec(); err != nil {
		log.Println(err)
		return
	}
}

Index

• Variables
• func GetAllocs() float64
• func GetMem() float64
• func GetMemHighwater() float64
• func Initialize(options ...InitOption) error
• func VipsErrorFree()
• type Argument
  • func (a *Argument) Free()
• type GValue
  • func GBoolean(value bool) *GValue
  • func GDouble(value float64) *GValue
  • func GInt(value int) *GValue
  • func GNullVipsBlob() *GValue
  • func GNullVipsImage() *GValue
  • func GString(value string) *GValue
  • func GVipsBlob(data []byte) *GValue
  • func (v *GValue) Boolean() (value, ok bool)
  • func (v *GValue) Bytes() (value []byte, ok bool)
  • func (v *GValue) Copy() (*GValue, error)
  • func (v *GValue) Double() (value float64, ok bool)
  • func (v *GValue) Free()
  • func (v *GValue) Image() (value *Image, ok bool)
  • func (v *GValue) Int() (value int, ok bool)
  • func (v *GValue) Ptr() unsafe.Pointer
  • func (v *GValue) String() (value string, ok bool)
• type Image
  • func (i *Image) Height() int
  • func (i *Image) Ptr() unsafe.Pointer
  • func (i *Image) Width() int
• type InitOption
  • func VipsCacheSetMax(n int) InitOption
  • func VipsCacheSetMaxMem(n int) InitOption
  • func VipsConcurrencySet(n int) InitOption
  • func VipsDetectMemoryLeak(on bool) InitOption
  • func VipsVectorSetEnables(enabled bool) InitOption
• type Operation
  • func NewOperation(name string) (*Operation, error)
  • func (op *Operation) AddInput(name string, value Value)
  • func (op *Operation) AddOutput(name string, value Value)
  • func (op *Operation) Exec() error
  • func (op *Operation) Free()
• type Value

Examples

• Package

Variables

var (
	// ErrCopyForbidden returns when GValue forbid copy function
	ErrCopyForbidden = errors.New("copy forbidden for this type")
)

var (
	// ErrOperationAlreadyFreed operation already call Free()
	ErrOperationAlreadyFreed = errors.New("operation already freed")
)

Functions

func GetAllocs

func GetAllocs() float64

GetAllocs return libvips tracked number of active allocations

func GetMem

func GetMem() float64

GetMem return libvips tracked memory

func GetMemHighwater

func GetMemHighwater() float64

GetMemHighwater return libvips tracked memory high-water

func Initialize

func Initialize(options ...InitOption) error

Initialize libvips

By default, libvips cache will be turned off (set to zero), vector arithmetic - turned on.

func VipsErrorFree

func VipsErrorFree()

VipsErrorFree clear error buffer

Types

type Argument

type Argument struct {
	// contains filtered or unexported fields
}

Argument contains key-gValue for set it to *C.VipsOperation

func (*Argument) Free

func (a *Argument) Free()

Free freed argument cName and gValue

type GValue

type GValue struct {
	// contains filtered or unexported fields
}

GValue contains glib gValue and its type

func GBoolean

func GBoolean(value bool) *GValue

GBoolean transform bool gValue to glib gValue

func GDouble

func GDouble(value float64) *GValue

GDouble transform float64 gValue to glib gValue

func GInt

func GInt(value int) *GValue

GInt transform int gValue to glib gValue

func GNullVipsBlob

func GNullVipsBlob() *GValue

GNullVipsBlob create empty glib object gValue with type for *C.VipsBlob Calling Copy() at GValue with type VipsBlob is forbidden.

func GNullVipsImage

func GNullVipsImage() *GValue

GNullVipsImage create empty glib object gValue with type for *C.VipsImage.

Calling Copy() at empty *C.VipsImage will return error.

func GString

func GString(value string) *GValue

GString transform string gValue to glib gValue

func GVipsBlob

func GVipsBlob(data []byte) *GValue

GVipsBlob create VipsBlob from bytes array.

You must protect bytes array from GC and modification while using the VipsImage loaded from this blob.

VipsBlob is used in load_buffer and save_buffer. VipsBlob is a boxed type, so we use g_value_set_boxed instead of g_value_set_object.

Calling Copy() at GValue with type VipsBlob is forbidden.

func (*GValue) Boolean

func (v *GValue) Boolean() (value, ok bool)

Boolean return boolean gValue, if type is GBoolean. If type not match, ok will return false. If gValue already freed, gValue will be false, ok will be true.

func (*GValue) Bytes

func (v *GValue) Bytes() (value []byte, ok bool)

Bytes return bytes slice from GValue.

If type not match, ok will return false. If VipsBlob already freed, return nil value, ok will be true.

func (*GValue) Copy

func (v *GValue) Copy() (*GValue, error)

Copy create new instance of *GValue with new *C.gValue and run copy() func

func (*GValue) Double

func (v *GValue) Double() (value float64, ok bool)

Double return float64 gValue, if type is GDouble. If type not match, ok will return false. If gValue already freed, gValue will be 0, ok will be true.

func (*GValue) Free

func (v *GValue) Free()

Free call free func for unref gValue

func (*GValue) Image

func (v *GValue) Image() (value *Image, ok bool)

Image return *Image, if type is *C.VipsImage.

If type not match, ok will return false. If gValue already freed, gValue will be nil, ok will be true.

func (*GValue) Int

func (v *GValue) Int() (value int, ok bool)

Int return int gValue, if type is GInt. If type not match, ok will return false. If gValue already freed, gValue will be 0, ok will be true.

func (*GValue) Ptr

func (v *GValue) Ptr() unsafe.Pointer

Ptr return unsafe pointer to *C.GValue

func (*GValue) String

func (v *GValue) String() (value string, ok bool)

String return string gValue, if type is GString. If type not match, ok will return false. If gValue already freed, gValue will be empty string, ok will be true.

type Image

type Image struct {
	// contains filtered or unexported fields
}

Image wrapper around *C.VipsImage

func (*Image) Height

func (i *Image) Height() int

Height return image height Return 0 if image was freed

func (*Image) Ptr

func (i *Image) Ptr() unsafe.Pointer

Ptr return unsafe pointer to *C.VipsImage

func (*Image) Width

func (i *Image) Width() int

Width return image width Return 0 if image was freed

type InitOption

type InitOption struct {
	// contains filtered or unexported fields
}

InitOption specifies an option for initialize libvips

func VipsCacheSetMax

func VipsCacheSetMax(n int) InitOption

VipsCacheSetMax set maximum number of operation to cache

func VipsCacheSetMaxMem

func VipsCacheSetMaxMem(n int) InitOption

VipsCacheSetMaxMem set maximum amount of tracked memory

func VipsConcurrencySet

func VipsConcurrencySet(n int) InitOption

VipsConcurrencySet set number of threads to use

func VipsDetectMemoryLeak

func VipsDetectMemoryLeak(on bool) InitOption

VipsDetectMemoryLeak turn on/off memory leak reports

func VipsVectorSetEnables

func VipsVectorSetEnables(enabled bool) InitOption

VipsVectorSetEnables enable fast vector path based on half-float arithmetic

type Operation

type Operation struct {
	// contains filtered or unexported fields
}

Operation wrapper around *C.VipsOperation.

It contains separates arguments for set to operation and arguments to return from operation.

func NewOperation

func NewOperation(name string) (*Operation, error)

NewOperation initialize new *C.VipsOperation.

If libvips don't known operation with provided name, function return error.

func (*Operation) AddInput

func (op *Operation) AddInput(name string, value Value)

AddInput adds argument for set to operation.

After call *Operation.Exec(), all values from input arguments will be freed.

func (*Operation) AddOutput

func (op *Operation) AddOutput(name string, value Value)

AddOutput adds argument for get from operation.

After call Exec(), all values from output arguments will be updated from operation result. These arguments will be freed after call *Operation.Free()

func (*Operation) Exec

func (op *Operation) Exec() error

Exec executes operation.

After execute all input arguments will be freed, all output arguments will be updated. If operation return error, input arguments will be freed, all output arguments will not be updated and not be freed.

func (*Operation) Free

func (op *Operation) Free()

Free freed operation outputs, unref operation, and clear vips error

type Value

type Value interface {
	// Free freed data in C
	Free()
	// Ptr return unsafe pointer to *C.GValue
	Ptr() unsafe.Pointer
}

Value is interface for create own value for operation argument