README
¶
C++ image library bindings for Go
cimg is a Go wrapper for various C/C++ image libraries, including:
- libjpeg-turbo
- stb_image_resize2
- Unrotate image so that natural encoding orientation is same as display orientation
- Reading and writing EXIF orientation (provided via native Go code)
Why?
There are a host of high-performance C/C++ libraries out there for image manipulation, and it's near impossible to write the same kind of code in Go.
Example: Compress/Decompress with TurboJPEG
import "github.com/bmharper/cimg"
func compressImage(width, height int, rgb []byte) {
raw := cimg.Image{
Width: width,
Height: height,
Stride: width * 3,
Pixels: rgb,
}
params := cimg.MakeCompressParams(cimg.PixelFormatRGB, cimg.Sampling420, 35, 0)
jpg, err := cimg.Compress(&raw, params)
}
func decompressImage(jpg []byte) (*Image, error) {
return cimg.Decompress(jpg)
}
Example: Read and Modify EXIF Orientation
import "github.com/bmharper/cimg"
func inspectOrientation(jpgRaw []byte) {
// Parse JPEG/JFIF segments, and read EXIF Orientation tag
jpgExif, err = cimg.LoadExif(jpgRaw)
fmt.Printf("Orientation: %v\n", jpgExif.GetOrientation())
// Modify EXIF rotation.
// If the file contains no EXIF data, then this will create an
// EXIF "segment".
err = jpgExif.SetOrientation(3)
out := bytes.Buffer{}
err = jpgExif.Save(&out)
}
Example: Resize with stb_image_resize2
import "github.com/bmharper/cimg"
// Resize from bytes
func resizeImage(srcWidth, srcHeight int, rgba []byte, dstWidth, dstHeight int) *cimg.Image {
src := cimg.WrapImage(srcWidth, srcHeight, 4, rgba)
return cimg.ResizeNew(src, dstWidth, dstHeight)
}
C/C++ compiler optimizations
I was initially worried that I needed to add the directive #cgo CXXFLAGS: -O2, but it looks like
cgo compiles with optimizations on by default. You can verify this by adding #cgo CXXFLAGS: -O0
to resize.go, and run go test -bench=.. Compare with -O0 and -O2 and there should be
a big difference. Removing the comment entirely should give similar performance to -O2.
System requirements
I have only tested this on Ubuntu 20.04 amd64.
To install the necessary packages:
apt install libturbojpeg0-dev
Testing
Warning! Many of the Go unit tests don't actually validate their results. Instead, they
simply write out a JPEG file into the test directory. It's your job to visually see that they look correct.
Documentation
¶
Index ¶
- Constants
- Variables
- func Compress(img *Image, params CompressParams) ([]byte, error)
- func NChan(pf PixelFormat) int
- func Resize(src, dst *Image, params *ResizeParams) error
- func Rotate(src *Image, dst *Image, angleRadians float64, params *RotateParams)
- type CompressParams
- type ExifData
- type Flags
- type Image
- func Decompress(encoded []byte) (*Image, error)
- func FromImage(src image.Image, allowDeepClone bool) (*Image, error)
- func NewImage(width, height int, format PixelFormat) *Image
- func ReadFile(filename string) (*Image, error)
- func ResizeNew(src *Image, dstWidth, dstHeight int, params *ResizeParams) *Image
- func UnrotateExif(exifOrientation int, src *Image) (*Image, error)
- func WrapImage(width, height int, format PixelFormat, pixels []byte) *Image
- func WrapImageStrided(width, height int, format PixelFormat, pixels []byte, stride int) *Image
- func (img *Image) AvgColor() []uint8
- func (img *Image) Clone() *Image
- func (dst *Image) CopyImage(src *Image, dstX1, dstY1 int) error
- func (dst *Image) CopyImageRect(src *Image, srcX1, srcY1, srcX2, srcY2 int, dstX1, dstY1 int) error
- func (img *Image) DrawRectangle(x1, y1, x2, y2 int, r, g, b uint8)
- func (img *Image) IsDense() bool
- func (img *Image) Matte(r, g, b uint8)
- func (img *Image) NChan() int
- func (img *Image) PixelByte(x, y int) int
- func (img *Image) Premultiply()
- func (img *Image) ReferenceCrop(x1, y1, x2, y2 int) *Image
- func (img *Image) ToGray() *Image
- func (img *Image) ToImage() (image.Image, error)
- func (img *Image) ToRGB() *Image
- func (img *Image) ToRGBA(alpha uint8) *Image
- func (img *Image) WriteJPEG(filename string, params CompressParams, perm os.FileMode) error
- type PixelFormat
- type ResizeEdge
- type ResizeFilter
- type ResizeParams
- type RotateFilter
- type RotateParams
- type Sampling
Constants ¶
const (
ExifTagOrientation = 0x112 // Photo orientation
)
const RotateDefaultSnapThreshold = 0.01 * math.Pi / 180
Variables ¶
var ErrNoAlpha = errors.New("Image has no alpha channel")
Functions ¶
func Compress ¶
func Compress(img *Image, params CompressParams) ([]byte, error)
Compress compresses an image using TurboJPEG
func NChan ¶
func NChan(pf PixelFormat) int
NChan returns the number of channels of the pixel format
func Resize ¶
func Resize(src, dst *Image, params *ResizeParams) error
Resize resizes an image into a destination buffer that you provide Assumes sRGB image
Types ¶
type CompressParams ¶
CompressParams are the TurboJPEG compression parameters
func MakeCompressParams ¶
func MakeCompressParams(sampling Sampling, quality int, flags Flags) CompressParams
MakeCompressParams returns a fully populated CompressParams struct
type ExifData ¶
type ExifData struct {
// contains filtered or unexported fields
}
ExifData is a wrapper around github.com/dsoprea/go-exif, with only the tags exposed that I've needed to manipulate
func LoadExif ¶
Load a JPEG file, and parse it into it's JFIF segments. You can then read the existing EXIF data, or alter it. Note that if you modify the EXIF data, then reading that same data back from this data structure will not reflect your changes. You changes will only be reflected if you call Save(), and then reload that file using LoadJpegExif again.
func (*ExifData) GetOrientation ¶
See https://www.impulseadventure.com/photo/exif-orientation.html 0th Row 0th Column 1 top left side 2 top right side 3 bottom right side 4 bottom left side 5 left side top 6 right side top 7 right side bottom 8 left side bottom
func (*ExifData) SetOrientation ¶
Set photo orientation (See GetOrientation for meaning of the codes)
type Flags ¶
const ( FlagAccurateDCT Flags = C.TJFLAG_ACCURATEDCT FlagBottomUp Flags = C.TJFLAG_BOTTOMUP FlagFastDCT Flags = C.TJFLAG_FASTDCT FlagFastUpsample Flags = C.TJFLAG_FASTUPSAMPLE FlagNoRealloc Flags = C.TJFLAG_NOREALLOC FlagProgressive Flags = C.TJFLAG_PROGRESSIVE FlagStopOnWarning Flags = C.TJFLAG_STOPONWARNING )
type Image ¶
type Image struct {
Pixels []byte
Width int
Height int
Stride int // Distance from one line to the next, in bytes
Format PixelFormat
Premultiplied bool
}
Image is the concrete image type that is used by all functions inside cimg
func Decompress ¶
Load an image into memory. JPEG: Uses TurboJPEG PNG: Uses Go's native PNG library TIFF: Uses golang.org/x/image/tiff The resulting image is RGB for JPEGs, or RGBA/Gray for PNG
func FromImage ¶
Convert a Go image.Image into a cimg.Image If allowDeepClone is true, and the source image is type GRAY, NRGBA, or RGBA, then the resulting Image points directly to the pixel buffer of the source image.
func NewImage ¶
func NewImage(width, height int, format PixelFormat) *Image
NewImage creates a new 8-bit image
func ResizeNew ¶
func ResizeNew(src *Image, dstWidth, dstHeight int, params *ResizeParams) *Image
ResizeNew allocates the output image for you and returns it Assumes sRGB image
func UnrotateExif ¶
UnrotateExif rewrites the bytes of an image so that the EXIF orientation information can be discarded. In other words, after running UnrotateExif, the encoded image orientation is the same as the natural display image orientation. exifOrientation must be either 3, 6, or 8.
func WrapImage ¶
func WrapImage(width, height int, format PixelFormat, pixels []byte) *Image
Wrap an array of bytes into an Image object (do not copy pixels)
func WrapImageStrided ¶
func WrapImageStrided(width, height int, format PixelFormat, pixels []byte, stride int) *Image
Wrap an array of bytes into an Image object, with controllable stride (do not copy pixels)
func (*Image) AvgColor ¶
AvgColor computes the average color of the entire image, per channel The averaging is performed in sRGB space (i.e. not linear light) If the image has more than 8 channels, then the function will panic
func (*Image) CopyImageRect ¶
CopyImageRect copies src into dst, at dstX1,dstY1. The source imagery is read from the rectangle specified by the 4 source location parameters. All coordinates are clipped prior to drawing. The only error condition is when the two images have a different number of channels. Note that you will get swapped RGB channels if you do something like copy from an RGB image into a BGR image (i.e. this function does not swizzle the channels, it just does a dumb memcpy of the rows).
func (*Image) DrawRectangle ¶ added in v2.1.4
Draw a rectangle.
func (*Image) IsDense ¶ added in v2.1.3
Returns true if the image is dense (i.e. the stride is equal to the width * number of channels)
func (*Image) Matte ¶
For an RGBA image, blend it on top of the given color, so that transparent regions of the image will be filled with the given color. If the image has no alpha channel, then this is a no-op.
func (*Image) Premultiply ¶
func (img *Image) Premultiply()
Premultiply RGB by A. If the image does not have an alpha channel, or if Premultiplied=true then this is a no-op.
func (*Image) ReferenceCrop ¶ added in v2.1.2
Return a crop of the image, where the crop points to the same underlying bytes
func (*Image) ToGray ¶ added in v2.1.1
ToGray returns a grayscale image. If the image is already a grayscale image, then a clone is returned
func (*Image) ToRGB ¶
ToRGB returns a 3 channel image. This is used to remove the alpha channel from an image that was loaded from a PNG, or to turn a gray image into an RGB image. If the image is already a 3 channel image, then a clone is returned
type PixelFormat ¶
const ( PixelFormatRGB PixelFormat = C.TJPF_RGB PixelFormatBGR PixelFormat = C.TJPF_BGR PixelFormatRGBX PixelFormat = C.TJPF_RGBX PixelFormatBGRX PixelFormat = C.TJPF_BGRX PixelFormatXBGR PixelFormat = C.TJPF_XBGR PixelFormatXRGB PixelFormat = C.TJPF_XRGB PixelFormatGRAY PixelFormat = C.TJPF_GRAY PixelFormatRGBA PixelFormat = C.TJPF_RGBA PixelFormatBGRA PixelFormat = C.TJPF_BGRA PixelFormatABGR PixelFormat = C.TJPF_ABGR PixelFormatARGB PixelFormat = C.TJPF_ARGB PixelFormatCMYK PixelFormat = C.TJPF_CMYK PixelFormatUNKNOWN PixelFormat = C.TJPF_UNKNOWN )
type ResizeEdge ¶ added in v2.0.8
type ResizeEdge int
const ( ResizeEdgeClamp ResizeEdge = C.STBIR_EDGE_CLAMP ResizeEdgeReflect ResizeEdge = C.STBIR_EDGE_REFLECT ResizeEdgeWrap ResizeEdge = C.STBIR_EDGE_WRAP // this edge mode is slower and uses more memory ResizeEdgeZero ResizeEdge = C.STBIR_EDGE_ZERO )
type ResizeFilter ¶ added in v2.0.8
type ResizeFilter int
const ( ResizeFilterDefault ResizeFilter = C.STBIR_FILTER_DEFAULT // use same filter type that easy-to-use API chooses ResizeFilterBox ResizeFilter = C.STBIR_FILTER_BOX // A trapezoid w/1-pixel wide ramps, same result as box for integer scale ratios ResizeFilterTriangle ResizeFilter = C.STBIR_FILTER_TRIANGLE // On upsampling, produces same results as bilinear texture filtering ResizeFilterCubicSpline ResizeFilter = C.STBIR_FILTER_CUBICBSPLINE // The cubic b-spline (aka Mitchell-Netrevalli with B=1,C=0), gaussian-esque ResizeFilterCatmullRom ResizeFilter = C.STBIR_FILTER_CATMULLROM // An interpolating cubic spline ResizeFilterMitchell ResizeFilter = C.STBIR_FILTER_MITCHELL // Mitchell-Netrevalli filter with B=1/3, C=1/3 ResizeFilterPointSample ResizeFilter = C.STBIR_FILTER_POINT_SAMPLE // Simple point sampling )
type ResizeParams ¶ added in v2.0.8
type ResizeParams struct {
Edge ResizeEdge // 0 = STBIR_EDGE_CLAMP, which is convenient
Filter ResizeFilter // 0 = STBIR_FILTER_DEFAULT, which is convenient
CheapSRGBFilter bool // If data is sRGB (for 8-bit it almost always is), then use cheap non-linear filtering directly in the sRGB space
}
type RotateFilter ¶ added in v2.1.1
type RotateFilter int
Rotation filter
const (
RotateFilterBilinear RotateFilter = iota // Bilinear filtering
)
type RotateParams ¶ added in v2.1.1
type RotateParams struct {
Filter RotateFilter
SnapThresholdRadians float64 // If rotation angle is close enough to -90, 90 or 180, then snap to discrete rotation
}
Rotation parameters
func NewRotateParams ¶ added in v2.1.3
func NewRotateParams() *RotateParams
Return default rotation parameters
type Sampling ¶
const ( Sampling444 Sampling = C.TJSAMP_444 Sampling422 Sampling = C.TJSAMP_422 Sampling420 Sampling = C.TJSAMP_420 SamplingGray Sampling = C.TJSAMP_GRAY )
Source Files