imgconv

README

Image Converter

Package imgconv provides basic image processing functions (resize, add watermark, format converter.).

All the image processing functions provided by the package accept any image type that implements image.Image interface as an input, include jpg(jpeg), png, gif, tif(tiff), bmp, webp(decode only) and pdf.

Installation

Required go version for building: go1.16 and up
go get -u github.com/sunshineplan/imgconv

Documentation

https://pkg.go.dev/github.com/sunshineplan/imgconv

License

The MIT License (MIT)

Credits

This repo relies on the following third-party projects:

• disintegration/imaging
• pdfcpu/pdfcpu
• hhrutter/tiff

Usage examples

A few usage examples can be found below. See the documentation for the full list of supported functions.

Image resizing

// Resize srcImage to size = 128x128px.
dstImage128 := imgconv.Resize(srcImage, imgconv.ResizeOption{Width: 128, Height: 128})

// Resize srcImage to width = 800px preserving the aspect ratio.
dstImage800 := imgconv.Resize(srcImage, imgconv.ResizeOption{Width: 800})

// Resize srcImage to 50% size preserving the aspect ratio.
dstImagePercent50 := imgconv.Resize(srcImage, imgconv.ResizeOption{Percent: 50})

Add watermark

// srcImage add a watermark at randomly position.
dstImage := imgconv.Watermark(srcImage, WatermarkOption{Mark: markImage, Opacity: 128, Random: true})

// srcImage add a watermark at fixed position with offset.
dstImage := imgconv.Watermark(srcImage, WatermarkOption{Mark: markImage, Opacity: 128, Offset: image.Pt(5, 5)})

Format convert

// Convert srcImage to dst with jpg format.
imgconv.Write(srcImage, dstWriter, imgconv.FormatOption{Format: imgconv.JPEG})

Example code

package main

import (
	"io"
	"log"

	"github.com/sunshineplan/imgconv"
)

func main() {
	// Open a test image.
	src, err := imgconv.Open("testdata/video-001.png")
	if err != nil {
		log.Fatalf("failed to open image: %v", err)
	}

	// Resize the image to width = 200px preserving the aspect ratio.
	mark := imgconv.Resize(src, imgconv.ResizeOption{Width: 200})

	// Add random watermark set opacity = 128.
	dst := imgconv.Watermark(src, imgconv.WatermarkOption{Mark: mark, Opacity: 128, Random: true})

	// Write the resulting image as TIFF.
	err = imgconv.Write(io.Discard, dst, imgconv.FormatOption{Format: imgconv.TIFF})
	if err != nil {
		log.Fatalf("failed to write image: %v", err)
	}
}

Documentation

Overview

Example

package main

import (
	"io"
	"log"

	"github.com/sunshineplan/imgconv"
)

func main() {
	// Open a test image.
	src, err := imgconv.Open("testdata/video-001.png")
	if err != nil {
		log.Fatalf("failed to open image: %v", err)
	}

	// Resize the image to width = 200px preserving the aspect ratio.
	mark := imgconv.Resize(src, imgconv.ResizeOption{Width: 200})

	// Add random watermark set opacity = 128.
	dst := imgconv.Watermark(src, imgconv.WatermarkOption{Mark: mark, Opacity: 128, Random: true})

	// Write the resulting image as TIFF.
	err = imgconv.Write(io.Discard, dst, imgconv.FormatOption{Format: imgconv.TIFF})
	if err != nil {
		log.Fatalf("failed to write image: %v", err)
	}
}

Index

• func Decode(r io.Reader) (image.Image, error)
• func DecodeConfig(r io.Reader) (image.Config, string, error)
• func Open(file string) (image.Image, error)
• func Resize(base image.Image, option ResizeOption) image.Image
• func Save(output string, base image.Image, option FormatOption) error
• func ToGray(img image.Image) image.Image
• func Watermark(base image.Image, option WatermarkOption) image.Image
• func Write(w io.Writer, base image.Image, option FormatOption) error
• type EncodeOption
  • func GIFDrawer(drawer draw.Drawer) EncodeOption
  • func GIFNumColors(numColors int) EncodeOption
  • func GIFQuantizer(quantizer draw.Quantizer) EncodeOption
  • func PNGCompressionLevel(level png.CompressionLevel) EncodeOption
  • func Quality(quality int) EncodeOption
  • func TIFFCompressionType(compressionType TIFFCompression) EncodeOption
• type Format
  • func FormatFromExtension(ext string) (Format, error)
• type FormatOption
  • func (f *FormatOption) Encode(w io.Writer, img image.Image) error
• type Options
  • func NewOptions() Options
  • func (opts *Options) Convert(w io.Writer, base image.Image) error
  • func (opts *Options) ConvertExt(filename string) string
  • func (opts *Options) SetFormat(f string, options ...EncodeOption) (err error)
  • func (opts *Options) SetGray(gray bool) *Options
  • func (opts *Options) SetResize(width, height int, percent float64) *Options
  • func (opts *Options) SetWatermark(mark image.Image, opacity uint) *Options
• type ResizeOption
• type TIFFCompression
• type WatermarkOption
  • func (w *WatermarkOption) SetOffset(offset image.Point) *WatermarkOption
  • func (w *WatermarkOption) SetRandom(random bool) *WatermarkOption

Examples

• Package

Functions

func Decode

func Decode(r io.Reader) (image.Image, error)

Decode reads an image from r.

func DecodeConfig

func DecodeConfig(r io.Reader) (image.Config, string, error)

DecodeConfig decodes the color model and dimensions of an image that has been encoded in a registered format. The string returned is the format name used during format registration.

func Open

func Open(file string) (image.Image, error)

Open loads an image from file.

func Resize

func Resize(base image.Image, option ResizeOption) image.Image

Resize add watermark to image

func Save

func Save(output string, base image.Image, option FormatOption) error

Save saves image according format option

func ToGray

func ToGray(img image.Image) image.Image

func Watermark

func Watermark(base image.Image, option WatermarkOption) image.Image

Watermark add watermark to image

func Write

func Write(w io.Writer, base image.Image, option FormatOption) error

Write image according format option

Types

type EncodeOption

type EncodeOption func(*encodeConfig)

EncodeOption sets an optional parameter for the Encode and Save functions. https://github.com/disintegration/imaging

func GIFDrawer

func GIFDrawer(drawer draw.Drawer) EncodeOption

GIFDrawer returns an EncodeOption that sets the drawer that is used to convert the source image to the desired palette of the GIF-encoded image.

func GIFNumColors

func GIFNumColors(numColors int) EncodeOption

GIFNumColors returns an EncodeOption that sets the maximum number of colors used in the GIF-encoded image. It ranges from 1 to 256. Default is 256.

func GIFQuantizer

func GIFQuantizer(quantizer draw.Quantizer) EncodeOption

GIFQuantizer returns an EncodeOption that sets the quantizer that is used to produce a palette of the GIF-encoded image.

func PNGCompressionLevel

func PNGCompressionLevel(level png.CompressionLevel) EncodeOption

PNGCompressionLevel returns an EncodeOption that sets the compression level of the PNG-encoded image. Default is png.DefaultCompression.

func Quality

func Quality(quality int) EncodeOption

Quality returns an EncodeOption that sets the output JPEG or PDF quality. Quality ranges from 1 to 100 inclusive, higher is better.

func TIFFCompressionType

func TIFFCompressionType(compressionType TIFFCompression) EncodeOption

TIFFCompressionType returns an EncodeOption that sets the compression type of the TIFF-encoded image. Default is tiff.Deflate.

type Format

type Format int

Format is an image file format.

const (
	JPEG Format = iota
	PNG
	GIF
	TIFF
	BMP
	PDF
)

Image file formats.

func FormatFromExtension

func FormatFromExtension(ext string) (Format, error)

FormatFromExtension parses image format from filename extension: "jpg" (or "jpeg"), "png", "gif", "tif" (or "tiff"), "bmp" and "pdf" are supported.

type FormatOption

type FormatOption struct {
	Format       Format
	EncodeOption []EncodeOption
}

FormatOption is format option

func (*FormatOption) Encode

func (f *FormatOption) Encode(w io.Writer, img image.Image) error

Encode writes the image img to w in the specified format (JPEG, PNG, GIF, TIFF, BMP or PDF).

type Options

type Options struct {
	Watermark *WatermarkOption
	Resize    *ResizeOption
	Format    FormatOption
	Gray      bool
}

Options represents options that can be used to configure a image operation.

func NewOptions

func NewOptions() Options

NewOptions creates a new option with default setting.

func (*Options) Convert

func (opts *Options) Convert(w io.Writer, base image.Image) error

Convert image according options opts.

func (*Options) ConvertExt

func (opts *Options) ConvertExt(filename string) string

ConvertExt convert filename's ext according image format.

func (*Options) SetFormat

func (opts *Options) SetFormat(f string, options ...EncodeOption) (err error)

SetFormat sets the value for the Format field.

func (*Options) SetGray

func (opts *Options) SetGray(gray bool) *Options

SetGray sets the value for the Gray field.

func (*Options) SetResize

func (opts *Options) SetResize(width, height int, percent float64) *Options

SetResize sets the value for the Resize field.

func (*Options) SetWatermark

func (opts *Options) SetWatermark(mark image.Image, opacity uint) *Options

SetWatermark sets the value for the Watermark field.

type ResizeOption

type ResizeOption struct {
	Width   int
	Height  int
	Percent float64
}

ResizeOption is resize option

type TIFFCompression

type TIFFCompression int

TIFFCompression describes the type of compression used in Options.

const (
	TIFFUncompressed TIFFCompression = iota
	TIFFDeflate
	TIFFLZW
	TIFFCCITTGroup3
	TIFFCCITTGroup4
	TIFFJPEG
)

Constants for supported TIFF compression types.

type WatermarkOption

type WatermarkOption struct {
	Mark    image.Image
	Opacity uint8
	Random  bool
	Offset  image.Point
}

WatermarkOption is watermark option

func (*WatermarkOption) SetOffset

func (w *WatermarkOption) SetOffset(offset image.Point) *WatermarkOption

SetOffset sets the option for the Watermark offset base center when adding fixed watermark.

func (*WatermarkOption) SetRandom

func (w *WatermarkOption) SetRandom(random bool) *WatermarkOption

SetRandom sets the option for the Watermark position random or not.