Codec.BMP

Reading and writing uncompressed BMP files.

Supports uncompressed 24bit RGB and 32bit RGBA WindowsV3, WindowsV4 and WindowsV5 formats.

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.5
   Add support for writing uncompressed 32-bit files.

 * bmp 1.2.4
   Update to use binary 0.6.

 * 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.

Data Structures

data BMP

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.

Constructors

BMP

Fields

• bmpFileHeader :: FileHeader
• bmpBitmapInfo :: BitmapInfo
• bmpRawImageData :: ByteString

Instances

Show BMP

Defined in Codec.BMP.Base

Methods

showsPrec :: Int -> BMP -> ShowS

show :: BMP -> String

showList :: [BMP] -> ShowS

data FileHeader

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.

Instances

Show FileHeader

Defined in Codec.BMP.FileHeader

Methods

showsPrec :: Int -> FileHeader -> ShowS

show :: FileHeader -> String

showList :: [FileHeader] -> ShowS

Binary FileHeader

Defined in Codec.BMP.FileHeader

Methods

put :: FileHeader -> Put

get :: Get FileHeader

putList :: [FileHeader] -> Put

data BitmapInfo

A wrapper for the various image header types.

Constructors

InfoV3 BitmapInfoV3

InfoV4 BitmapInfoV4

InfoV5 BitmapInfoV5

Instances

Show BitmapInfo

Defined in Codec.BMP.BitmapInfo

Methods

showsPrec :: Int -> BitmapInfo -> ShowS

show :: BitmapInfo -> String

showList :: [BitmapInfo] -> ShowS

Binary BitmapInfo

Defined in Codec.BMP.BitmapInfo

Methods

put :: BitmapInfo -> Put

get :: Get BitmapInfo

putList :: [BitmapInfo] -> Put

data BitmapInfoV3

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.

Instances

Show BitmapInfoV3

Defined in Codec.BMP.BitmapInfoV3

Methods

showsPrec :: Int -> BitmapInfoV3 -> ShowS

show :: BitmapInfoV3 -> String

showList :: [BitmapInfoV3] -> ShowS

Binary BitmapInfoV3

Defined in Codec.BMP.BitmapInfoV3

Methods

put :: BitmapInfoV3 -> Put

get :: Get BitmapInfoV3

putList :: [BitmapInfoV3] -> Put

data BitmapInfoV4

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

Instances

Show BitmapInfoV4

Defined in Codec.BMP.BitmapInfoV4

Methods

showsPrec :: Int -> BitmapInfoV4 -> ShowS

show :: BitmapInfoV4 -> String

showList :: [BitmapInfoV4] -> ShowS

Binary BitmapInfoV4

Defined in Codec.BMP.BitmapInfoV4

Methods

put :: BitmapInfoV4 -> Put

get :: Get BitmapInfoV4

putList :: [BitmapInfoV4] -> Put

data BitmapInfoV5

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.

Instances

Show BitmapInfoV5

Defined in Codec.BMP.BitmapInfoV5

Methods

showsPrec :: Int -> BitmapInfoV5 -> ShowS

show :: BitmapInfoV5 -> String

showList :: [BitmapInfoV5] -> ShowS

Binary BitmapInfoV5

Defined in Codec.BMP.BitmapInfoV5

Methods

put :: BitmapInfoV5 -> Put

get :: Get BitmapInfoV5

putList :: [BitmapInfoV5] -> Put

data Compression

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

Constructors

CompressionRGB

CompressionRLE8

CompressionRLE4

CompressionBitFields

CompressionJPEG

CompressionPNG

CompressionUnknown Word32

Instances

Show Compression

Defined in Codec.BMP.Compression

Methods

showsPrec :: Int -> Compression -> ShowS

show :: Compression -> String

showList :: [Compression] -> ShowS

Binary Compression

Defined in Codec.BMP.Compression

Methods

put :: Compression -> Put

get :: Get Compression

putList :: [Compression] -> Put

Eq Compression

Defined in Codec.BMP.Compression

Methods

(==) :: Compression -> Compression -> Bool

(/=) :: Compression -> Compression -> Bool

data CIEXYZ

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

Constructors

CIEXYZ Word32 Word32 Word32

Instances

Show CIEXYZ

Defined in Codec.BMP.CIEXYZ

Methods

showsPrec :: Int -> CIEXYZ -> ShowS

show :: CIEXYZ -> String

showList :: [CIEXYZ] -> ShowS

Binary CIEXYZ

Defined in Codec.BMP.CIEXYZ

Methods

put :: CIEXYZ -> Put

get :: Get CIEXYZ

putList :: [CIEXYZ] -> Put

data Error

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.

Fields

• errorBytesNeeded :: Int
• errorBytesAvailable :: Int

ErrorReservedFieldNotZero

Reserved fields should be zero.

ErrorDodgyFileHeaderFieldOffset

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

Fields

• errorFileHeaderOffset :: Word32

ErrorUnhandledBitmapHeaderSize

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

Fields

• errorBitmapHeaderSize :: Word32

ErrorUnhandledPlanesCount

We only handle single color planes.

Fields

• errorPlanesCount :: Word16

ErrorUnhandledColorDepth

We only handle 24 and 32 bit images.

Fields

• errorColorDepth :: Word16

ErrorUnhandledCompressionMode

We only handle uncompressed images.

Fields

• errorCompression :: Compression

ErrorImagePhysicalSizeMismatch

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

Fields

• errorImageSizeFromHeader :: Word32
• errorImageSizeOfBuffer :: Word32

ErrorInternalErrorPleaseReport

Something went wrong in the library.

Instances

Show Error

Defined in Codec.BMP.Error

Methods

showsPrec :: Int -> Error -> ShowS

show :: Error -> String

showList :: [Error] -> ShowS

Eq Error

Defined in Codec.BMP.Error

Methods

(==) :: Error -> Error -> Bool

(/=) :: Error -> Error -> Bool

Reading

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

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)

Get a BMP image from a file handle.

parseBMP :: ByteString -> Either Error BMP

Parse a BMP image from a lazy ByteString

Writing

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

Wrapper for hPutBMP

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

Put a BMP image to a file handle.

renderBMP :: BMP -> ByteString

Render a BMP image to a lazy ByteString.

Pack and Unpack

packRGBA32ToBMP

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 32-bit BMP image.

Alias for packRGBA32ToBMP32.

packRGBA32ToBMP32

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 32-bit BMP image.

• If the given dimensions don't match the input string then error.
• If the width or height fields are negative then error.

packRGBA32ToBMP24

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 24-bit BMP image, discarding the alpha channel of the source data.

• If the given dimensions don't match the input string then error.
• If the width or height fields are negative then error.

unpackBMPToRGBA32 :: BMP -> ByteString

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

bmpDimensions :: BMP -> (Int, Int)

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