bmp-1.2.4.1: Read and write uncompressed BMP image files.

Safe HaskellNone

Codec.BMP

Contents

Description

Reading and writing uncompressed BMP files.

Reading works for both uncompressed 24bit RGB and 32bit RGBA WindowsV3, WindowsV4 and WindowsV5 formats.

Writing is limited to the uncompressed 24bit RGB WindowsV3 format.

We don't support the plain OS/2 BitmapCoreHeader and BitmapCoreHeader2 image headers, but I haven't yet seen one of these in the wild.

To write a file do something like:

 do let rgba   = Data.ByteString.pack [some list of Word8s]
    let bmp    = packRGBA32ToBMP width height rgba
    writeBMP fileName bmp

To read a file do something like:

 do Right bmp  <- readBMP fileName
    let rgba   =  unpackBMPToRGBA32 bmp
    let (width, height) = bmpDimensions bmp
    ... 

Release Notes:

  * bmp 1.2.3
    Add pure parseBMP / renderBMP API.

  * bmp 1.2.2
    Allow the physical image buffer to be larger than the image
     size stated in the header, to accept output of foolish Win7 codec.

  * bmp 1.2.1
    Fix slow ByteString conversion via lists.  

  * bmp 1.2.0
    Accept files with zero padding on the end of the file.
    Accept RGBA files with V3 headers.

  * bmp 1.1.2   
    Accept files with the image size field set to zero.

Synopsis

Data Structures

data BMP Source

A BMP image. For an uncompressed image, the image data contains triples of BGR component values. Each line may also have zero pad values on the end, to bring them up to a multiple of 4 bytes in length.

Instances

data FileHeader Source

BMP file header.

Constructors

FileHeader 

Fields

fileHeaderType :: Word16

(+0) Magic numbers 0x42 0x4d

fileHeaderFileSize :: Word32

(+2) Size of the file, in bytes.

fileHeaderReserved1 :: Word16

(+6) Reserved, must be zero.

fileHeaderReserved2 :: Word16

(+8) Reserved, must be zero.

fileHeaderOffset :: Word32

(+10) Offset in bytes to the start of the pixel data.

data BitmapInfo Source

A wrapper for the various image header types.

data BitmapInfoV3 Source

Device Independent Bitmap (DIB) header for Windows V3.

Constructors

BitmapInfoV3 

Fields

dib3Size :: Word32

(+0) Size of the image header, in bytes.

dib3Width :: Word32

(+4) Width of the image, in pixels.

dib3Height :: Word32

(+8) Height of the image, in pixels.

dib3HeightFlipped :: Bool

If the height field in the file is negative then this is interpreted as an image with the rows flipped.

dib3Planes :: Word16

(+12) Number of color planes.

dib3BitCount :: Word16

(+14) Number of bits per pixel.

dib3Compression :: Compression

(+16) Image compression mode.

dib3ImageSize :: Word32

(+20) Size of raw image data. Some encoders set this to zero, so we need to calculate it based on the overall file size.

If it is non-zero then we check it matches the file size - header size.

dib3PelsPerMeterX :: Word32

(+24) Prefered resolution in pixels per meter, along the X axis.

dib3PelsPerMeterY :: Word32

(+28) Prefered resolution in pixels per meter, along the Y axis.

dib3ColorsUsed :: Word32

(+32) Number of color entries that are used.

dib3ColorsImportant :: Word32

(+36) Number of significant colors.

data BitmapInfoV4 Source

Device Independent Bitmap (DIB) header for Windows V4 (95 and newer)

Constructors

BitmapInfoV4 

Fields

dib4InfoV3 :: BitmapInfoV3

Size of the image header, in bytes.

dib4RedMask :: Word32

Color masks specify components of each pixel. Only used with the bitfields compression mode.

dib4GreenMask :: Word32
 
dib4BlueMask :: Word32
 
dib4AlphaMask :: Word32
 
dib4ColorSpaceType :: Word32

The color space used by the image.

dib4Endpoints :: (CIEXYZ, CIEXYZ, CIEXYZ)

Specifies the XYZ coords of the three colors that correspond to the RGB endpoints for the logical color space associated with the bitmap. Only used when ColorSpaceType specifies a calibrated image.

dib4GammaRed :: Word32

Toned response curves for each component. Only used when the ColorSpaceType specifies a calibrated image.

dib4GammaGreen :: Word32
 
dib4GammaBlue :: Word32
 

data BitmapInfoV5 Source

Device Independent Bitmap (DIB) header for Windows V5 (98/2000 and newer)

Constructors

BitmapInfoV5 

Fields

dib5InfoV4 :: BitmapInfoV4
 
dib5Intent :: Word32

Rendering intent for the bitmap.

dib5ProfileData :: Word32

Offset (in bytes) from the beginning of the header to the start of the profile data.

dib5ProfileSize :: Word32

Size (in bytes) of embedded profile data.

dib5Reserved :: Word32

Reserved, should be zero.

data Compression Source

The Compression mode says how the image data is encoded in the file.

data CIEXYZ Source

Contains the XYZ coordinates of a specific color in a specified color space.

Constructors

CIEXYZ Word32 Word32 Word32 

Instances

data Error Source

Things that can go wrong when loading a BMP file.

Constructors

ErrorBadMagic

Magic number was not at the start of the file, so this probably isn't a BMP file.

Fields

errorMagic :: Word16
 
ErrorFileHeaderTruncated

File is too short to contain a file header.

ErrorImageHeaderTruncated

File is too short to contain an image header.

ErrorImageDataTruncated

File is too short to contain the image data.

ErrorReservedFieldNotZero

Reserved fields should be zero.

ErrorDodgyFileHeaderFieldOffset

The offset to the image data from the file header doesn't point anywhere sensible.

ErrorUnhandledBitmapHeaderSize

We handle V3 V4 and V5 image headers, but the size of the header indicates it has some other format.

ErrorUnhandledPlanesCount

We only handle single color planes.

ErrorUnhandledColorDepth

We only handle 24 and 32 bit images.

ErrorUnhandledCompressionMode

We only handle uncompressed images.

ErrorImagePhysicalSizeMismatch

Mismatch between the image size stated in the header and that which is calculuated from the other fields.

ErrorInternalErrorPleaseReport

Something went wrong in the library.

Instances

Reading

readBMP :: FilePath -> IO (Either Error BMP)Source

Read a BMP from a file. The file is checked for problems and unsupported features when read. If there is anything wrong this gives an Error instead.

hGetBMP :: Handle -> IO (Either Error BMP)Source

Get a BMP image from a file handle.

parseBMP :: ByteString -> Either Error BMPSource

Parse a BMP image from a lazy ByteString

Writing

writeBMP :: FilePath -> BMP -> IO ()Source

Wrapper for hPutBMP

hPutBMP :: Handle -> BMP -> IO ()Source

Put a BMP image to a file handle.

renderBMP :: BMP -> ByteStringSource

Render a BMP image to a lazy ByteString.

Pack and Unpack

packRGBA32ToBMPSource

Arguments

:: Int

Width of image (must be positive).

-> Int

Height of image (must be positive).

-> ByteString

A string of RGBA component values. Must have length (width * height * 4)

-> BMP 

Pack a string of RGBA component values into a BMP image.

  • If the given dimensions don't match the input string then error.
  • If the width or height fields are negative then error.
  • This currently ignores the alpha component of the input string and produces a 24bit RGB image.

unpackBMPToRGBA32 :: BMP -> ByteStringSource

Unpack a BMP image to a string of RGBA component values.

bmpDimensions :: BMP -> (Int, Int)Source

Get the width and height of an image. It's better to use this function than to access the headers directly.