Diagrams 1.4

The diagrams team is very pleased to announce the release of diagrams 1.4. The release actually happened a few months ago, in October—we just hadn't gotten around to writing about it yet. But in any case this was a fairly quiet release, with very few breaking changes; mostly 1.4 just introduced new features. There is a migration guide which lists a few known potentially breaking changes, but most users should have no trouble. The rest of this post highlights some of the new features in 1.4.

Alignment and layout

Radial tree layout

The existing Diagrams.TwoD.Layout.Tree module from diagrams-contrib has been extended with a new radialLayout function, based on an algorithm by Andy Pavlo.

> import Diagrams.TwoD.Layout.Tree
> import Data.Tree
>
> t = Node 'A'
>     [ Node 'B' (map lf "CDE")
>     , Node 'F' [Node 'G' (map lf "HIJKLM"), Node 'N' (map lf "OPQRS")]
>     , Node 'T' (map lf "UVWXYZ")
>     ]
>   where lf x = Node x []
>
> example =
>    renderTree (\n -> (text (show n) # fontSizeG 0.5
>                             <> circle 0.5 # fc white))
>              (~~) (radialLayout t)
>    # centerXY # frame 0.5

Aligned composition

Sometimes, it is desirable to compose some diagrams according to a certain alignment, but without affecting their local origins. The composeAligned function can be used for this purpose. It takes as arguments an alignment function (such as alignT or snugL), a composition function of type [Diagram] -> Diagram, and produces a new composition function which works by first aligning the diagrams before composing them.

> example :: Diagram B
> example = (hsep 2 # composeAligned alignT) (map circle [5,1,3,2])
>         # showOrigin

The example above shows using hsep 2 to compose a collection of top-aligned circles. Notice how the origin of the composed diagram is still at the center of the leftmost circle, instead of at its top edge (where it would normally be placed by alignT).

Constrained layout

The new Diagrams.TwoD.Layout.Constrained module from diagrams-contrib implements basic linear constraint-based layout. As a simple example of something that would be tedious to draw without some kind of constraint solving, consider this diagram which consists of a vertical stack of circles of different sizes, along with an accompanying set of squares, such that (1) each square is constrained to lie on the same horizontal line as a circle, and (2) the squares all lie on a diagonal line.

> import Diagrams.TwoD.Layout.Constrained
> import Control.Monad (zipWithM_)
>
> example :: Diagram B
> example = frame 1 $ layout $ do
>   let rs = [2,2,4,3,5,6]
>   cirs <- newDias (map circle rs # fc blue)
>   sqs  <- newDias (replicate (length rs) (square 2) # fc orange)
>   constrainWith vcat cirs
>   zipWithM_ sameY cirs sqs
>   constrainWith hcat [cirs !! 0, sqs !! 0]
>   along (direction (1 ^& (-1))) (map centerOf sqs)

See the package documentation for more examples and documentation.

Anchors

Another new module in diagrams-contrib, Diagrams.Anchors, provides a convenient interface for aligning diagrams relative to named anchor points. This can be useful, for example, when laying out diagrams composed of pieces that should "attach" to each other at various points.

We don't have an example of its use at the moment—if you play with it and create a nice example, let us know!

Paths

Boolean path operations

The new Diagrams.TwoD.Path.Boolean module from diagrams-contrib contains functions for computing boolean combinations of paths, such as union, intersection, difference, and symmetric difference.

> import qualified Diagrams.TwoD.Path.Boolean as B
>
> thing1, thing2 :: Path V2 Double
> thing1 = square 1
> thing2 = circle 0.5 # translate (0.5 ^& (-0.5))
>
> example = hsep 0.5 . fc green . map strokePath $
>   [ B.union        Winding (thing1 <> thing2)
>   , B.intersection Winding thing1     thing2
>   , B.difference   Winding thing1     thing2
>   , B.exclusion    Winding thing1     thing2
>   ]

Cubic B-splines

Diagrams.CubicSpline has a new function, bspline, which creates a smooth curve (to be precise, a [uniform cubic B-spline](https://en.wikipedia.org/wiki/B-spline)) with the given points as control points. The curve begins and ends at the first and last points, and is tangent to the lines to the second-to-last control points. It does not, in general, pass through the intermediate control points.

> pts = map p2 (zip [0 .. 8] (cycle [0, 1]))
> example = mconcat
>   [ bspline pts
>   , mconcat $ map (place (circle 0.1 # fc blue # lw none)) pts
>   ]

One major difference between cubicSpline and bspline is that the curves generated by cubicSpline depend on the control points in a global way—that is, changing one control point could alter the entire curve—whereas with bspline, each control point only affects a local portion of the curve.

Following composition

diagrams-contrib has a new module, Diagrams.TwoD.Path.Follow, which defines a wrapper type Following n. Following is just like Trail' Line V2, except that it has a different Monoid instance: following values are concatenated, just like regular lines, except that they are also rotated so the tangents match at the join point. In addition, they are normalized so the tangent at the start point is in the direction of the positive \(x\) axis (essentially we are considering trails equivalent up to rotation).

> import Control.Lens (ala)
> import Diagrams.TwoD.Path.Follow
>
> wibble :: Trail' Line V2 Double
> wibble = hrule 1 <> hrule 0.5 # rotateBy (1/6) <> hrule 0.5 # rotateBy (-1/6) <> a
>   where a = arc (xDir # rotateBy (-1/4)) (1/5 @@ turn)
>           # scale 0.7
>
> example =
>   [ wibble
>   , wibble
>     # replicate 5
>     # ala follow foldMap
>   ]
>   # map stroke
>   # map centerXY
>   # hsep 1
>   # frame 0.3

Notice how the above example makes use of the ala combinator from Control.Lens to automatically wrap all the Lines using follow before combining and then unwrap the result.

Fun

L-systems

The new module Diagrams.TwoD.Path.LSystem in diagrams-contrib draws L-systems described by recursive string rewriting rules, and provides a number of examples that can be used as starting points for exploration.

> import           Diagrams.TwoD.Path.LSystem
> import qualified Data.Map as M
>
> tree :: RealFloat n => Int -> TurtleState n
> tree n = lSystem n (1/18 @@ turn) (symbols "F") rules
>  where
>    rules  = M.fromList [rule 'F' "F[+>>>F]F[->>>F][>>>F]"]
>
> example = getTurtleDiagram $ tree 6

This example is already provided by the module as tree2.

XKCD colors

Randall Munroe, of xkcd fame, ran a survey to determine commonly used names for colors, and published a list of the 954 most common colors based on the results. Diagrams.Color.XKCD from diagrams-contrib provides all these color names.

> import Diagrams.Color.XKCD
>
> colors = [booger, poisonGreen, cinnamon, petrol, vibrantPurple]
> example = hsep 0.1 (zipWith fcA colors (repeat (circle 1 # lw none)))

Diagrams + Cairo + Gtk + Mouse picking, reloaded

A little over a year ago, Christopher Mears wrote a nice article on how to match up mouse clicks in a GTK window with parts of a diagram. The only downside was that to make it work, you had to explicitly construct the diagram in such a way that its coordinate system precisely matched the coordinates of the window you wanted to use, so that there was essentially no "translation" to do. This was unfortunate, since constructing a diagram in a particular global coordinate system is not a very "diagrams-y" sort of thing to do. However, the 1.3 release of diagrams includes a new feature that makes matching up mouse clicks and diagrams much easier and more idiomatic, and I thought it would be worth updating Chris's original example to work more idiomatically in diagrams 1.3. The complete code is listed at the end.

First, here's how we construct the house. This is quite different from the way Chris did it; I have tried to make it more idiomatic by focusing on local relationships of constituent pieces, rather than putting everything at absolute global coordinates. We first create all the constituent pieces:

> -- The diagram to be drawn, with features tagged by strings.
> prettyHouse :: QDiagram Cairo V2 Double [String]
> prettyHouse = house
>   where
>     roof    = triangle 1   # scaleToY 0.75 # centerY # fc blue
>     door    = rect 0.2 0.4 # fc red
>     handle  = circle 0.02  # fc black
>     wall    = square 1     # fc yellow
>     chimney = fromOffsets [0 ^& 0.25, 0.1 ^& 0, 0 ^& (-0.4)]
>             # closeTrail # strokeT # fc green
>             # centerX
>             # named "chimney"
>     smoke = mconcat
>       [ circle 0.05 # translate v
>       | v <- [ zero, 0.05 ^& 0.15 ]
>       ]
>       # fc grey

We then put the pieces together, labelling each by its name with the value function. Diagrams can be valuated by any monoid; when two diagrams are combined, the value at each point will be the mappend of the values of the two component diagrams. In this case, each point in the final diagram will accumulate a list of Strings corresponding to the pieces of the house which are under that point. Note how we make use of combinators like vcat and mconcat, alignments like alignB, snugL and snugR, and the use of a named subdiagram (the chimney) to position the components relative to each other. (You can click on any of the above function names to go to their documentation!)

>     house = vcat
>       [ mconcat
>         [ roof    # snugR                   # value ["roof"]
>         , chimney # snugL                   # value ["chimney"]
>         ]
>         # centerX
>       , mconcat
>         [ handle  # translate (0.05 ^& 0.2) # value ["handle"]
>         , door    # alignB                  # value ["door"]
>         , wall    # alignB                  # value ["wall"]
>         ]
>       ]
>       # withName "chimney" (\chim ->
>           atop (smoke # moveTo (location chim) # translateY 0.4
>                       # value ["smoke"]
>                )
>         )

Now, when we render the diagram to a GTK window, we can get diagrams to give us an affine transformation that mediates between the diagram's local coordinates and the GTK window's coordinates. I'll just highlight a few pieces of the code; the complete listing can be found at the end of the post. We first create an IORef to hold the transformation:

>   gtk2DiaRef <- (newIORef mempty :: IO (IORef (T2 Double)))

We initialize it with the identity transformation. We use the renderDiaT function to get not only a rendering action but also the transformation from diagram to GTK coordinates; we save the inverse of the transformation in the IORef (since we will want to convert from GTK to diagram coordinates):

>     let (dia2gtk, (_,r)) = renderDiaT Cairo
>                              (CairoOptions "" (mkWidth 250) PNG False)
>                              prettyHouse
>
>     -- store the inverse of the diagram -> window coordinate transformation
>     -- for later use in interpreting mouse clicks
>     writeIORef gtk2DiaRef (inv dia2gtk)

(Note that if it is possible for the first motion notify event to happen before the expose event, then such mouse motions will be computed to correspond to the wrong part of the diagram, but who cares.) Now, when we receive a mouse click, we apply the stored transformation to convert to a point in diagram coordinates, and pass it to the sample function to extract a list of house components at that location.

>     (x,y) <- eventCoordinates
>
>     -- transform the mouse click back into diagram coordinates.
>     gtk2Dia <- liftIO $ readIORef gtk2DiaRef
>     let pt' = transform gtk2Dia (p2 (x,y))
>
>     liftIO $ do
>       putStrLn $ show (x,y) ++ ": "
>                    ++ intercalate " " (sample prettyHouse pt')

The final product ends up looking and behaving identically to the video that Chris made.

Finally, here's the complete code. A lot of it is just boring standard GTK setup.

> import           Control.Monad                   (void)
> import           Control.Monad.IO.Class          (liftIO)
> import           Data.IORef
> import           Data.List                       (intercalate)
> import           Diagrams.Backend.Cairo
> import           Diagrams.Backend.Cairo.Internal
> import           Diagrams.Prelude
> import           Graphics.UI.Gtk
>
> main :: IO ()
> main = do
>   -- Ordinary Gtk setup.
>   void initGUI
>   w <- windowNew
>   da <- drawingAreaNew
>   w `containerAdd` da
>   void $ w `on` deleteEvent $ liftIO mainQuit >> return True
>
>   -- Make an IORef to hold the transformation from window to diagram
>   -- coordinates.
>   gtk2DiaRef <- (newIORef mempty :: IO (IORef (T2 Double)))
>
>   -- Render the diagram on the drawing area and save the transformation.
>   void $ da `on` exposeEvent $ liftIO $ do
>     dw <- widgetGetDrawWindow da
>
>     -- renderDiaT returns both a rendering result as well as the
>     -- transformation from diagram to output coordinates.
>     let (dia2gtk, (_,r)) = renderDiaT Cairo
>                              (CairoOptions "" (mkWidth 250) PNG False)
>                              prettyHouse
>
>     -- store the inverse of the diagram -> window coordinate transformation
>     -- for later use in interpreting mouse clicks
>     writeIORef gtk2DiaRef (inv dia2gtk)
>
>     renderWithDrawable dw r
>     return True
>
>   -- When the mouse moves, show the coordinates and the objects under
>   -- the pointer.
>   void $ da `on` motionNotifyEvent $ do
>     (x,y) <- eventCoordinates
>
>     -- transform the mouse click back into diagram coordinates.
>     gtk2Dia <- liftIO $ readIORef gtk2DiaRef
>     let pt' = transform gtk2Dia (p2 (x,y))
>
>     liftIO $ do
>       putStrLn $ show (x,y) ++ ": "
>                    ++ intercalate " " (sample prettyHouse pt')
>       return True
>
>   -- Run the Gtk main loop.
>   da `widgetAddEvents` [PointerMotionMask]
>   widgetShowAll w
>   mainGUI
>
> -- The diagram to be drawn, with features tagged by strings.
> prettyHouse :: QDiagram Cairo V2 Double [String]
> prettyHouse = house
>   where
>     roof    = triangle 1   # scaleToY 0.75 # centerY # fc blue
>     door    = rect 0.2 0.4 # fc red
>     handle  = circle 0.02  # fc black
>     wall    = square 1     # fc yellow
>     chimney = fromOffsets [0 ^& 0.25, 0.1 ^& 0, 0 ^& (-0.4)]
>             # closeTrail # strokeT # fc green
>             # centerX
>             # named "chimney"
>     smoke = mconcat
>       [ circle 0.05 # translate v
>       | v <- [ zero, 0.05 ^& 0.15 ]
>       ]
>       # fc grey
>     house = vcat
>       [ mconcat
>         [ roof    # snugR                  # value ["roof"]
>         , chimney # snugL                  # value ["chimney"]
>         ]
>         # centerX
>       , mconcat
>         [ handle  # translate (0.05 ^& 0.2) # value ["handle"]
>         , door    # alignB                  # value ["door"]
>         , wall    # alignB                  # value ["wall"]
>         ]
>       ]
>       # withName "chimney" (\chim ->
>           atop (smoke # moveTo (location chim) # translateY 0.4
>                       # value ["smoke"]
>                )
>         )

Diagrams 1.3

The diagrams team is very pleased to announce the release of diagrams 1.3. The actual release to Hackage happened a week or so ago, and by now I think we have most of the little kinks ironed out. This is an exciting release that represents a great deal of effort from a lot of people (see the list of contributors at the end of this post). Here's a quick rundown of some of the new features. If you're just looking for help porting your diagrams code to work with 1.3, see the migration guide.

Path intersection

Using the functions intersectPointsP and intersectPointsT, it is now possible to find the points of intersection between two paths or two trails, respectively. This is not so hard for paths with straight segments, but for cubic Bezier curves, finding intersection points is nontrivial!

> {-# LANGUAGE TupleSections #-}
>
> example :: Diagram B
> example = mconcat (map (place pt) points) <> mconcat ellipses
>   where
>     ell = circle 1 # scaleX 2
>     pt  = circle 0.05 # fc blue # lw none
>     ellipses = [ ell # rotateBy r # translateX (2*r) | r <- [0, 1/12 .. 5/12] ]
>     points = allPairs ellipses >>= uncurry (intersectPointsP' 1e-8)
>     allPairs [] = []
>     allPairs (x:xs) = map (x,) xs ++ allPairs xs

Note that this feature is something of a "technology preview" in diagrams 1.3: the API will probably change and grow in the next release (for example, giving a way to find the parameters of intersection points).

Affine maps and projections

Affine maps have been added to Diagrams.LinearMap that can map between different vector spaces. The Deformable class has also been generalised to map between spaces. Helper functions have been added to Diagrams.ThreeD.Projection for basic orthographic and perspective projections.

In the below example, we construct a 3-dimensional path representing the wireframe of a simple house, and then project it into 2 dimensions using perspective, orthographic, and isometric projections.

> import Diagrams.ThreeD.Transform  (translateZ)
> import Diagrams.ThreeD.Projection
> import Diagrams.LinearMap         (amap)
> import Linear.Matrix              ((!*!))
>
> box :: Path V3 Double
> box = Path [f p1 ~~ f p2 | p1 <- ps, p2 <- ps, quadrance (p1 .-. p2) == 4]
>   where
>     ps = getAllCorners $ fromCorners (-1) 1
>     f  = fmap fromIntegral
>
> roof :: Path V3 Double
> roof = Path
>   [ mkP3 1 1 1       ~~ mkP3 1 0 1.4
>   , mkP3 1 (-1) 1    ~~ mkP3 1 0 1.4
>   , mkP3 1 0 1.4     ~~ mkP3 (-1) 0 1.4
>   , mkP3 (-1) 1 1    ~~ mkP3 (-1) 0 1.4
>   , mkP3 (-1) (-1) 1 ~~ mkP3 (-1) 0 1.4
>   ]
>
> door :: Path V3 Double
> door = fromVertices
>   [ mkP3 1 (-0.2) (-1)
>   , mkP3 1 (-0.2) (-0.4)
>   , mkP3 1 (0.2) (-0.4)
>   , mkP3 1 (0.2) (-1)
>   ]
>
> house = door <> roof <> box
>
> -- Perspective projection
> -- these bits are from Linear.Projection
> m  = lookAt (V3 3.4 4 2.2) zero unitZ
> pm = perspective (pi/3) 0.8 1 3 !*! m
>
> pd = m44Deformation pm
> perspectiveHouse = stroke $ deform pd (translateZ (-1) house)
>
> -- Orthogonal projection
> am = lookingAt (mkP3 3.4 4 2.2) zero zDir
> orthogonalHouse = stroke $ amap am house
>
> -- Isometric projection (specialised orthogonal)
> isometricHouse = stroke $ isometricApply zDir house
>
> example :: Diagram B
> example = hsep 1 . map (sized (mkHeight 3) . centerXY) $
>   [ perspectiveHouse, orthogonalHouse, isometricHouse ]

Note that this should also be considered a "technology preview". Future releases of diagrams will likely include higher-level ways to do projections.

Grouping for opacity

A few backends (diagrams-svg, diagrams-pgf, and diagrams-rasterific as of version 1.3.1) support grouped transparency. The idea is that transparency can be applied to a group of diagrams as a whole rather than to individual diagrams. The difference is in what happens when diagrams overlap: if they are individually transparent, the overlapping section will be darker, as if two pieces of colored cellophane were overlapped. If transparency is applied to a group instead, the transparency is uniformly applied to the rendered output of the group of diagrams, as if a single piece of colored cellophane were cut out in the shape of the group of diagrams.

An example should help make this clear. In the example to the left below, the section where the two transparent circles overlap is darker. On the right, the call to groupOpacity means that the entire shape formed form the union of the two circles is given a uniform opacity; there is no darker region where the circles overlap.

> cir = circle 1 # lw none # fc red
> overlap = (cir <> cir # translateX 1)
>
> example = hsep 1 [ overlap # opacity 0.3, overlap # opacityGroup 0.3 ]
>           # centerX
>        <> rect 9 0.1 # fc lightblue # lw none

Visualizing envelopes and traces

Some new functions have been added to help visualize (approximations of) the envelope and trace of a diagram. For example:

> d1, d2 :: Diagram B
> d1 = circle 1
> d2 = (pentagon 1 === roundedRect 1.5 0.7 0.3)
>
> example = hsep 1
>   [ (d1 ||| d2)          # showEnvelope' (with & ePoints .~ 360) # showOrigin
>   , (d1 ||| d2) # center # showEnvelope' (with & ePoints .~ 360) # showOrigin
>   , (d1 ||| d2) # center # showTrace' (with & tPoints .~ 20) # showOrigin
>   ]

Introducing the Palette Package, Part II

In part 1 of this post we talked mostly about borrowing a set of colors that was made by someone else. In this part we talk about tools we can use to make our own color schemes.

Most software provides some type of color picker for selecting a single color. To choose a color we are often given the choice between several different color panels, including a clolor wheel, color sliders, and others. The sliders metaphor works well for choosing a single color, but it doesn't provide us with an intuitive way to choose a color scheme.

The color wheel is more promising. A color wheel is designed to have pure hues on the perimeter, that means saturation and brightness are set to 100%. If you look at this type of color wheel, that is one based on HSB or HSL, you will notice that the red, green and blue sections are 120 degrees apart. If you look at Adobe Kuler on the other hand you will see that red and green lie on oposite poles of the wheel. That's a better way to visualize the color wheel since red and green are complimentary colors (They produce black or white when combined in the correct proportions). Complimentary colors

The point is that when picking colors for a scheme, tradional color harmony defines which colors are chosen by choosing a base color and other colors on the wheel at specific angles apart. The wheel that is used though is one with complimentary colors opposite each other like in Kuler. This is the so called traditional or artist's color wheel. We call it the RYB (red, yellow, blue) wheel since it is based on those three being the primary colors and colors in between as mixtures of those.

The RYB color wheel and the color schemes we will design below are easy to view using the wheel function. wheel takes a list of colors and makes a color wheel out of them by placing the first color in the list at the top of the wheel.

> wheel cs = wheel' # rotate r
>   where
>     wheel' = mconcat $ zipWith fc cs (iterateN n (rotate a) w)
>     n = length cs
>     a = 1 / (fromIntegral n) @@ turn
>     w = wedge 1 xDir a # lwG 0
>     r = (1/4 @@ turn)  ^-^  (1/(2*(fromIntegral n)) @@ turn)

Here is the RYB color wheel. Notice that colors we perceive as opposites, e.g. red and green are 180 degrees apart on the wheel. In harmony the RYB color wheel is created by shrinking and stretching sections of the HSB color wheel so that complimentary colors are always on opposite sides of the wheel.

> ryb = [rybColor n | n <- [0..23]]
> example = wheel ryb

Although we have described the base color as a pure hue, we are actually free to choose any color we like at the base color. In order to create the harmonies we desire, we want a function that takes a given color and returns the color a certain number of degrees away on the RYB wheel. For that harmony provides the function rotateColor. Here is the original d3 color set and the same set rotated by 60 degrees (counter clockwise).

> d3 = [d3Colors1 n | n <- [0..9]]
> example = hcat' (with & sep .~ 0.5) [bar d3, bar $ map (rotateColor 60) d3]

Let's pick a base color to demonstrate the classic color harmonies and how to use the Harmony functions. How about a nice mustardy yellow "#FFC200".

Since we have been talking about complimentary colors, the first scheme we describe is unsurprisingly called Complimentary. It's based on two complimentary colors and in the Harmmony module three other colors are choosen by shading and tinting those two colors.

> example = hcat' (with & sep .~ 0.5) [ bar (take 2 (complement base))
>                                     , wheel $ complement base]

A Monochromatic color harmony consists of the base color plus various tints, shades and tones.

> example = wheel $ monochrome base

The following scheme does not have a name as far as I know. We take the base color and mix a little bit of it into black, grey, and white. In Harmony the function is called bwg.

> example = wheel $ bwg base

Sometimes it is useful to view a color scheme like a wheel but with the base color as a disc in the center. We define the function pie for this purpose.

> pie (c:cs) = ring <> center
>   where
>     center = circle 0.5 # fc c # lwG 0
>     ring = mconcat $ zipWith fc cs (iterateN n (rotate a) w)
>     n = length cs
>     a = 1 / (fromIntegral n) @@ turn
>     w = annularWedge 0.5 1 xDir a # lwG 0

The Analogic color scheme is the base color plus the two colors 30 degrees apart on each side. As usual we add in some tints, shades, and tones to fill out a 5 color scheme. Accent Analogic is similar but we add in the color complimentary to the base color.

> example = hcat' (with & sep .~ 0.5) [ pie $ analogic base
>                                     , pie $ accentAnalogic base]

The lase two schemes provided by Harmony are Triad, with colors 120 degrees apart and Tetrad with colors on the corners of a rectangle inscribed in the color wheel.

> example = hcat' (with & sep .~ 0.5) [ pie $ triad base
>                                     , pie $ tetrad base]

Introducing the Palette Package, Part I

Choosing a set of colors that look good together can be quite a challenge. The task comes up in a variety of different contexts including: webiste design, print design, cartography, and as we will discuss here, making diagrams. The problem comes down to a balancing act between two issues; first is that the choosen set of colors is asthetically pleasing, and second is that there is enough contrast between them.

The easiest approach is to borrow a set of colors from someone who has already put in the time and effort to create it. The Palette package "Data.Colour.Palette.ColorSet" provides access to a few different predefined color sets including the ones in d3 and the package "Data.Colour.Palette.BrewerSet" contains a large variety of color schemes created by Cynthia Brewer for use in map making see colorbrewer 2.0.

Let's start out by building some tools in Diagrams, the Haskell drawing framework. We will use the golden ration to give us some pleasing proportions.

> gr = (1 + sqrt 5) / 2

The function bar takes a list of colors which we define here as [Colour Double] (we often use the type synonym [Kolor]). We set the length of the color bar to the golden ratio and the height to 1.

> bar cs = hcat [square gr # scaleX s # fc k # lwG 0 | k <- cs] # centerXY
>   where s = gr / (fromIntegral (length cs))

We can use bar to view the color sets in Palette. Let's make a few color bars. We will use functions provided in Palette to make the color lists and then use bar to make the diagrams. The function d3Colors1 takes an Int between 0 and 9 and returns a color from the set.

> d3 = [d3Colors1 n | n <- [0..9]]
> example = bar d3

The function we use to access schemes from Data.Colour.Palette.Brewerset is brewerSet. It takes two arguments: the category of the set ColorCat (see the haddocks documentation for a list of categories), and an integer representing how many colors in the set. The sets are divided up into 3 categories primarily for showing different types of data on a map: sequential, diverging and qualitative. But they are useful for making diagrams as well.

> gb = bar $ brewerSet GnBu 9    -- green/blue, sequential multihue
> po = bar $ brewerSet PuOr 11   -- purple/orange, diverging
> bs = bar $ brewerSet Paired 11 -- qualitative
> example = hcat' (with & sep .~ 0.5) [gb, po, bs]

Some of the color sets provided in ColorSet occur with 2 or 4 brightness levels. data Brightness = Darkest | Dark | Light | Lightest with Darkest == Dark and similarly for Light when using a two set variant. The grid function is useful for visualizing these.

grid takes a nested list of colors [[Kolor]] and returns a grid of vertically stacked bars.

> grid cs = centerXY $ vcat [bar c # scaleY s | c <- cs]
>   where s = 1 / (fromIntegral (length cs))
>
> d3Pairs = [[d3Colors2  Dark  n | n <- [0..9]], [d3Colors2 Light n | n <- [0..9]]]
> g2 = grid d3Pairs
>
> d3Quads = [[d3Colors4 b n | n <- [0..9]] | b <- [Darkest, Dark, Light, Lightest]]
> g4 = grid d3Quads
> example = hcat' (with & sep .~ 0.5) [g2, g4]

The are over 300 colors that W3C recommends that every browser support. These are usually list in alphabetical order, which needless to say does not separate similar colors well. Palette provides the function webColors which takes an integer n returns the n th color in a list which has first been sorted by hue and then travesed by skiping every 61 elements. This cycles through a good amount of colors before repeating similar hues. The variant infiniteWebColors recycles this list. When using these colors it's a good idea to pick some random starting point and increment the color number by 1 every time a new color is required.

> web = [[webColors (19 * j + i) | i <- [0..8]] | j <- [0..8]]
> w1 = grid web
>
> web2 = [[webColors (19 * j + i) | i <- [0..19]] | j <- [0..14]]
> w2 = grid web2
> example = hcat' (with & sep .~ 0.5) [w1, w2]

If none of the above color schemes suit your purposes or if you just want to create your own - use the functions in Data.Colour.Palette.Harmony. The module provides some basic functions for adjusting colors plus a progammatic interface to tools like Adobe Kuler and Color Scheme Designer. We'll finish Part 1 of this post by examining some of the functions provided to tweak a color: shade, tone and tint. These three functions mix a given color with black, gray, and white repsectively. So if for example we wanted a darker version of the d3 scheme, we can apply a shade. Or we can add some gray to the brewer set GnBu from above.

> s = bar $ map (shade 0.75) d3
> t = bar $ map (tone 0.65) (brewerSet GnBu 9)
> example = hcat' (with & sep .~ 0.5) [s, t]

In part II we will talk just a bit about color theory and explain more of the fucntions in Harmony.