brille

README

Brille Image Processing

Brille is an image processing module for Golang

Works with JPEG and PNG images

It does not have any dependencies, only standard Golang libraries are being used

Demo: https://images.dyum.in

Installation

Minimal required Golang version: v1.18

go get github.com/julyskies/brille/v2@latest

Versioning

Brille v2.0.X have a number of breaking changes compared to v1.0.X:

• some of the filtering functions were removed
• some of the filtering functions were renamed
• some of the constants were renamed

Check Available filters section for more information regarding these changes.

Usage

All of the Brille filter functions return 3 values:

• processed file as io.Reader
• file format as string
• processing error

Basic example:

package main

import (
	"io"
	"log"
	"os"

	"github.com/julyskies/brille"
)

func main() {
	file, fileError := os.Open("/path/to/file.jpeg")
	if fileError != nil {
		log.Fatal(fileError)
	}
	defer file.Close()

	sobel, format, processingError := brille.Sobel(file)
	if processingError != nil {
		log.Fatal(processingError)
	}

	outputFile, outputError := os.Create("sobel." + format)
	if outputError != nil {
		log.Fatal(outputError)
	}
	defer outputFile.Close()

	_, copyError := io.Copy(outputFile, sobel)
	if copyError != nil {
		log.Fatal(copyError)
	}
	
	log.Println("processed " + format)
}

Using with Fiber:

package apis

import (
	"strings"

	"github.com/gofiber/fiber/v2"
	"github.com/julyskies/brille"
)

func controller(context *fiber.Ctx) error {
	file, fileError := context.FormFile("image")
	if fileError != nil {
		return fiber.NewError(fiber.StatusInternalServerError)
	}

	partials := strings.Split(file.Filename, ".")
	extension := partials[len(partials)-1]
	if extension == "" {
		return fiber.NewError(fiber.StatusBadRequest)
	}

	fileHandle, readerError := file.Open()
	if readerError != nil {
		return fiber.NewError(fiber.StatusInternalServerError)
	}

	result, format, processingError := brille.Grayscale(
		fileHandle,
		brille.GRAYSCALE_TYPE_LUMINANCE,
	)
	if processingError != nil {
		return fiber.NewError(fiber.StatusInternalServerError)
	}

	context.Set("Content-Type", "image/"+format)
	return context.SendStream(result)
}

Full Fiber example is available at https://github.com/peterdee/filtering-backend

Available filters

• Binary: converts an image to 1-bit black and white. Requires a threshold value (uint8, 0 to 255):

  binary, format, processingError := brille.Binary(file, 155)
  

• Box blur: blurs the image. Requires blur radius to be provided (uint, any value):

  blurred, format, processingError := brille.BoxBlur(file, 7)
  

• Brightness: adjusts image bightness. Requires brightness amount to be provided (int, -255 to 255):

  brightened, format, processingError := brille.Brightness(file, 75)
  

• Color inversion: inverts image colors:

  inverted, format, processingError := brille.ColorInversion(file)
  

• Contrast: adjusts image contrast. Requires contrast amount to be provided (int, -255 to 255):

  contrast, format, processingError := brille.Contrast(file, -45)
  

• Eight colors: this filter leaves only eight colors present on the image (red, green, blue, yellow, cyan, magenta, white, black):

  eightColors, format, processingError := brille.EightColors(file)
  

• Emboss: a static edge detection filter that uses a 3x3 kernel. It can be used to outline edges on an image:

  embossed, format, processingError := brille.Emboss(file)
  

• Flip: flips image horizontally or vertically. This filter requires a second argument - flip direction. Flip directions are available as brille module constants (FLIP_DIRECTION_HORIZONTAL is a horizontal mirroring and FLIP_DIRECTION_VERTICAL is vertical mirroring):

  flipped, format, processingError := brille.Flip(
    file,
    brille.FLIP_DIRECTION_HORIZONTAL,
  )
  

• Gamma correction: corrects image gamma. Requires correction amount to be provided (float64, 0 to 3.99). By default image gamma equals to 1, so providing a value less than that makes colors more intense, and larger values decrease color intensity:

  corrected, format, processingError := brille.GammaCorrection(file, 2.05)
  

• Grayscale: turns colors into shades of gray. This filter requires a second argument - grayscale type. Grayscale types are available as brille module constants (GRAYSCALE_TYPE_AVERAGE and GRAYSCALE_TYPE_LUMINANCE):

  grayscale, format, processingError := brille.Grayscale(
    file,
    brille.GRAYSCALE_TYPE_LUMINANCE,
  )
  

• Hue rotation: rotates image hue. Requires an angle to be provided (int, any value):

  rotated, format, processingError := brille.HueRotate(file, 278)
  

• Kuwahara: an edge detection filter with dynamic radius. Requires radius to be provided (uint, any value). This filter is pretty slow, and will probably be optimized in the future:

  kuwahara, format, processingError := brille.Kuwahara(file, 5)
  

• Laplacian: a static edge detection filter that uses a 3x3 kernel. It can be used to outline edges on an image:

  laplacian, format, processingError := brille.Laplacian(file)
  

• Rotate image (fixed angles): rotates an image clockwise (90, 180 or 270 degrees). This filter requires a second argument - rotation angle. Rotation angles are available as brille module constants (ROTATE_FIXED_90, ROTATE_FIXED_180 and ROTATE_FIXED_270):

  rotated270deg, format, processingError := brille.RotateFixed(
    file,
    brille.ROTATE_FIXED_270,
  )
  

• Sepia: sepia color filter.

  sepia, format, processingError := brille.Sepia(file)
  

• Sharpen: sharpens provided image. Requires an amount to be provided (uint, 0 to 100):

  sharpen, format, processingError := brille.Sharpen(file, 50)
  

• Sobel: a static edge detection filter that uses a 3x3 kernel. It can be used to outline edges on an image:

  sobel, format, processingError := brille.Sobel(file)
  

• Solarize: solarization affects image colors, partially inversing the colors. Requires a threshold to be provided (uint8, 0 to 255):

  solarized, format, processingError := brille.Solarize(file, 99)
  

Environment variables

• BRILLE_JPEG_QUALITY (int) - controls output quality for JPEG images, should be a number from 0 (low quality) to 100 (highest quality). Highest quality is used by default.

License

MIT

Documentation

Index

• Constants
• func Binary(file io.Reader, threshold uint8) (io.Reader, string, error)
• func BoxBlur(file io.Reader, radius uint) (io.Reader, string, error)
• func Brightness(file io.Reader, amount int) (io.Reader, string, error)
• func ColorInversion(file io.Reader) (io.Reader, string, error)
• func Contrast(file io.Reader, amount int) (io.Reader, string, error)
• func EightColors(file io.Reader) (io.Reader, string, error)
• func Emboss(file io.Reader) (io.Reader, string, error)
• func Flip(file io.Reader, direction string) (io.Reader, string, error)
• func GammaCorrection(file io.Reader, amount float64) (io.Reader, string, error)
• func Grayscale(file io.Reader, grayscaleType string) (io.Reader, string, error)
• func HueRotate(file io.Reader, angle int) (io.Reader, string, error)
• func Kuwahara(file io.Reader, radius uint) (io.Reader, string, error)
• func Laplacian(file io.Reader) (io.Reader, string, error)
• func RotateFixed(file io.Reader, angle uint) (io.Reader, string, error)
• func Sepia(file io.Reader) (io.Reader, string, error)
• func Sharpen(file io.Reader, amount uint) (io.Reader, string, error)
• func Sobel(file io.Reader) (io.Reader, string, error)
• func Solarize(file io.Reader, threshold uint8) (io.Reader, string, error)

Constants

const FLIP_DIRECTION_HORIZONTAL string = constants.FLIP_DIRECTION_HORIZONTAL

const FLIP_DIRECTION_VERTICAL string = constants.FLIP_DIRECTION_VERTICAL

const GRAYSCALE_TYPE_AVERAGE string = constants.GRAYSCALE_TYPE_AVERAGE

const GRAYSCALE_TYPE_LUMINANCE string = constants.GRAYSCALE_TYPE_LUMINANCE

const ROTATE_FIXED_180 uint = constants.ROTATE_FIXED_180

const ROTATE_FIXED_270 uint = constants.ROTATE_FIXED_270

const ROTATE_FIXED_90 uint = constants.ROTATE_FIXED_90

Functions

func Binary

func Binary(file io.Reader, threshold uint8) (io.Reader, string, error)

threshold: 0 to 255

func BoxBlur

func BoxBlur(file io.Reader, radius uint) (io.Reader, string, error)

radius: any uint

func Brightness

func Brightness(file io.Reader, amount int) (io.Reader, string, error)

amount: -255 to 255

func ColorInversion

func ColorInversion(file io.Reader) (io.Reader, string, error)

func Contrast

func Contrast(file io.Reader, amount int) (io.Reader, string, error)

amount: -255 to 255

func EightColors

func EightColors(file io.Reader) (io.Reader, string, error)

func Emboss

func Emboss(file io.Reader) (io.Reader, string, error)

func Flip

func Flip(file io.Reader, direction string) (io.Reader, string, error)

direction: horizontal or vertical

func GammaCorrection

func GammaCorrection(file io.Reader, amount float64) (io.Reader, string, error)

amount: 0 to 3.99

func Grayscale

func Grayscale(file io.Reader, grayscaleType string) (io.Reader, string, error)

grayscale type: average or luminance

func HueRotate

func HueRotate(file io.Reader, angle int) (io.Reader, string, error)

angle: any int

func Kuwahara

func Kuwahara(file io.Reader, radius uint) (io.Reader, string, error)

radius: 0 to 40

func Laplacian

func Laplacian(file io.Reader) (io.Reader, string, error)

func RotateFixed

func RotateFixed(file io.Reader, angle uint) (io.Reader, string, error)

angle: 90, 180 or 270 (use provided constants)

func Sepia

func Sepia(file io.Reader) (io.Reader, string, error)

func Sharpen

func Sharpen(file io.Reader, amount uint) (io.Reader, string, error)

amount: 0 to 100

func Sobel

func Sobel(file io.Reader) (io.Reader, string, error)

func Solarize

func Solarize(file io.Reader, threshold uint8) (io.Reader, string, error)

threshold: any uint8