Fast image IO and transformations.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src/Vision
test
.gitignore
LICENSE
README.md
Setup.hs
bench_results.png
changelog
friday.cabal
header.png

README.md

friday is an image processing framework for Haskell. It has been designed to build fast, generic and type-safe image processing algorithms.

friday also provide some simple computer vision features such as edge detection or histogram processing.

Except for I/Os, friday is entirely written in Haskell.

Header

Features

The four distinguishing features of this image library are:

  • A reliance on a strongly typed programming language to detect programming errors directly at compile time.
  • The ability to fuse image transformations. For example, if one wishes to apply a rotation on a resized image, he can use friday and the Haskell compiler to generate a single loop that will automatically combine the resizing and the rotating operations into a single algorithm, removing the need to store the intermediate resized image.
  • The ability to automatically parallelize algorithms to use multiple processors. The library is able to parallelize upon request image transformations, even these which have been generated by the fusion mechanism.
  • Being extremely generic. One who wants to create new algorithms, new pixel color-spaces or new ways to store an image will be able to reuse the advanced type checking features and both the fusion and automatic parallelization mechanisms.

The library is more like a set of building blocks to write image processing algorithms in a functional programming style than a collection of image processing algorithms.

The library currently supports four color-spaces: RGB, RGBA, HSV and gray-scale images. Images can be converted between these color-spaces.

At this moment, the following features and algorithms have been implemented:

  • various image transformations: resizing, cropping, vertical and horizontal flop/flipping and flood fill ;

  • filters: morphological transformations (dilation and erosion), blurring (mean and Gaussian blurs) and derivative computation (Sobel and Scharr operators) ;

  • support for mutable and masked images ;

  • non-adaptive, adaptive, Otsu and SCW thresholding methods ;

  • edge detection using Canny's algorithm ;

  • color histograms (including comparisons and image equalization).

Quick tour

Modules

The library is divided in three main modules: Vision.Primitive, Vision.Image and Vision.Histogram.

You can directly import sub-modules (such as Vision.Image.Transform), but the backward-compatibility is not enforced. That is, some functions could be moved to another sub-module in a newer backward-compatible advertised version.

Vision.Primitive

Vision.Primitive contains types used all over the library, such as Shape which is used to define shapes and indices in images and histograms.

The module is usually imported unqualified:

import Vision.Primitive

Vision.Image

Vision.Image contains functions and types to manage and transform images.

The module can be imported unqualified but it's often better use a qualified import as some function names (such as map) can conflict with Prelude and Vision.Histogram:

import Vision.Image
-- or
import qualified Vision.Image as I

Vision.Histogram

Vision.Histogram contains functions and types to create and compare histograms.

The module can be imported unqualified but it's often better use a qualified import as some function names (such as map) can conflict with Prelude and Vision.Image:

import Vision.Histogram
-- or
import qualified Vision.Histogram as H

The Image type-class

Images implement the Image type-class.

This type-class give you, among other things, the index and the shape methods to look up for pixel values and to get the image size.

Manifest and Delayed images

To benefit from Haskell's purity, non-mutable images are represented in two ways:

  • the Manifest representation stores images in Haskell Vectors. Grey, HSV, RGB and RGBA are manifest images ;

  • the Delayed representation uses a function to produce image pixels. These images can be efficiently chained to produce complex transformations. With some inlining, Haskell compilers are able to produce fast algorithms by removing intermediate structures when working with delayed images. GreyDelayed, HSVDelayed, RGBDelayed and RGBADelayed are delayed images.

The convert method from the convertible package can be used to convert images between color-spaces and representations.

As most functions work with both representations and all color-spaces, you need to help the type checker to choose the correct return type.

For example, if you want to convert an RGBA image to a greyscale image, use a type annotation to inform the compiler the image type you want to get:

toGrey :: RGBA -> Grey
toGrey = convert

When you only need to force the returned representation of a function, you can use the delayed and manifest functions. These functions don't do anything except enforcing types.

makeMiniature = delayed . resize Bilinear (ix2 150 150)

See this file for an example of a pipeline of delayed images.

Masked images

Some images are not defined for each of their pixels. These are called masked images and implement the MaskedImage type-class.

The MaskedImage type-class primarily gives you a maskedIndex method which differs from index by its type :

index       :: Image i       => i -> Point -> ImagePixel i
maskedIndex :: MaskedImage i => i -> Point -> Maybe (ImagePixel i)

Unlike index, maskedIndex doesn't always return a value. For convenience, every Image instance is also a MaskedImage instance.

DelayedMask can be used to create a masked image.

Create images from functions

Images are instance of the FromFunction type-class. This class provide a method to create images from a function.

For example, if you want to create a black and white image from another image, you could write:

toBlackAndWhite :: (Image i, Convertible i Grey) => i -> Grey
toBlackAndWhite img =
    let grey = convert img :: Grey
    in fromFunction (shape img) $ \pt ->
            if grey `index` pt > 127 then 255
                                     else 0

However, most of the time, you will prefer to use the map function instead:

toBlackAndWhite :: (Image i, Convertible i Grey) => i -> Grey
toBlackAndWhite img =
    let grey = convert img :: Grey
    in map (\pix -> if pix > 127 then 255 else 0) grey

Load and save images from and to files

For modularity, storage operations are provided by separate packages.

The friday-devil package provides FFI calls to the DevIL image library. The library is written in C and supports a wide variety of image formats, including BMP, JPG, PNG, GIF, ICO and PSD.

The popular JuicyPixels package is a native Haskell library for decoding many image types. Efficient, zero copy, conversion between JuicyPixels and Friday Haskell types is provided by friday-juicypixels.

Examples

See the friday-examples package for a set of examples.

Benchmarks

The library has been sightly optimized and could be moderately used for real-time applications.

The following graph shows how the library compares to two other image processing libraries written in C. The fastest implementation for each algorithm is taken as reference:

Benchmark results

The main reason that performances are currently below OpenCV is that OpenCV relies heavily on SIMD instructions.