Copyright | (c) Alexey Kuleshevich 2018-2019 |
---|---|
License | BSD3 |
Maintainer | Alexey Kuleshevich <lehins@yandex.ru> |
Stability | experimental |
Portability | non-portable |
Safe Haskell | None |
Language | Haskell2010 |
Synopsis
- readArray :: Readable f arr => f -> ReadOptions f -> FilePath -> IO arr
- readImage :: (Source S Ix2 (Pixel cs e), ColorSpace cs e) => FilePath -> IO (Image S cs e)
- readImageAuto :: (Mutable r Ix2 (Pixel cs e), ColorSpace cs e) => FilePath -> IO (Image r cs e)
- writeArray :: Writable f arr => f -> WriteOptions f -> FilePath -> arr -> IO ()
- writeImage :: (Source r Ix2 (Pixel cs e), ColorSpace cs e) => FilePath -> Image r cs e -> IO ()
- writeImageAuto :: (Source r Ix2 (Pixel cs e), ColorSpace cs e, ToYA cs e, ToRGBA cs e, ToYCbCr cs e, ToCMYK cs e) => FilePath -> Image r cs e -> IO ()
- data ExternalViewer = ExternalViewer FilePath [String] Int
- displayImage :: Writable (Auto TIF) (Image r cs e) => Image r cs e -> IO ()
- displayImageUsing :: Writable (Auto TIF) (Image r cs e) => ExternalViewer -> Bool -> Image r cs e -> IO ()
- displayImageFile :: ExternalViewer -> FilePath -> IO ()
- defaultViewer :: ExternalViewer
- eogViewer :: ExternalViewer
- gpicviewViewer :: ExternalViewer
- fehViewer :: ExternalViewer
- gimpViewer :: ExternalViewer
- class Writable f arr where
- encode :: f -> WriteOptions f -> arr -> ByteString
- class Readable f arr where
- decode :: f -> ReadOptions f -> ByteString -> arr
- class (Default (ReadOptions f), Default (WriteOptions f), Show f) => FileFormat f where
- type ReadOptions f
- type WriteOptions f
- ext :: f -> String
- exts :: f -> [String]
- isFormat :: String -> f -> Bool
- newtype Auto f = Auto f
- newtype Sequence f = Sequence f
- newtype EncodeError = EncodeError String
- newtype DecodeError = DecodeError String
- newtype ConvertError = ConvertError String
- type Image r cs e = Array r Ix2 (Pixel cs e)
- defaultReadOptions :: FileFormat f => f -> ReadOptions f
- defaultWriteOptions :: FileFormat f => f -> WriteOptions f
- data Encode out
- encodeImage :: (Source r Ix2 (Pixel cs e), ColorSpace cs e) => [Encode (Image r cs e)] -> FilePath -> Image r cs e -> ByteString
- imageWriteFormats :: (Source r Ix2 (Pixel cs e), ColorSpace cs e) => [Encode (Image r cs e)]
- imageWriteAutoFormats :: (Source r Ix2 (Pixel cs e), ColorSpace cs e, ToYA cs e, ToRGBA cs e, ToYCbCr cs e, ToCMYK cs e) => [Encode (Image r cs e)]
- data Decode out
- decodeImage :: (Source r Ix2 (Pixel cs e), ColorSpace cs e) => [Decode (Image r cs e)] -> FilePath -> ByteString -> Image r cs e
- imageReadFormats :: (Source S Ix2 (Pixel cs e), ColorSpace cs e) => [Decode (Image S cs e)]
- imageReadAutoFormats :: (Mutable r Ix2 (Pixel cs e), ColorSpace cs e) => [Decode (Image r cs e)]
- data BMP = BMP
- data GIF = GIF
- data WriteOptionsGIF
- woGetPaletteOptionsGIF :: WriteOptionsGIF -> PaletteOptions
- woSetPaletteOptionsGIF :: PaletteOptions -> WriteOptionsGIF -> WriteOptionsGIF
- data PaletteOptions = PaletteOptions {}
- data PaletteCreationMethod
- data WriteOptionsSequenceGIF
- woGetGifLoopingGIFs :: WriteOptionsSequenceGIF -> GifLooping
- woGetPaletteOptionsGIFs :: WriteOptionsSequenceGIF -> PaletteOptions
- woSetGifLoopingGIFs :: GifLooping -> WriteOptionsSequenceGIF -> WriteOptionsSequenceGIF
- woSetPaletteOptionsGIFs :: PaletteOptions -> WriteOptionsSequenceGIF -> WriteOptionsSequenceGIF
- type GifDelay = Int
- data GifLooping
- data HDR = HDR
- data JPG = JPG
- data WriteOptionsJPG
- woGetQualityJPG :: WriteOptionsJPG -> Word8
- woSetQualityJPG :: Word8 -> WriteOptionsJPG -> WriteOptionsJPG
- data PNG = PNG
- data TGA = TGA
- data TIF = TIF
- toAnyCS :: forall r' cs' e' r cs e. (Source r' Ix2 (Pixel cs' e'), Mutable r Ix2 (Pixel cs e), ColorSpace cs e, ToYA cs' e', ToRGBA cs' e', ToHSIA cs' e', ToCMYKA cs' e', ToYCbCrA cs' e') => Image r' cs' e' -> Maybe (Image r cs e)
- toJPImageY8 :: Source r Ix2 (Pixel Y Word8) => Image r Y Word8 -> Image Pixel8
- toJPImageYA8 :: Source r Ix2 (Pixel YA Word8) => Image r YA Word8 -> Image PixelYA8
- toJPImageY16 :: Source r Ix2 (Pixel Y Word16) => Image r Y Word16 -> Image Pixel16
- toJPImageYA16 :: Source r Ix2 (Pixel YA Word16) => Image r YA Word16 -> Image PixelYA16
- toJPImageYF :: Source r Ix2 (Pixel Y Float) => Image r Y Float -> Image PixelF
- toJPImageRGB8 :: Source r Ix2 (Pixel RGB Word8) => Image r RGB Word8 -> Image PixelRGB8
- toJPImageRGBA8 :: Source r Ix2 (Pixel RGBA Word8) => Image r RGBA Word8 -> Image PixelRGBA8
- toJPImageRGB16 :: Source r Ix2 (Pixel RGB Word16) => Image r RGB Word16 -> Image PixelRGB16
- toJPImageRGBA16 :: Source r Ix2 (Pixel RGBA Word16) => Image r RGBA Word16 -> Image PixelRGBA16
- toJPImageRGBF :: Source r Ix2 (Pixel RGB Float) => Image r RGB Float -> Image PixelRGBF
- toJPImageYCbCr8 :: Source r Ix2 (Pixel YCbCr Word8) => Image r YCbCr Word8 -> Image PixelYCbCr8
- toJPImageCMYK8 :: Source r Ix2 (Pixel CMYK Word8) => Image r CMYK Word8 -> Image PixelCMYK8
- toJPImageCMYK16 :: Source r Ix2 (Pixel CMYK Word16) => Image r CMYK Word16 -> Image PixelCMYK16
- fromDynamicImage :: forall cs e. ColorSpace cs e => DynamicImage -> Maybe (Image S cs e)
- fromAnyDynamicImage :: (Mutable r Ix2 (Pixel cs e), ColorSpace cs e) => DynamicImage -> Maybe (Image r cs e)
- data PBM = PBM
- data PGM = PGM
- data PPM = PPM
Documentation
Encoding and decoding of images is done using JuicyPixels and netpbm packages.
List of image formats that are currently supported, and their exact
ColorSpace
s and precision for reading and writing without an implicit
conversion:
:: Readable f arr | |
=> f | File format that should be used while decoding the file |
-> ReadOptions f | Any file format related decoding options. Use |
-> FilePath | Path to the file |
-> IO arr |
Read an array from one of the supported file formats.
:: (Source S Ix2 (Pixel cs e), ColorSpace cs e) | |
=> FilePath | File path for an image |
-> IO (Image S cs e) |
Try to guess an image format from file's extension, then attempt to decode it as such. In order
to supply the format manually and thus avoid this guessing technique, use readArray
instead. Color space and precision of the result array must match exactly that of the actual
image, in order to apply auto conversion use readImageAuto
instead.
Might throw ConvertError
, DecodeError
and other standard errors related to file IO.
Result image will be read as specified by the type signature:
>>>
frog <- readImage "files/frog.jpg" :: IO (Image S YCbCr Word8)
>>>
displayImage frog
In case when the result image type does not match the color space or precision of the actual
image file, ConvertError
will be thrown.
>>>
frog <- readImage "files/frog.jpg" :: IO (Image S CMYK Word8)
>>>
displayImage frog
*** Exception: ConvertError "Cannot decode JPG image <Image S YCbCr Word8> as <Image S CMYK Word8>"
Whenever image is not in the color space or precision that we need, either use readImageAuto
or
manually convert to the desired one by using the appropriate conversion functions:
>>>
frogCMYK <- readImageAuto "files/frog.jpg" :: IO (Image S CMYK Double)
>>>
displayImage frogCMYK
:: (Mutable r Ix2 (Pixel cs e), ColorSpace cs e) | |
=> FilePath | File path for an image |
-> IO (Image r cs e) |
Same as readImage
, but will perform any possible color space and
precision conversions in order to match the result image type. Very useful
whenever image format isn't known at compile time.
Writing
:: Writable f arr | |
=> f | Format to use while encoding the array |
-> WriteOptions f | Any file format related encoding options. Use |
-> FilePath | |
-> arr | |
-> IO () |
writeImage :: (Source r Ix2 (Pixel cs e), ColorSpace cs e) => FilePath -> Image r cs e -> IO () Source #
This function will guess an output file format from the file extension and will write to file
any image with the colorspace that is supported by that format. Precision of the image might be
adjusted using Elevator
if precision of the source array is not supported by the image file
format. For instance an (
being saved as Image
r RGBA
Double
)PNG
file would be written as
(
, thus using highest supported precision Image
r RGBA
Word16
)Word16
for that
format. If automatic colors space is also desired, writeImageAuto
can be used instead.
Can throw ConvertError
, EncodeError
and other usual IO errors.
writeImageAuto :: (Source r Ix2 (Pixel cs e), ColorSpace cs e, ToYA cs e, ToRGBA cs e, ToYCbCr cs e, ToCMYK cs e) => FilePath -> Image r cs e -> IO () Source #
Write an image to file while performing all necessary precisiona and color space conversions.
Displaying
data ExternalViewer Source #
External viewing application to use for displaying images.
ExternalViewer FilePath [String] Int | Any custom viewer, which can be specified:
|
Instances
Show ExternalViewer Source # | |
Defined in Data.Massiv.Array.IO showsPrec :: Int -> ExternalViewer -> ShowS # show :: ExternalViewer -> String # showList :: [ExternalViewer] -> ShowS # |
displayImage :: Writable (Auto TIF) (Image r cs e) => Image r cs e -> IO () Source #
Makes a call to an external viewer that is set as a default image viewer by the OS. This is a non-blocking function call, so it might take some time before an image will appear.
:: Writable (Auto TIF) (Image r cs e) | |
=> ExternalViewer | Image viewer program |
-> Bool | Should the function block the current thread until viewer is closed. |
-> Image r cs e | |
-> IO () |
An image is written as a .tiff
file into an operating system's temporary
directory and passed as an argument to the external viewer program.
displayImageFile :: ExternalViewer -> FilePath -> IO () Source #
Displays an image file by calling an external image viewer.
Common viewers
defaultViewer :: ExternalViewer Source #
Default viewer is inferred from the operating system.
eogViewer :: ExternalViewer Source #
eog /tmp/hip/img.tiff
gpicviewViewer :: ExternalViewer Source #
gpicview /tmp/hip/img.tiff
fehViewer :: ExternalViewer Source #
feh --fullscreen --auto-zoom /tmp/hip/img.tiff
gimpViewer :: ExternalViewer Source #
gimp /tmp/hip/img.tiff
Supported Image Formats
class Writable f arr where Source #
Arrays that can be written into a file.
encode :: f -> WriteOptions f -> arr -> ByteString Source #
Encode an array into a ByteString
.
Instances
class Readable f arr where Source #
File formats that can be read into an Array.
decode :: f -> ReadOptions f -> ByteString -> arr Source #
Decode a ByteString
into an Array.
Instances
class (Default (ReadOptions f), Default (WriteOptions f), Show f) => FileFormat f where Source #
File format. Helps in guessing file format from a file extension, as well as supplying format specific options during saving the file.
type ReadOptions f Source #
Options that can be used during reading a file in this format.
type WriteOptions f Source #
Options that can be used during writing a file in this format.
Default file extension for this file format.
exts :: f -> [String] Source #
Other known file extensions for this file format, eg. ".jpeg", ".jpg".
isFormat :: String -> f -> Bool Source #
Checks if a file extension corresponds to the format, eg.
isFormat ".png" PNG == True
Instances
FileFormat TIF Source # | |
FileFormat TGA Source # | |
FileFormat JPG Source # | |
FileFormat HDR Source # | |
FileFormat GIF Source # | |
FileFormat PNG Source # | |
FileFormat BMP Source # | |
FileFormat PPM Source # | |
FileFormat PGM Source # | |
FileFormat PBM Source # | |
FileFormat f => FileFormat (Auto f) Source # | |
FileFormat (Sequence (Auto GIF)) Source # | |
Defined in Data.Massiv.Array.IO.Image.JuicyPixels | |
FileFormat (Sequence (Auto PPM)) Source # | |
Defined in Data.Massiv.Array.IO.Image.Netpbm | |
FileFormat (Sequence (Auto PGM)) Source # | |
Defined in Data.Massiv.Array.IO.Image.Netpbm | |
FileFormat (Sequence (Auto PBM)) Source # | |
Defined in Data.Massiv.Array.IO.Image.Netpbm | |
FileFormat (Sequence GIF) Source # | |
FileFormat (Sequence PPM) Source # | |
FileFormat (Sequence PGM) Source # | |
FileFormat (Sequence PBM) Source # | |
FileFormat (Decode (Image r cs e)) Source # | |
Defined in Data.Massiv.Array.IO.Image | |
FileFormat (Encode (Image r cs e)) Source # | |
Defined in Data.Massiv.Array.IO.Image |
Auto f |
Instances
Special wrapper for formats that support encoding/decoding sequence of array.
Sequence f |
Instances
newtype EncodeError Source #
This exception can be thrown while writing/encoding into a file and indicates an error in an array that is being encoded.
Instances
Show EncodeError Source # | |
Defined in Data.Massiv.Array.IO.Base showsPrec :: Int -> EncodeError -> ShowS # show :: EncodeError -> String # showList :: [EncodeError] -> ShowS # | |
Exception EncodeError Source # | |
Defined in Data.Massiv.Array.IO.Base |
newtype DecodeError Source #
This exception can be thrown while reading/decoding a file and indicates an error in the file itself.
Instances
Show DecodeError Source # | |
Defined in Data.Massiv.Array.IO.Base showsPrec :: Int -> DecodeError -> ShowS # show :: DecodeError -> String # showList :: [DecodeError] -> ShowS # | |
Exception DecodeError Source # | |
Defined in Data.Massiv.Array.IO.Base |
newtype ConvertError Source #
Conversion error, which is thrown when there is a mismatch between the expected array type and the one supported by the file format. It is also thrown upon a failure of automatic conversion between those types, in case such conversion is utilized.
Instances
Show ConvertError Source # | |
Defined in Data.Massiv.Array.IO.Base showsPrec :: Int -> ConvertError -> ShowS # show :: ConvertError -> String # showList :: [ConvertError] -> ShowS # | |
Exception ConvertError Source # | |
Defined in Data.Massiv.Array.IO.Base |
defaultReadOptions :: FileFormat f => f -> ReadOptions f Source #
Generate default read options for a file format
defaultWriteOptions :: FileFormat f => f -> WriteOptions f Source #
Generate default write options for a file format
Instances
Show (Encode out) Source # | |
FileFormat (Encode (Image r cs e)) Source # | |
Defined in Data.Massiv.Array.IO.Image | |
Writable (Encode (Image r cs e)) (Image r cs e) Source # | |
Defined in Data.Massiv.Array.IO.Image encode :: Encode (Image r cs e) -> WriteOptions (Encode (Image r cs e)) -> Image r cs e -> ByteString Source # | |
type ReadOptions (Encode (Image r cs e)) Source # | |
Defined in Data.Massiv.Array.IO.Image | |
type WriteOptions (Encode (Image r cs e)) Source # | |
Defined in Data.Massiv.Array.IO.Image |
:: (Source r Ix2 (Pixel cs e), ColorSpace cs e) | |
=> [Encode (Image r cs e)] | List of image formats to choose from (useful lists are
|
-> FilePath | File name with extension, so the format can be inferred |
-> Image r cs e | Image to encode |
-> ByteString |
Encode an image into a lazy ByteString
, while selecting the appropriate format from the
file extension.
imageWriteFormats :: (Source r Ix2 (Pixel cs e), ColorSpace cs e) => [Encode (Image r cs e)] Source #
List of image formats that can be encoded without any color space conversion.
imageWriteAutoFormats :: (Source r Ix2 (Pixel cs e), ColorSpace cs e, ToYA cs e, ToRGBA cs e, ToYCbCr cs e, ToCMYK cs e) => [Encode (Image r cs e)] Source #
List of image formats that can be encoded with any necessary color space conversions.
Instances
Show (Decode out) Source # | |
FileFormat (Decode (Image r cs e)) Source # | |
Defined in Data.Massiv.Array.IO.Image | |
Readable (Decode (Image r cs e)) (Image r cs e) Source # | |
Defined in Data.Massiv.Array.IO.Image decode :: Decode (Image r cs e) -> ReadOptions (Decode (Image r cs e)) -> ByteString -> Image r cs e Source # | |
type ReadOptions (Decode (Image r cs e)) Source # | |
Defined in Data.Massiv.Array.IO.Image | |
type WriteOptions (Decode (Image r cs e)) Source # | |
Defined in Data.Massiv.Array.IO.Image |
:: (Source r Ix2 (Pixel cs e), ColorSpace cs e) | |
=> [Decode (Image r cs e)] | List of available formats to choose from |
-> FilePath | File name with extension, so format can be inferred |
-> ByteString | Encoded image |
-> Image r cs e |
Decode an image from the strict ByteString
while inferring format the image is encoded in
from the file extension
imageReadFormats :: (Source S Ix2 (Pixel cs e), ColorSpace cs e) => [Decode (Image S cs e)] Source #
List of image formats decodable with no colorspace conversion
imageReadAutoFormats :: (Mutable r Ix2 (Pixel cs e), ColorSpace cs e) => [Decode (Image r cs e)] Source #
List of image formats decodable with no colorspace conversion
JuicyPixels formats
BMP
Bitmap image with .bmp
extension.
Instances
GIF
Graphics Interchange Format image with .gif
extension.
Instances
data WriteOptionsGIF Source #
Instances
Default WriteOptionsGIF Source # | |
Defined in Data.Massiv.Array.IO.Image.JuicyPixels def :: WriteOptionsGIF # |
data PaletteOptions #
To specify how the palette will be created.
PaletteOptions | |
|
data PaletteCreationMethod #
Define which palette creation method is used.
MedianMeanCut | MedianMeanCut method, provide the best results (visualy) at the cost of increased calculations. |
Uniform | Very fast algorithm (one pass), doesn't provide good looking results. |
Animated
data WriteOptionsSequenceGIF Source #
Instances
Default WriteOptionsSequenceGIF Source # | |
Defined in Data.Massiv.Array.IO.Image.JuicyPixels |
woSetPaletteOptionsGIFs :: PaletteOptions -> WriteOptionsSequenceGIF -> WriteOptionsSequenceGIF Source #
Delay to wait before showing the next Gif image. The delay is expressed in 100th of seconds.
data GifLooping #
Help to control the behaviour of GIF animation looping.
LoopingNever | The animation will stop once the end is reached |
LoopingForever | The animation will restart once the end is reached |
LoopingRepeat Word16 | The animation will repeat n times before stoping |
HDR
High-dynamic-range image with .hdr
or .pic
extension.
Instances
JPG
Joint Photographic Experts Group image with .jpg
or .jpeg
extension.
Instances
data WriteOptionsJPG Source #
Instances
Show WriteOptionsJPG Source # | |
Defined in Data.Massiv.Array.IO.Image.JuicyPixels showsPrec :: Int -> WriteOptionsJPG -> ShowS # show :: WriteOptionsJPG -> String # showList :: [WriteOptionsJPG] -> ShowS # | |
Default WriteOptionsJPG Source # | |
Defined in Data.Massiv.Array.IO.Image.JuicyPixels def :: WriteOptionsJPG # |
woSetQualityJPG :: Word8 -> WriteOptionsJPG -> WriteOptionsJPG Source #
Set the image quality, supplied value will be clamped to [0, 100]
range. This setting directly affects the Jpeg compression level.
PNG
Portable Network Graphics image with .png
extension.
Instances
TGA
Truevision Graphics Adapter image with .tga extension.
Instances
TIF
Tagged Image File Format image with .tif
or .tiff
extension.
Instances
JuciyPixels conversion
To JuicyPixels
toAnyCS :: forall r' cs' e' r cs e. (Source r' Ix2 (Pixel cs' e'), Mutable r Ix2 (Pixel cs e), ColorSpace cs e, ToYA cs' e', ToRGBA cs' e', ToHSIA cs' e', ToCMYKA cs' e', ToYCbCrA cs' e') => Image r' cs' e' -> Maybe (Image r cs e) Source #
toJPImageRGBA8 :: Source r Ix2 (Pixel RGBA Word8) => Image r RGBA Word8 -> Image PixelRGBA8 Source #
toJPImageRGB16 :: Source r Ix2 (Pixel RGB Word16) => Image r RGB Word16 -> Image PixelRGB16 Source #
toJPImageRGBA16 :: Source r Ix2 (Pixel RGBA Word16) => Image r RGBA Word16 -> Image PixelRGBA16 Source #
toJPImageYCbCr8 :: Source r Ix2 (Pixel YCbCr Word8) => Image r YCbCr Word8 -> Image PixelYCbCr8 Source #
toJPImageCMYK8 :: Source r Ix2 (Pixel CMYK Word8) => Image r CMYK Word8 -> Image PixelCMYK8 Source #
toJPImageCMYK16 :: Source r Ix2 (Pixel CMYK Word16) => Image r CMYK Word16 -> Image PixelCMYK16 Source #
From JuicyPixels
fromDynamicImage :: forall cs e. ColorSpace cs e => DynamicImage -> Maybe (Image S cs e) Source #
fromAnyDynamicImage :: (Mutable r Ix2 (Pixel cs e), ColorSpace cs e) => DynamicImage -> Maybe (Image r cs e) Source #
Netpbm formats
PBM
Netpbm: portable bitmap image with .pbm
extension.
Instances
PGM
Netpbm: portable graymap image with .pgm
extension.
Instances
PPM
Netpbm: portable pixmap image with .ppm
extension.