friday- A functional image processing library for Haskell.

Safe HaskellNone




Contour tracing of binary images (zero ~ background, nonzero ~ object).


A binary image is an image in which the pixel is boolean (represented here using Grey and zero or non-zero pixel values).

All zero-value pixels are part of the "background".

An object is an connected group of non-zero pixels.

A Contour is a trace of an objects' outer or inner edges. Some objects are solid, having no inner contours (consider a filled circle, or letters such as h, s, k and l). Other objects have "holes", also known as inner contours. The letters a and e have one hole while the letter B has two.

After obtaining a Contours structure (via the contours function) the raw traces (Contour type) can be used for further processing or the contours can be filtered by aspects of interest and selectively re-drawn (drawContour) , perhaps used to mask the original image.

About Holes:

In cases where there is only one hole it is uniquely recorded in the Contours structure. Objects with more than one hole record all inner contours in one vector making them hard to extract separately - this is due to the main data structure not being rich enough to record the holes separately. As of writing, this is not seen as an issue because the desired operation, drawContour, can still be achieved. Changing this behavior should be trivial if desired.


To use this library it is advised that you preprocess the image, including thresholding (ex: otsu on a grey scale image), to obtain a binary image then call:

cs = contours img

The Contours structure can be accessed directly if desired. It includes an Map of all contours (numbered counting from 1) and a vector of the contour sizes (indexed by contour number, zero index is unused/zero).

The algorithm implemented in this module follows the design laid out in 'A Linear-Time Component-Labeling Algorithm Using Contour Tracing Technique' [1].



Main Interface

data Contours Source #

Contours of an image include: * A map from contour number to outer points and negative contour number of inner contour points. * A vector of sizes for each contour for domain [1..size contourOutlines] (the zero index is meaningless)

type OneContour = Vector ContourValue Source #

A contour is described by the points on the perimeter and a boolean indicating if that point is "terminal" (next pixel to the right is background iff the point is terminal). The terminal information allows for a slightly simpler drawContour implementation.

type RowContour = Vector (Point, Point) Source #

RowContour is a method of expressing contours by, for each row, recording the start of an object and the end (due to reaching the other side or a hole/inner contour) for each row.

contours :: (Image src, Num (ImagePixel src), Eq (ImagePixel src)) => src -> Contours Source #

The meat of this module is the contours function, which extracts the contours (outer and inner outlines) of a binary image. Zero-valued pixels are the background and non-zero are active/objects to trace. The output, Contours, contains enough information to determine the number of contours, their traces, the size in pixels (filled size and perimeter), number of holes, etc.

ADT style interface (hides Contours internals)

rowContour :: [ContourValue] -> RowContour Source #

Given a vector including outer (and optionally inner) contour points, make 'row contour' from which is easier to transform back into a binary image. By not including the inner contour points the row will be filled, making traces of objects with holes appear solid.

Reconstructing Image Elements

data ContourDrawStyle Source #

Outline: Just draw the edge.

OuterOutline: Outline the outer contours only, no hole contours AllOutlines: Draw all contours Fill: Draw the object but fill it in, ignoring holes. FillWithHoles: Draw the object and do not fill in the holes.


Bounded ContourDrawStyle Source # 
Enum ContourDrawStyle Source # 
Eq ContourDrawStyle Source # 
Ord ContourDrawStyle Source # 
Read ContourDrawStyle Source # 
Show ContourDrawStyle Source # 

drawContour :: Contours -> Size -> ContourDrawStyle -> ContourId -> Grey Source #

Draws a given contour. The size specified must be large enough to include the coordinate originally occupied by the contour being drawn, no cropping or other transformation is done.

drawContours :: Contours -> Size -> ContourDrawStyle -> [ContourId] -> Grey Source #

Draws many contours. See drawContour.