JuicyPixels-2.0: Picture loading/serialization (in png, jpeg, bitmap and gif)

Safe HaskellNone

Codec.Picture

Contents

Description

Main module exporting import/export functions into various image formats.

To use the library without thinking about it, look after decodeImage and readImage.

Generally, the read* functions read the images from a file and try to decode it, and the decode* functions try to decode a bytestring.

For an easy image writing use the saveBmpImage, saveJpgImage & savePngImage functions

Synopsis

Generic functions

readImage :: FilePath -> IO (Either String DynamicImage)Source

Load an image file without even thinking about it, it does everything as decodeImage

decodeImage :: ByteString -> Either String DynamicImageSource

If you want to decode an image in a bytestring without even thinking in term of format or whatever, this is the function to use. It will try to decode in each known format and if one decoding succeed will return the decoded image in it's own colorspace

pixelMap :: forall a b. (Pixel a, Pixel b) => (a -> b) -> Image a -> Image bSource

map equivalent for an image, working at the pixel level. Little example : a brightness function for an rgb image

 brightnessRGB8 :: Int -> Image PixelRGB8 -> Image PixelRGB8
 brightnessRGB8 add = pixelMap brightFunction
      where up v = fromIntegral (fromIntegral v + add)
            brightFunction (PixelRGB8 r g b) =
                    PixelRGB8 (up r) (up g) (up b)

generateImageSource

Arguments

:: forall a . Pixel a 
=> (Int -> Int -> a)

Generating function, with x and y params.

-> Int

Width in pixels

-> Int

Height in pixels

-> Image a 

Create an image given a function to generate pixels. The function will receive value from 0 to width-1 for the x parameter and 0 to height-1 for the y parameter. The coordinate 0,0 is the upper left corner of the image, and (width-1, height-1) the lower right corner.

for example, to create a small gradient image :

 imageCreator :: String -> Image PixelRGB8
 imageCreator path = writePng path $ generateImage pixelRenderer 250 300
    where pixelRenderer x y = PixelRGB8 x y 128

generateFoldImageSource

Arguments

:: forall a acc . Pixel a 
=> (acc -> Int -> Int -> (acc, a))

Function taking the state, x and y

-> acc

Initial state

-> Int

Width in pixels

-> Int

Height in pixels

-> (acc, Image a) 

This function implement the same algorithm as generateImage, and let use an user-defined state

Generic image writing

saveBmpImage :: String -> DynamicImage -> IO ()Source

Save an image to a '.bmp' file, will do everything it can to save an image.

saveJpgImage :: Int -> String -> DynamicImage -> IO ()Source

Save an image to a '.jpg' file, will do everything it can to save an image.

savePngImage :: String -> DynamicImage -> IO ()Source

Save an image to a '.png' file, will do everything it can to save an image. For example, a simple transcoder to png

 transcodeToPng :: FilePath -> FilePath -> IO ()
 transcodeToPng pathIn pathOut = do
    eitherImg <- decodeImage pathIn
    case eitherImg of
        Left _ -> return ()
        Right img -> savePngImage img

Specific image format functions

Bitmap handling

class BmpEncodable pixel Source

All the instance of this class can be written as a bitmap file using this library.

writeBitmap :: BmpEncodable pixel => FilePath -> Image pixel -> IO ()Source

Write an image in a file use the bitmap format.

encodeBitmap :: forall pixel. BmpEncodable pixel => Image pixel -> ByteStringSource

Encode an image into a bytestring in .bmp format ready to be written on disk.

readBitmap :: FilePath -> IO (Either String DynamicImage)Source

Try to load a .bmp file. The colorspace would be RGB or RGBA

decodeBitmap :: ByteString -> Either String DynamicImageSource

Try to decode a bitmap image. Right now this function can output the following pixel types :

  • PixelRGB8

encodeDynamicBitmap :: DynamicImage -> Either String ByteStringSource

Encode a dynamic image in bmp if possible, supported pixel type are :

  • RGB8
  • RGBA8
  • Y8

writeDynamicBitmap :: FilePath -> DynamicImage -> IO (Either String Bool)Source

Write a dynamic image in a .bmp image file if possible. The same restriction as encodeDynamicBitmap apply.

Gif handling

readGif :: FilePath -> IO (Either String DynamicImage)Source

Helper function trying to load a gif file from a file on disk.

readGifImages :: FilePath -> IO (Either String [Image PixelRGB8])Source

Helper function trying to load all the images of an animated gif file.

decodeGif :: ByteString -> Either String DynamicImageSource

Transform a raw gif image to an image, witout modifying the pixels. This function can output the following pixel types :

  • PixelRGB8

decodeGifImages :: ByteString -> Either String [Image PixelRGB8]Source

Transform a raw gif to a list of images, representing all the images of an animation.

Jpeg handling

readJpeg :: FilePath -> IO (Either String DynamicImage)Source

Try to load a jpeg file and decompress. The colorspace is still YCbCr if you want to perform computation on the luma part. You can convert it to RGB using colorSpaceConversion

decodeJpeg :: ByteString -> Either String DynamicImageSource

Try to decompress a jpeg file and decompress. The colorspace is still YCbCr if you want to perform computation on the luma part. You can convert it to RGB using colorSpaceConversion

This function can output the following pixel types :

  • PixelY8
  • PixelYCbCr8

encodeJpeg :: Image PixelYCbCr8 -> ByteStringSource

Encode an image in jpeg at a reasonnable quality level. If you want better quality or reduced file size, you should use encodeJpegAtQuality

encodeJpegAtQualitySource

Arguments

:: Word8

Quality factor

-> Image PixelYCbCr8

Image to encode

-> ByteString

Encoded JPEG

Function to call to encode an image to jpeg. The quality factor should be between 0 and 100 (100 being the best quality).

Png handling

class PngSavable a whereSource

Encode an image into a png if possible.

Methods

encodePng :: Image a -> ByteStringSource

Transform an image into a png encoded bytestring, ready to be writte as a file.

readPng :: FilePath -> IO (Either String DynamicImage)Source

Helper function trying to load a png file from a file on disk.

decodePng :: ByteString -> Either String DynamicImageSource

Transform a raw png image to an image, without modifying the underlying pixel type. If the image is greyscale and < 8 bits, a transformation to RGBA8 is performed. This should change in the future. The resulting image let you manage the pixel types.

This function can output the following pixel types :

  • PixelY8
  • PixelYA8
  • PixelRGB8
  • PixelRGBA8

writePng :: PngSavable pixel => FilePath -> Image pixel -> IO ()Source

Helper function to directly write an image as a png on disk.

encodeDynamicPng :: DynamicImage -> Either String ByteStringSource

Encode a dynamic image in bmp if possible, supported pixel type are :

  • Y8
  • YA8
  • RGB8
  • RGBA8

writeDynamicPng :: FilePath -> DynamicImage -> IO (Either String Bool)Source

Write a dynamic image in a .png image file if possible. The same restriction as encodeDynamicPng apply.

Image types and pixel types

Image

data Image a Source

Image or pixel buffer, the coordinates are assumed to start from the upper-left corner of the image, with the horizontal position first, then the vertical one.

Constructors

Image 

Fields

imageWidth :: !Int

Width of the image in pixels

imageHeight :: !Int

Height of the image in pixels.

imageData :: Vector Word8

The real image, to extract pixels at some position you should use the helpers functions.

Instances

data DynamicImage Source

Type allowing the loading of an image with different pixel structures

Constructors

ImageY8 (Image Pixel8)

A greyscale image.

ImageYA8 (Image PixelYA8)

An image in greyscale with an alpha channel.

ImageRGB8 (Image PixelRGB8)

An image in true color.

ImageRGBA8 (Image PixelRGBA8)

An image in true color and an alpha channel.

ImageYCbCr8 (Image PixelYCbCr8)

An image in the colorspace used by Jpeg images.

Instances

Pixels

class Serialize a => Pixel a whereSource

Typeclass used to query a type about it's properties regarding casting to other pixel types

Methods

canPromoteTo :: a -> PixelType -> BoolSource

Tell if a pixel can be converted to another pixel, the first value should not be used, and undefined can be used as a valid value.

componentCount :: a -> IntSource

Return the number of component of the pixel

pixelBaseIndex :: Image a -> Int -> Int -> IntSource

Calculate the index for the begining of the pixel

mutablePixelBaseIndex :: MutableImage s a -> Int -> Int -> IntSource

Calculate theindex for the begining of the pixel at position x y

promotionType :: a -> PixelTypeSource

Return the constructor associated to the type, again the value in the first parameter is not used, so you can use undefined

pixelAt :: Image a -> Int -> Int -> aSource

Extract a pixel at a given position, (x, y), the origin is assumed to be at the corner top left, positive y to the bottom of the image

readPixel :: MutableImage s a -> Int -> Int -> ST s aSource

Same as pixelAt but for mutable images.

writePixel :: MutableImage s a -> Int -> Int -> a -> ST s ()Source

Write a pixel in a mutable image at position x y

type Pixel8 = Word8Source

Simple alias for greyscale value in 8 bits.