Graphics.Rendering.Diagrams

An embedded domain-specific language (EDSL) for creating simple diagrams, built on top of the Cairo rendering engine.

Introduction

Graphics.Rendering.Diagrams is an embedded domain-specific language (EDSL) for creating simple diagrams. It is compositional; starting with some basic shapes, you can build up complex diagrams by combining simpler diagrams in various ways.

A few fundamental concepts to keep in mind:

• When constructing diagrams, there is no concept of an absolute coordinate system; everything is relative. You cannot say "this diagram should go at (2,1)"; you can only say "this diagram should go to the right of this other one", or "this diagram should go two units to the right and one unit above where it would otherwise be".
• Every diagram has an associated rectangular bounding box, which determines its positioning and alignment relative to other diagrams. Usually this makes no difference but there are times when it's nice to be aware of it. For example, translating a diagram works by moving the diagram relative to its bounding box; positioning the bounding box where it would have gone means the diagram itself ends up elsewhere. Also, some shapes have non-obvious bounding boxes; for example, regular polygons have a bounding box that fits their circumcircle.
• The positive y-axis points downwards.

For some simple examples, see http://byorgey.wordpress.com/2008/04/30/new-haskell-diagrams-library/.

Enjoy! Please send comments, suggestions, bug reports, or patches to byorgey at gmail dot com.

Primitives

data Diagram

Diagram is the core data type which describes a diagram. Diagrams may be constructed, transformed, combined, and ultimately rendered as an image.

nil :: Diagram

The nil diagram, which takes up no space and produces no output.

Shapes

circle :: Double -> Diagram

circle r is a circle with radius r.

poly :: Int -> Double -> Diagram

poly n r is a regular n-gon, with a circumcircle of radius r. One vertex is oriented along the positive x-axis. Note that the bounding box is the square circumscribed around the circumcircle.

rect :: Double -> Double -> Diagram

rect w h is a rectangle of width w and height h.

shape :: ShapeClass s => s -> Diagram

Create a Diagram out of any instance of ShapeClass.

Spacers

hspace :: Double -> Diagram

hspace w is a Diagram which produces no output but takes up w amount of space horizontally. Useful for manually creating horizontal separation between two diagrams. A negative value of w can also be used to move two diagrams closer to one another. hspace w is equivalent to empty w 0.

vspace :: Double -> Diagram

vspace h is a Diagram which produces no output but takes up h amount of space vertically. Useful for manually creating vertical separation between two diagrams. A negative value of h can also be used to move two diagrams closer to one another. vspace h is equivalent to empty 0 h.

empty :: Double -> Double -> Diagram

empty w h is an empty diagram which produces no output, but takes up an amount of space equal to a w by h rectangle.

Combinators

Union

(##) :: Diagram -> Diagram -> Diagram

Superimpose one diagram atop another. d1 d2 results in a diagram in which d2 is on top of d1 (i.e., d1 is drawn first, then d2).

union :: [Diagram] -> Diagram

Create a Diagram as a union of subdiagrams which will not be repositioned. If the subdiagrams overlap, they will appear with the first Diagram on the bottom, and the last on top.

unionA :: HAlignment -> VAlignment -> [Diagram] -> Diagram

Create a Diagram as a union of subdiagrams superimposed on one another, aligned vertically and/or horizontally.

Lists

(<>) :: Diagram -> Diagram -> Diagram

d1 d2 is a Diagram with d1 to the left of d2, aligned along their top edges.

(//) :: Diagram -> Diagram -> Diagram

d1 d2 is a Diagram with d1 above d2, aligned along their left edges.

hcat :: [Diagram] -> Diagram

Lay out a list of Diagrams horizontally from left to right, aligned along their top edges.

vcat :: [Diagram] -> Diagram

Lay out a list of Diagrams vertically from top to bottom, aligned along their left edges.

hcatA :: VAlignment -> [Diagram] -> Diagram

Lay out a list of Diagrams horizontally from left to right, with the given vertical alignment (top, vcenter, or bottom).

vcatA :: HAlignment -> [Diagram] -> Diagram

Lay out a list of Diagrams vertically from top to bottom, with the given horizontal alignment (left, hcenter, or right).

hsep

Arguments

:: Double

amount of separation between each pair of diagrams

-> [Diagram]

-> Diagram

Lay out a list of Diagrams horizontally, aligned along their top edges, with a given amount of separation in between each pair.

vsep

Arguments

:: Double

amount of separation between each pair of diagrams

-> [Diagram]

-> Diagram

Lay out a list of Diagrams vertically, aligned along their left edges, with a given amount of separation in between each pair.

hsepA

Arguments

:: Double

amount of separation between each pair of diagrams

-> VAlignment

alignment to use (top, vcenter, or bottom)

-> [Diagram]

-> Diagram

Lay out a list of Diagrams horizontally, with the given amount of separation in between each pair, using the given vertical alignment (top, center, or bottom).

vsepA

Arguments

:: Double

amount of separation between each pair of diagrams

-> HAlignment

alignment to use (left, hcenter, or right)

-> [Diagram]

-> Diagram

Lay out a list of Diagrams vertically, with the given amount of separation in between each pair, using the given horizontal alignment (left, hcenter, or right).

hdistrib

Arguments

:: Double

How far from one diagram to the next?

-> HAlignment

Distribute according to which parts of the diagrams (left, hcenter, right)?

-> [Diagram]

-> Diagram

Distribute a list of Diagrams horizontally according to a regular spacing, aligned along their top edges.

vdistrib

Arguments

:: Double

How far from one diagram to the next?

-> VAlignment

Distribute according to which parts of the diagrams (top, vcenter, bottom)?

-> [Diagram]

-> Diagram

Distribute a list of Diagrams vertically according to a regular spacing, aligned along their left edges.

hdistribA

Arguments

:: Double

How far from one diagram to the next?

-> HAlignment

Distribute according to which parts of the diagrams (left, hcenter, right)?

-> VAlignment

alignment to use (top, vcenter, bottom)

-> [Diagram]

-> Diagram

Distribute a list of Diagrams horizontally according to a regular spacing, with the given alignment.

vdistribA

Arguments

:: Double

How far from one diagram to the next?

-> VAlignment

Distribute according to which parts of the diagrams (top, vcenter, bottom)?

-> HAlignment

alignment to use (left, hcenter, right)

-> [Diagram]

-> Diagram

Distribute a list of Diagrams vertically according to a regular spacing, with the given alignment.

type VAlignment = Alignment

Vertical alignment.

top :: VAlignment

vcenter :: VAlignment

bottom :: VAlignment

type HAlignment = Alignment

Horizontal alignment.

left :: HAlignment

hcenter :: HAlignment

right :: HAlignment

Transformations

Various ways to modify and transform Diagrams.

stretch :: Double -> Double -> Diagram -> Diagram

Stretch a diagram by a separate scaling factor for each axis. stretch w h scales by a factor of w in the x direction and a factor of h in the y direction.

scale :: Double -> Diagram -> Diagram

Scale by the same scaling factor in both dimensions, so the diagram retains its aspect ratio.

scaleX :: Double -> Diagram -> Diagram

Scale a diagram along the x-axis only. scaleX s is equivalent to stretch s 1.

scaleY :: Double -> Diagram -> Diagram

Scale a diagram along the y-axis only. scaleY s is equivalent to stretch 1 s.

translate :: Double -> Double -> Diagram -> Diagram

Translate a diagram by the given relative offsets in the x and y directions. Note that the positive x-axis is to the right, while the positive y-axis points downwards.

translateX :: Double -> Diagram -> Diagram

Translate a diagram along the x-axis only. translateX x is equivalent to translate x 0.

translateY :: Double -> Diagram -> Diagram

Translate a diagram along the y-axis only. translateY y is equivalent to translate 0 y.

rotate :: Double -> Diagram -> Diagram

rotate f rotates a diagram clockwise by fraction f of a complete revolution. rotate f is equivalent to rotateR (2*pi*f).

rotateR :: Double -> Diagram -> Diagram

rotateR r rotates a diagram clockwise by r radians.

view :: Point -> Point -> Diagram -> Diagram

XXX comment me

Attributes

Attributes which affect the way in which a Diagram is rendered. For a large list of predefined Color values, see Graphics.Rendering.Diagrams.Colors.

fillColor :: Color -> Diagram -> Diagram

Draw a diagram using the given fill color. Note that the new color only applies to parts of the diagram which are not otherwise colored; subdiagrams which already have an explicit fill color will not be affected. The default fill color is completely transparent.

fc :: Color -> Diagram -> Diagram

fc is provided as a convenient short synonym for fillColor.

fillTransparency :: Int -> Diagram -> Diagram

Set the transparency used for the fill color, from 0 (completely transparent) to 255 (completely opaque). Note that you can set the alpha channel of the fill color using fillColor combined with rgba, but fillTransparency allows you to set the alpha channel independently of the color channels. This means you can use it together with the colors defined in Graphics.Rendering.Diagrams.Colors.

ft :: Int -> Diagram -> Diagram

ft is provided as a convenient short synonym for fillTransparency.

lineColor :: Color -> Diagram -> Diagram

Draw a diagram using the given color for lines. Note that the new color only applies to parts of the diagram which are not otherwise colored; subdiagrams which already have an explicit line color will not be affected. The default line color is black.

lc :: Color -> Diagram -> Diagram

lc is provided as a convenient short synonym for lineColor.

lineWidth :: Double -> Diagram -> Diagram

Draw shape outlines and lines with the given width. Note that the line width is invariant under uniform scaling, although under non-uniform scaling (scaling by different amounts in the x and y axes) lines can become distorted. The default line width is 1.

lw :: Double -> Diagram -> Diagram

lw is provided as a convenient short synonym for lineWidth.

data Color

The Color type represents colors in red-green-blue-alpha format, with each channel in the range 0-1. For a large list of predefined colors, see Graphics.Rendering.Diagrams.Colors.

Instances

Eq Color

Read Color

Show Color

rgb

Arguments

:: Double

red channel

-> Double

green channel

-> Double

blue channel

-> Color

Construct an opaque (alpha = 1) color from RGB values specified as Doubles in the range 0-1.

rgba

Arguments

:: Double

red channel

-> Double

green channel

-> Double

blue channel

-> Double

alpha (transparency) channel

-> Color

Construct a color from RGBA values, specified as Doubles in the range 0-1.

module Graphics.Rendering.Diagrams.Colors

Rendering

renderToPng

Arguments

:: String

The name of the file to create.

-> Int

The desired width of the image, in pixels.

-> Int

The desired height of the image.

-> Diagram

The diagram to render.

-> IO ()

Render a diagram to a file in PNG format.

compose

Arguments

:: Double

output width

-> Double

output height

-> Diagram

Diagram to render

-> Render ()

Given a target width and height and a user-constructed Diagram, render it using the Cairo rendering library. Note that compose takes care of all the rendering details, including preprocessing of the Diagram, and scaling/translating the final output so that it fits within the given width and height.

The background of the output diagram will be opaque white.

In order to produce a physical output, the output of compose must be given as input to an output adapter such as writePng.