Images have become an important part of modern web design. They draw attention, trigger emotions and could make for the perfect atmosphere on a website. You could just serve the original image and use CSS to display it as you see fit. However this does impact the load time for your webpage and uses unnecessarily much bandwidth. So having your images available in the right size would be best for you and your visitors. ## How? There are a couple of packages available to do image processing in Haskell, for this article we will be using [`JuicyPixels`](https://hackage.haskell.org/package/JuicyPixels) and [`friday`](https://hackage.haskell.org/package/friday) with the bridge package [`friday-juicypixels`](https://hackage.haskell.org/package/friday-juicypixels). We will combine those packages with scotty to create a small web-application which will respond to routes with the following format: `/images/:size/:file` where `:size` is a predefined named size and `:file` the name of a file available on the filesystem. Internally this application will check if a cached version of the requested size already exists and serve this to save time. However is a cached version does not exist it will look up the original, crop it to the required dimensions and then resizes it to match the requested size and cache the newly computed image. *We will only handle jpeg images in this article but with a bit of tinkering it should not be hard to support other formats too.* ## Setup Let's create a simple Haskell application with [`stack`](https://www.haskellstack.org/), create a folder to store our images in and add the applications dependencies to the `.cabal` file. ``` sh stack --version #> Version 1.1.2 x86_64 hpack-0.14.0 stack new on-demand-images simple --resolver lts-6.14 cd on-demand-images mkdir images ``` Beside the image processing and web-application dependencies we will also be using: - [`flow`](https://hackage.haskell.org/package/flow) - [`directory`](https://hackage.haskell.org/package/directory) - [`text`](https://hackage.haskell.org/package/text) The `build-depends` should look like this: ``` yaml build-depends: base >= 4.7 && < 5 , JuicyPixels , directory , flow , friday , friday-juicypixels , scotty , text ``` Because `friday` and `friday-juicypixels` are not available on Stackage we need to add them in `stack.yml` as `extra-deps`. They also require an other dependency which is not included in Stackage, which is `ratio-int`, so add that one too. ``` yaml extra-deps: - friday-0.2.2.0 - friday-juicypixels-0.1.1 - ratio-int-0.1.2 ``` All of those dependencies should be imported in `src/Main.hs`. I like to import most dependencies as `qualified` so it's always clear from which package a function comes and it also avoids naming collisions, but feel free to do it your own way. ``` haskell import qualified Codec.Picture as JP import qualified Codec.Picture.Types as JP import qualified Control.Monad.IO.Class as IO import qualified Data.Text.Lazy as Text import Flow import qualified System.Directory as Dir import qualified Vision.Image as Friday import qualified Vision.Image.JuicyPixels as Friday import qualified Vision.Primitive as Friday import qualified Web.Scotty as Scotty ``` For convenience we also insert `OverloadedStrings` and `RecordWildCards` at the beginning of `src/Main.hs`. ``` haskell {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE RecordWildCards #-} ``` ## Defining available sizes For this article we will keep it simple and allow the application to respond to two sizes: `Thumbnail` and `Header`. However it will be **very** easy to add new sizes whenever you want to. We want those sizes to be type-safe so let's define them as `data`. I also added and derived `Enum` and `Bounded` instance because those will be needed later on. ``` haskell data Size = Thumbnail | Header deriving (Enum, Bounded) ``` Now it would be nice to actually give those `Size`'s some dimensions to work with. So why not create a function `dimensions` which returns a `Tuple` with the width and height for the size. While we are at it we might just as well create a `width` and `height` function too. ``` haskell -- dimensions given as (width, height) dimensions :: Size -> (Int, Int) dimensions Thumbnail = (200, 200) dimensions Header = (600, 300) height :: Size -> Int height = snd . dimensions width :: Size -> Int width = fst . dimensions ``` Because we need to create a cache directory for each image size and we want `scotty` to read the size from the url we have to define the slugs for all our sizes. We could just derive `Show` on `Size` but that would result in the urls having a capitalised path piece which I don't like. So we will define the `Show` instance manually and use this as input for the `Scotty.Parsable` instance which `scotty` requires. ``` haskell instance Show Size where show Thumbnail = "thumbnail" show Header = "header" ``` The `Scotty.Parsable Size` instance requires the `parseParam` function to be implemented which should return an `Either Text Size` where the `Text` is a custom error message. To keep this dynamic we will use the `Show` and `Bounded` instances of Size so we will not have to touch this piece of code ever again! The `Bounded` class exposes a `minBound` and `maxBound` function which we can use to create a list of all available sizes without having to write them all out again. With this list we create a dictionary from which we can lookup the actual type for a size slug. If the lookup succeeds we return the type and otherwise we return the error message `Invalid size`. ``` haskell instance Scotty.Parsable Size where parseParam size = maybe (Left "Invalid size") Right $ lookup size sizes where sizes :: [(Text.Text, Size)] sizes = map (\s -> (Text.pack $ show s, s)) [minBound..maxBound] ``` Adding a new size would be as easy as adding it to the data type, define the dimensions and add the slug to the `Show` instance. ## Building the route handler Our application will just handle a single route (`/images/:size/:file`), so we are going to use a minimal `scotty` implementation which is going to run the application on port 3000. Because this is the only thing our application is going to do we will put this directly in the modules `main` function. The handler will retrieve the `:size` and `:file` parameters from the url, check if an original exists for the requested image, check the cache and when required generate the new image size. When `scotty` fails to read the size from the url it will stop the execution of the handler and return a 404. If anything unexpected happens while reading or creating a cached image a 500 with the error message `Could not process the requested image` is returned. ``` haskell main :: IO () main = Scotty.scotty 3000 $ do Scotty.get "/images/:size/:file" $ do size <- Scotty.param "size" file <- Scotty.param "file" requireOriginal file p <- IO.liftIO $ readOrCreateCachedImage size file case p of Just path -> Scotty.file path Nothing -> Scotty.raise "Could not process the requested image" ``` Next we are going to perform some actions on the filesystem so let's define some helpers to avoid mistakes. Defining the path structure for our original images and the cached sizes should be enough. ``` haskell imgDir :: FilePath imgDir = "./images/" sizeDir :: Size -> FilePath sizeDir s = imgDir ++ show s ++ "/" ``` Now it's time to implement the `requireOriginal` function which we already used in the route handler. All this function should do is check if an original exists for the requested image, if an original is not present it should stop the execution of the handler (which results in a 404). ``` haskell requireOriginal :: FilePath -> Scotty.ActionM () requireOriginal file = do doesExist <- IO.liftIO . Dir.doesFileExist $ imgDir ++ file if doesExist then return () else Scotty.next ``` Having made sure we only ever try to handle sizes for images that have an original we should now implement `readOrCreateCachedImage`. This function will check if a cached version of the image already exists for the requested size. If the cached image exists we return the path on the filesystem where it's stored and otherwise try to generate it. When generation succeeds continue by also returning the path, on a failure we return `Nothing`. ``` haskell readOrCreateCachedImage :: Size -> FilePath -> IO (Maybe FilePath) readOrCreateCachedImage size file = do doesExist <- Dir.doesFileExist path if doesExist then return $ Just path else do generated <- generateSize size file return $ if generated then Just path else Nothing where path = sizeDir size ++ file ``` ## Processing images That leaves us with just the core part of the application to build; the actual processing of the images. Because we went 100% Haskell we use `JuicyPixels` to read the original image from the filesystem and then convert it to something `friday` understands. `friday` on its turn performs the required computations on the original to get to the requested image size before converting it back for `JuicyPixels` to save the cached version. In `readOrCreateCachedImage` we already saw the `generateSize` function. This function starts by reading the original image (which should exist, we checked this). Remember we currently only support jpeg files so placing an image with a different format in `./images/` will result in an error. If the folder for the requested size does not yet exist we should also create it here. To crop the image we need to calculate a rectangle, this is the most complex part of the application and we will get to this in a moment. After cropping its just a case of resizing the image to the size's dimensions and save it. Note that we use the heaviest resize method and save the jpeg with the highest possible quality, faster (first time) responses and smaller file sizes to save additional bandwidth can be achieved by playing with those settings. To tell the caller of `generateSize` whether the processing was successful or not we let it return a `Bool`. ``` haskell generateSize :: Size -> FilePath -> IO Bool generateSize size file = do o <- JP.readJpeg $ imgDir ++ file case o of Right (JP.ImageYCbCr8 image) -> do Dir.createDirectoryIfMissing False $ sizeDir size image |> JP.convertImage |> Friday.toFridayRGB |> Friday.crop (rectFor size image) |> Friday.delayed |> Friday.resize Friday.Bilinear (Friday.ix2 (height size) (width size)) |> Friday.toJuicyRGB |> JP.ImageRGB8 |> JP.saveJpgImage 100 (sizeDir size ++ file) return True _ -> return False ``` Now for the cropping rectangle we need to know if we have to adjust the width or the height of the original. We can find this out by calculating the target and source ratios and comparing them. When calculation the ratio by dividing the height with the width a bigger target ratio means we have to adjust the width. We are also going to center the crop so an adjustment to the width will mean a shift on the x-axis and thus we need to shift the y-axis when we make adjustments to the height. The amount of pixels we need to shift will always be the amount of pixels which are going to be cropped off divided by 2. Note that we first need to convert the widths and heights to `Double`s before doing the calculations or we lose **a lot** of important precision. ``` haskell rectFor :: Size -> JP.Image a -> Friday.Rect rectFor size JP.Image{..} = if targetRatio > srcRatio then Friday.Rect { rX = (imageWidth - newWidth) `div` 2 , rY = 0 , rWidth = newWidth , rHeight = imageHeight } else Friday.Rect { rX = 0 , rY = (imageHeight - newHeight) `div` 2 , rWidth = imageWidth , rHeight = newHeight } where f :: Int -> Double f = fromIntegral targetRatio = f (height size) / f (width size) srcRatio = f imageHeight / f imageWidth newWidth = floor $ (f imageHeight / f (height size)) * f (width size) newHeight = floor $ (f imageWidth / f (width size)) * f (height size) ``` ## Seeing results It's about time we get to build the application and see it in action. ``` sh stack exec on-demand-images ``` The application is now running on port 3000. Put some jpg images in `./images/` and let the application create the image sizes dynamically whenever they are required by visiting `https://localhost:3000/images//.jpg`. The source code for this article is available on [https://gitlab.com/paramander/on-demand-images](https://gitlab.com/paramander/on-demand-images).

With focus on innovation, performance en security. Paramander is your partner for automating your business processes.

Playbrush

Toothbrush subscriptions on Shopify with Stripe Billing for payments

What we've worked on

Parfumado

Playbrush

What's new?

Handle rate limit errors in Shopify Admin GraphQL API using Apollo client

Extending Fishery to build test data for Sequelize models

On demand image processing with Haskell