| Copyright | (c) Claude Heiland-Allen 20122018 |
|---|---|
| License | BSD3 |
| Maintainer | claude@mathr.co.uk |
| Stability | unstable |
| Portability | portable |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Codec.Image.PBM
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 {}
- encodePBM :: BitArray (Int, Int) -> ByteString
- encodePlainPBM :: BitArray (Int, Int) -> String
- data EncodeError
- = BadPixelWidth { }
- | BadSmallWidth { }
- | BadLargeWidth { }
- encodePBM' :: PBM -> Either EncodeError ByteString
- data DecodeError 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
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.
Encoding PBM images.
Arguments
| :: BitArray (Int, Int) | pixels |
| -> ByteString |
Encode a binary PBM (P4) image, padding rows to multiples of 8 bits as necessary.
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 |
| BadSmallWidth | image width is too smaller than array width |
| BadLargeWidth | image width is larger than array width |
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
| Read a => Read (DecodeError a) # | |
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) # | |
Defined in Codec.Image.PBM Methods showsPrec :: Int -> DecodeError a -> ShowS show :: DecodeError a -> String showList :: [DecodeError a] -> ShowS | |
| Eq a => Eq (DecodeError a) # | |
Defined in Codec.Image.PBM | |
| Ord a => Ord (DecodeError a) # | |
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.
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.
Trim any padding bits, required for fold operations to give
meaningful results.
Fails for invalid PBM with image width greater than array width.