caire

README

Caire

Caire is a content aware image resize library based on Seam Carving for Content-Aware Image Resizing paper.

How does it work

• An energy map (edge detection) is generated from the provided image.
• The algorithm tries to find the least important parts of the image taking into account the lowest energy values.
• Using a dynamic programming approach the algorithm will generate individual seams accrossing the image from top to down, or from left to right (depending on the horizontal or vertical resizing) and will allocate for each seam a custom value, the least important pixels having the lowest energy cost and the most important ones having the highest cost.
• Traverse the image from the second row to the last row and compute the cumulative minimum energy for all possible connected seams for each entry.
• The minimum energy level is calculated by summing up the current pixel with the lowest value of the neighboring pixels from the previous row.
• Traverse the image from top to bottom and compute the minimum energy level. For each pixel in a row we compute the energy of the current pixel plus the energy of one of the three possible pixels above it.
• Find the lowest cost seam from the energy matrix starting from the last row and remove it.
• Repeat the process.

The process illustrated:

Original image	Energy map	Seams applied

Features

Key features which differentiates from the other existing open source solutions:

• Customizable command line support
• Support for both shrinking or enlarging the image
• Resize image both vertically and horizontally
• Can resize all the images from a directory
• Does not require any third party library
• Use of sobel threshold for fine tuning
• Use of blur filter for increased edge detection

To Do

• Face detection

Install

First, install Go, set your GOPATH, and make sure $GOPATH/bin is on your PATH.

$ export GOPATH="$HOME/go"
$ export PATH="$PATH:$GOPATH/bin"

Next download the project and build the binary file.

$ go get github.com/esimov/caire/cmd/caire
$ go install

Usage

$ caire -in input.jpg -out output.jpg

Supported commands:

$ caire --help

The following flags are supported:

Flag	Default	Description
in	n/a	Input file
out	n/a	Output file
width	n/a	New width
height	n/a	New height
perc	false	Reduce image by percentage
blur	1	Blur radius
sobel	10	Sobel filter threshold
debug	false	Use debugger

In case you wish to reduce the image size by a specific percentage, it can be used the -perc boolean flag, which means the image will be reduced to the width and height expressed as percentage. Here is a sample command using -perc:

caire -in input/source.jpg -out ./out.jpg -perc=1 -width 20 -height 20 -debug=false

which reduces the image width and height by 20%.

The CLI command can process all the images from a specific directory too.

$ caire -in ./input-directory -out ./output-directory

Sample images

Shrunk images

Original	Shrunk

Enlarged images

Original	Extended

Useful resources

• https://en.wikipedia.org/wiki/Seam_carving
• https://inst.eecs.berkeley.edu/~cs194-26/fa16/hw/proj4-seamcarving/imret.pdf
• http://pages.cs.wisc.edu/~moayad/cs766/download_files/alnammi_cs_766_final_report.pdf
• https://stacks.stanford.edu/file/druid:my512gb2187/Zargham_Nassirpour_Content_aware_image_resizing.pdf

License

This project is under the MIT License. See the LICENSE file for the full license text.

Documentation

Index

• func Grayscale(src *image.NRGBA) *image.NRGBA
• func Resize(s SeamCarver, img *image.NRGBA) (image.Image, error)
• func SobelFilter(img *image.NRGBA, threshold float64) *image.NRGBA
• func Stackblur(img *image.NRGBA, width, height, radius uint32) *image.NRGBA
• type ActiveSeam
• type Carver
  • func NewCarver(width, height int) *Carver
  • func (c *Carver) AddSeam(img *image.NRGBA, seams []Seam, debug bool) *image.NRGBA
  • func (c *Carver) ComputeSeams(img *image.NRGBA, p *Processor) []float64
  • func (c *Carver) FindLowestEnergySeams() []Seam
  • func (c *Carver) RemoveSeam(img *image.NRGBA, seams []Seam, debug bool) *image.NRGBA
  • func (c *Carver) RotateImage270(src *image.NRGBA) *image.NRGBA
  • func (c *Carver) RotateImage90(src *image.NRGBA) *image.NRGBA
• type Processor
  • func (p *Processor) Process(r io.Reader, w io.Writer) error
  • func (p *Processor) Resize(img *image.NRGBA) (image.Image, error)
• type Seam
• type SeamCarver
• type UsedSeams

Functions

func Grayscale

func Grayscale(src *image.NRGBA) *image.NRGBA

Convert image to grayscale.

func Resize

func Resize(s SeamCarver, img *image.NRGBA) (image.Image, error)

Implement the Resize method of the Carver interface.

func SobelFilter

func SobelFilter(img *image.NRGBA, threshold float64) *image.NRGBA

Detect image edges. See https://en.wikipedia.org/wiki/Sobel_operator

func Stackblur

func Stackblur(img *image.NRGBA, width, height, radius uint32) *image.NRGBA

Types

type ActiveSeam

type ActiveSeam struct {
	Seam
	Pix color.Color
}

Struct containing the current seam color and position.

type Carver

type Carver struct {
	Width  int
	Height int
	Points []float64
}

func NewCarver

func NewCarver(width, height int) *Carver

NewCarver returns an initialized Carver structure.

func (*Carver) AddSeam

func (c *Carver) AddSeam(img *image.NRGBA, seams []Seam, debug bool) *image.NRGBA

Add new seam.

func (*Carver) ComputeSeams

func (c *Carver) ComputeSeams(img *image.NRGBA, p *Processor) []float64

Compute the minimum energy level based on the following logic:

• traverse the image from the second row to the last row and compute the cumulative minimum energy M for all possible connected seams for each entry (i, j).

• the minimum energy level is calculated by summing up the current pixel value with the minimum pixel value of the neighboring pixels from the previous row.

func (*Carver) FindLowestEnergySeams

func (c *Carver) FindLowestEnergySeams() []Seam

Find the lowest vertical energy seam.

func (*Carver) RemoveSeam

func (c *Carver) RemoveSeam(img *image.NRGBA, seams []Seam, debug bool) *image.NRGBA

Remove the least important columns based on the stored energy seams level.

func (*Carver) RotateImage270

func (c *Carver) RotateImage270(src *image.NRGBA) *image.NRGBA

Rotate image by 270 degree counter clockwise

func (*Carver) RotateImage90

func (c *Carver) RotateImage90(src *image.NRGBA) *image.NRGBA

Rotate image by 90 degree counter clockwise

type Processor

type Processor struct {
	SobelThreshold int
	BlurRadius     int
	NewWidth       int
	NewHeight      int
	Percentage     bool
	Debug          bool
}

Processor options

func (*Processor) Process

func (p *Processor) Process(r io.Reader, w io.Writer) error

Process image.

func (*Processor) Resize

func (p *Processor) Resize(img *image.NRGBA) (image.Image, error)

This is the main entry point which takes the source image and encodes the new, rescaled image into the output file.

type Seam

type Seam struct {
	X int
	Y int
}

Seam struct containing the pixel coordinate values.

type SeamCarver

type SeamCarver interface {
	Resize(*image.NRGBA) (image.Image, error)
}

SeamCarver is an interface that Carver uses to implement the Resize function. It takes an image and the output as parameters and returns the resized image.

type UsedSeams

type UsedSeams struct {
	ActiveSeam []ActiveSeam
}

Struct containing the generated seams.