Codec.Image.PBM

bitwise-1.0.0.1: fast multi-dimensional unboxed bit packed Bool arrays

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.