Copyright	(c) Claude Heiland-Allen 20122018
License	BSD3
Maintainer	claude@mathr.co.uk
Stability	unstable
Portability	portable
Safe Haskell	None
Language	Haskell2010

Codec.Image.PBM

Contents

Encoding PBM images.
Decoding PBM images.
Padding and trimming PBM images.

Description

Encode and decode both versions (binary P4 and plain P1) of PBM: the portable bitmap lowest common denominator monochrome image file format.

References:

pbm(5)
The PBM Format http://netpbm.sourceforge.net/doc/pbm.html

Bugs:

This implementation is not fully compliant with the PBM specification, with respect to point 8 in the second reference above which states that a comment can actually be in the middle of what you might consider a token Such a pathological PBM file might be rejected by decodePBM, but may instead be wrongly decoded if (for example) the comment were in the middle of the image width token, leading to it being interpreted as a (smaller) width and height.

Synopsis

data PBM = PBM {
- pbmWidth :: !Int
- pbmPixels :: !(BitArray (Int, Int))
}
encodePBM :: BitArray (Int, Int) -> ByteString
encodePlainPBM :: BitArray (Int, Int) -> String
data EncodeError
- = BadPixelWidth {
  - encErrPBM :: PBM
  }
- | BadSmallWidth {
  - encErrPBM :: PBM
  }
- | BadLargeWidth {
  - encErrPBM :: PBM
  }
encodePBM' :: PBM -> Either EncodeError ByteString
data DecodeError a
- = BadMagicP a
- | BadMagicN a
- | BadWidth a
- | BadHeight a
- | BadSpace a
- | BadPixels a
decodePBM :: ByteString -> Either (DecodeError ByteString) (PBM, ByteString)
decodePlainPBM :: String -> Either (DecodeError String) (PBM, String)
decodePBMs :: ByteString -> ([PBM], Maybe (DecodeError ByteString))
padPBM :: PBM -> PBM
trimPBM :: PBM -> Maybe PBM
repadPBM :: PBM -> Maybe PBM

Documentation

data PBM #

A decoded PBM image. pbmWidth must be less or equal to the width of the pbmPixels array (which has its first index in Y and the second in X, with lowest coordinates at the top left).

False pixels are white, True pixels are black. Pixels to the right of pbmWidth are don't care padding bits. However, these padding bits are likely to invalidate aggregrate fold operations. See trimPBM.

Constructors

PBM
Fields pbmWidth :: !Int pbmPixels :: !(BitArray (Int, Int))

Encoding PBM images.

encodePBM #

Arguments

:: BitArray (Int, Int)	pixels
-> ByteString

Encode a binary PBM (P4) image, padding rows to multiples of 8 bits as necessary.

encodePlainPBM #

Arguments

:: BitArray (Int, Int)	pixels
-> String

Encode a plain PBM (P1) image.

No restrictions on pixels array size, but the file format is exceedingly wasteful of space.

data EncodeError #

Possible reasons for encoding to fail.

Constructors

BadPixelWidth	array width is not a multiple of 8 bits
Fields encErrPBM :: PBM
BadSmallWidth	image width is too smaller than array width
Fields encErrPBM :: PBM
BadLargeWidth	image width is larger than array width
Fields encErrPBM :: PBM

encodePBM' :: PBM -> Either EncodeError ByteString #

Encode a pre-padded PBM to a binary PBM (P4) image.

The pixels array must have a multiple of 8 bits per row. The image width may be less than the pixel array width, with up to 7 padding bits at the end of each row.

Decoding PBM images.

data DecodeError a #

Possible reasons for decoding to fail, with the input that failed.

Constructors

BadMagicP a	First character was not P.
BadMagicN a	Second character was not 4 (binary) or 1 (plain).
BadWidth a	The width could not be parsed, or was non-positive.
BadHeight a	The height could not be parsed, or was non-positive.
BadSpace a	Parsing failed at the space before the pixel data.
BadPixels a	There weren't enough bytes of pixel data.

Instances

Instances details

Read a => Read (DecodeError a) #
Instance details Defined in Codec.Image.PBM Methods readsPrec :: Int -> ReadS (DecodeError a) # readList :: ReadS [DecodeError a] # readPrec :: ReadPrec (DecodeError a) # readListPrec :: ReadPrec [DecodeError a] #
Show a => Show (DecodeError a) #
Instance details Defined in Codec.Image.PBM Methods showsPrec :: Int -> DecodeError a -> ShowS # show :: DecodeError a -> String # showList :: [DecodeError a] -> ShowS #
Eq a => Eq (DecodeError a) #
Instance details Defined in Codec.Image.PBM Methods (==) :: DecodeError a -> DecodeError a -> Bool # (/=) :: DecodeError a -> DecodeError a -> Bool #
Ord a => Ord (DecodeError a) #
Instance details Defined in Codec.Image.PBM Methods compare :: DecodeError a -> DecodeError a -> Ordering # (<) :: DecodeError a -> DecodeError a -> Bool # (<=) :: DecodeError a -> DecodeError a -> Bool # (>) :: DecodeError a -> DecodeError a -> Bool # (>=) :: DecodeError a -> DecodeError a -> Bool # max :: DecodeError a -> DecodeError a -> DecodeError a # min :: DecodeError a -> DecodeError a -> DecodeError a #

decodePBM :: ByteString -> Either (DecodeError ByteString) (PBM, ByteString) #

Decode a binary PBM (P4) image.

decodePlainPBM :: String -> Either (DecodeError String) (PBM, String) #

Decode a plain PBM (P1) image.

Note that the pixel array size is kept as-is (with the width not necessarily a multiple of 8 bits).

decodePBMs :: ByteString -> ([PBM], Maybe (DecodeError ByteString)) #

Decode a sequence of binary PBM (P4) images.

Keeps decoding until end of input (in which case the snd of the result is Nothing) or an error occurred.

Padding and trimming PBM images.

padPBM :: PBM -> PBM #

Add padding bits at the end of each row to make the array width a multiple of 8 bits, required for binary PBM (P4) encoding.

trimPBM :: PBM -> Maybe PBM #

Trim any padding bits, required for fold operations to give meaningful results.

Fails for invalid PBM with image width greater than array width.

repadPBM :: PBM -> Maybe PBM #

Trim then pad. The resulting PBM (if any) is suitable for encoding to binary PBM (P4), moreover its padding bits will be cleared.