hip-1.0.1: Haskell Image Processing (HIP) Library.

Copyright(c) Alexey Kuleshevich 2016
LicenseBSD3
MaintainerAlexey Kuleshevich <lehins@yandex.ru>
Stabilityexperimental
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell2010

Graphics.Image.IO

Contents

Description

 

Synopsis

Reading

readImage :: Readable (Image arr cs Double) InputFormat => FilePath -> IO (Either String (Image arr cs Double)) Source

This function will try to guess an image format from file's extension, then it will attempt to read it as such. It will fall back onto the rest of the supported formats and will try to read them regarless of file's extension. Whenever image cannot be decoded, Left containing all errors for each attempted format will be returned, and Right containing an image otherwise. Image will be read into a type signature specified ColorSpace (Y, YA, RGB and RGBA only) with Double precision, while doing all necessary conversions.

readImageExact Source

Arguments

:: Readable img format 
=> format

A file format that an image should be read as. See Supported Image Formats

-> FilePath

Location of an image.

-> IO (Either String img) 

This function allows for reading any supported image in the exact colorspace and precision it is currently encoded in. For instance, frog image can be read into it's YCbCr colorspace with Word8 precision and into any supported array representation.

>>> readImageExact JPG "images/frog.jpg" :: IO (Either String (Image RP YCbCr Word8))
Right <Image RepaParallel YCbCr (Word8): 200x320>

The drawback here is that colorspace and precision has to match exactly, otherwise it will return an error:

>>> readImageExact JPG "images/frog.jpg" :: IO (Either String (Image RD RGB Word8))
Left "JuicyPixel decoding error: Input image is in YCbCr8 (Pixel YCbCr Word8), cannot convert it to RGB8 (Pixel RGB Word8) colorspace."

Attempt to read an image in a particular color space that is not supported by the format, will result in a compile error. Refer to Readable class for all images that can be decoded.

Writing

writeImage Source

Arguments

:: (ManifestArray arr cs Double, Writable (Image arr cs Double) OutputFormat) 
=> FilePath

Location where an image should be written.

-> Image arr cs Double

An image to write.

-> IO () 

Just like readImage, this function will guess an output file format from the extension and write to file any image that is in one of Y, YA, RGB or RGBA ColorSpaces with Double precision. While doing necessary conversions the choice will be given to the most suited color space supported by the format, for instance, in case of a PNG format, an (Image arr RGBA Double) would be written as RGBA16, hence preserving transparency and using highest supported precision Word16. At the same time, writing that image in GIF format would save it in RGB8, since Word8 is the highest precision GIF supports and it currently cannot be saved with transparency.

writeImageExact Source

Arguments

:: Writable img format 
=> format

A file format that an image should be saved in. See Supported Image Formats

-> [SaveOption format]

A list of format specific options.

-> FilePath

Location where an image should be written.

-> img

An image to write. Can be a list of images in case of formats supporting animation.

-> IO () 

Write an image in a specific format, while supplying any format specific options. Precision and color space that an image will be written is decided from image's type. Attempt to write image file in a format that does not support color space and precision combination will result in a compile error.

Displaying

displayImage Source

Arguments

:: (ManifestArray arr cs e, Writable (Image arr cs e) TIF) 
=> Image arr cs e

Image to be displayed

-> IO (Maybe ThreadId) 

Makes a call to the current display program, which can be changed using setDisplayProgram. An image is written as a .tiff file into an operating system's temporary directory and passed as an argument to the display program. If a blocking flag was set to False using setDisplayProgram, then function will return immediately with (Just ThreadId), otherwise it will block current thread until external program is terminated, in which case Nothing is returned. Temporary file is deleted, after a program displaying an image is closed.

>>> frog <- readImageRGB "images/frog.jpg"
>>> displayImage frog
Just ThreadId 505
>>> setDisplayProgram ("gimp", True)
>>> displayImage frog -- will only return after gimp is closed.
Nothing

setDisplayProgram :: (String, Bool) -> IO () Source

Sets the program to be use when displaying an image, where Bool specifies if current thread should block until the program is closed when calling displayImage function. GPicView ("gpicview", False) is set as a default program with a nonblocking flag. Here are some examples:

>>> setDisplayProgram ("gpicview", True) -- use gpicview and block current thread.
>>> setDisplayProgram ("gimp", False) -- use gimp and don't block current thread.
>>> setDisplayProgram ("xv", False)
>>> setDisplayProgram ("display", False)

Supported Image Formats

Encoding and decoding of images is done using JuicyPixels and netpbm packages.

List of image formats that are currently supported, and their exact ColorSpaces and precision for reading and writing: