polygonise

README

polygonise

A library to convert images into a set of polygons based on a binary filter.

Installation

If you're familiar with Go, you should know how this works:

$ go get -u github.com/miltfra/polygonise

Now you can import it in your file header:

package main

import "github.com/miltfra/polygonise"

// ...

Use cases

Before we look at how you can use this, we need to figure out when you can use this. This package does not polygonise images to make them look fancy. Instead it allows you to generate polygons, that is ordered sets of points, from images.

I've only ever had one use case but there are others I can think of:

• generate unlimited input data for algorithms in 2D-terrain; as far as I know the package manages to avoid overlapping polygons
• convert 2D terrain into polygons; I don't see where you'd need this, but there's probably one person out there who's done exactly that... if you read this: Hello there.
• get objects from heatmaps (e.g. infra red images); this is probably the most useful case with a connection to the real world... yet, I think the first one is more likely

Basic Usage

A polygon is a slice of integers. In each slice there's an even number of integers because they are listed as x0, y0, x1, y1, ..., xn, yn.

The package's essential function, polygonise.Get, returns a slice of polygons ([][]int).

Let's say you want to read an arbitrary image and get the polygons of the areas that have an average color bigger than 100:

package main

import "github.com/miltfra/polygonise"

func main() {
    filter := polygonise.NewGreyFilter(100, false)
    img, err := polygonise.FromFile("path/to/image")
    if err != nil {
        panic(err)
    }
    polygons := polygonise.Get(img, filter, 10)
    // Do something with polygons ...
}

To remove corners of polygons that do not add to the shape because they form a straight line with their neighbours you can use polygonise.Flatten().

Filters

The entire package is based around the idea of filters. The interface looks as follows (see filters.go for further documentation):

type Filter interface {
	Filter(color.RGBA) bool
	FalseValue() color.RGBA
	TrueValue() color.RGBA
}

As you can see, a filter needs to be able to decide wether any RGBA color is true or false. Further, the algorithms depends on colors which are known to return true and false. If you want to create your own filter you only have to satisfy this interface.

To make things a bit easier there are 4 different default filter types implemented.

You can access them through NewGreyFilter, NewRedFilter, NewGreenFilter and NewBlueFilter.

Disclaimer

Do not expect to get the exact polygons you are seeing on screen, unless:

1. Your step size in polygonise.Get is 1,
2. you used polygonise.Flatten and
3. your polygon only has horizontal, vertical and 45 degree edges.

The algorithm might not see edges at another angle as true lines, because in most cases they aren't.

Further, a step size of more than 1 will improve performance and reduce the number of edges but it will increase inaccuracies. That means that instead of the real corners the algorithm might pick two other points on either side of the corner. That might make a rectangle into an octagon.

License

GPLv3 as in LICENSE.

Documentation

Index

• func ApplyFilter(img *image.RGBA, f Filter) *image.RGBA
• func Flatten(p []int) []int
• func FromFile(path string) (*image.RGBA, error)
• func Get(img *image.RGBA, f Filter, step int) [][]int
• func GetNext(img *image.RGBA, f Filter, step int) ([]int, *image.RGBA)
• func ToFile(path string, img *image.RGBA) error
• func ToRGBA(img image.Image) *image.RGBA
• type Filter
  • func NewBlueFilter(threshold uint8, inverted bool) (Filter, error)
  • func NewFilter(f func(color.RGBA) bool, trueValue, falseValue color.RGBA) Filter
  • func NewGreenFilter(threshold uint8, inverted bool) (Filter, error)
  • func NewGreyFilter(threshold uint8, inverted bool) (Filter, error)
  • func NewRedFilter(threshold uint8, inverted bool) (Filter, error)

Functions

func ApplyFilter

func ApplyFilter(img *image.RGBA, f Filter) *image.RGBA

ApplyFilter returns a new image object where every pixel is replaced either with the filters true value or it's false value depending on the original pixels value.

func Flatten

func Flatten(p []int) []int

Flatten removes every corner from a given polygon that is exactly on the line of the two adjacent corners.

func FromFile

func FromFile(path string) (*image.RGBA, error)

FromFile is a function for the users convenience. It reads either a jpeg or a png file and returns an image.RGBA object which can then be used with this libarary.

func Get

func Get(img *image.RGBA, f Filter, step int) [][]int

Get returns all the polygons that are available based on the given filter and the given step size.

Note: A higher step size reduces the count of corners per polygon but increases the chance that the resulting polygons overlap.

func GetNext

func GetNext(img *image.RGBA, f Filter, step int) ([]int, *image.RGBA)

GetNext returns the next polygon in this image and another image with the pixels of this polygon removed. The return value is nil iff there are no true pixels for this filter in this image.

func ToFile

func ToFile(path string, img *image.RGBA) error

ToFile inverts the FromFile function. That is, it saves a given image.RGBA object to the disk into a given path.

func ToRGBA

func ToRGBA(img image.Image) *image.RGBA

ToRGBA converts an arbitrary image.Image object to image.RGBA.

Types

type Filter

type Filter interface {
	Filter(color.RGBA) bool
	FalseValue() color.RGBA
	TrueValue() color.RGBA
}

A Filter is any type that has a Filter function to return wether a certain color is part of a polygon or not

func NewBlueFilter

func NewBlueFilter(threshold uint8, inverted bool) (Filter, error)

NewBlueFilter returns a new filter object that accepts any color with a higher grey value than given. If inverted is true it accepts any color with a grey value less than the given one.

func NewFilter

func NewFilter(f func(color.RGBA) bool, trueValue, falseValue color.RGBA) Filter

NewFilter returns a new filter object from a given function.

func NewGreenFilter

func NewGreenFilter(threshold uint8, inverted bool) (Filter, error)

NewGreenFilter returns a new filter object that accepts any color with a higher grey value than given. If inverted is true it accepts any color with a grey value less than the given one.

func NewGreyFilter

func NewGreyFilter(threshold uint8, inverted bool) (Filter, error)

NewGreyFilter returns a new filter object that accepts any color with a higher grey value than given. If inverted is true it accepts any color with a grey value less than the given one.

func NewRedFilter

func NewRedFilter(threshold uint8, inverted bool) (Filter, error)

NewRedFilter returns a new filter object that accepts any color with a higher grey value than given. If inverted is true it accepts any color with a grey value less than the given one.