Euclidean 2-space

There are three main type synonyms defined for referring to two-dimensional space:

• R2 is the type of the two-dimensional Euclidean vector space. It is a synonym for (Double, Double). The positive \(x\)-axis extends to the right, and the positive \(y\)-axis extends upwards. This is consistent with standard mathematical practice, but upside-down with respect to many common graphics systems. This is intentional: the goal is to provide an elegant interface which is abstracted as much as possible from implementation details.

  unitX and unitY are unit vectors in the positive \(x\)- and \(y\)-directions, respectively. Their negated counterparts are unit_X and unit_Y.

• P2 is the type of points in two-dimensional space. It is a synonym for Point R2. The distinction between points and vectors is important; see Vectors and points.

• T2 is the type of two-dimensional affine transformations. It is a synonym for Transformation R2.

Angles

The Angle type class classifies types which measure two-dimensional angles. Three instances are provided by default (you can, of course, also make your own):

• CircleFrac represents fractions of a circle. A value of 1 represents a full turn.

• Rad represents angles measured in radians. A value of tau (that is, \(\tau = 2 \pi\)) represents a full turn. (If you haven't heard of \(\tau\), see The Tau Manifesto.)

• Deg represents angles measured in degrees. A value of 360 represents a full turn.

The intention is that to pass an argument to a function that expects a value of some Angle type, you can write something like (3 :: Deg) or (3 :: Rad). The convertAngle function is also provided for converting between different angle representations.

The direction function computes the angle of a vector, measured clockwise from the positive \(x\)-axis.

Circles and ellipses

Circles can be created with the unitCircle and circle functions, defined in Diagrams.TwoD.Ellipse.

For example,

> example = circle 0.5 <> unitCircle

unitCircle creates a circle of radius 1 centered at the origin; circle takes the desired radius as an argument.

Every ellipse is the image of the unit circle under some affine transformation, so ellipses can be created by appropriately scaling and rotating circles.

> example = unitCircle # scaleX 0.5 # rotateBy (1/6)

For convenience the standard library also provides ellipse, for creating an ellipse with a given eccentricity, and ellipseXY, for creating an axis-aligned ellipse with specified radii in the x and y directions.

Arcs

Diagrams.TwoD.Arc provides a function arc, which constructs a radius-one circular arc starting at a first angle and extending counterclockwise to the second.

> example = arc (tau/4 :: Rad) (4 * tau / 7 :: Rad)

Pre-defined shapes

Diagrams.TwoD.Shapes provides a number of pre-defined polygons and other path-based shapes. For example:

• eqTriangle constructs an equilateral triangle with sides of a given length.

• square constructs a square with a given side length; unitSquare constructs a square with sides of length 1.

• pentagon, hexagon, ..., dodecagon construct other regular polygons with sides of a given length.

• In general, regPoly constructs a regular polygon with any number of sides.

• rect constructs a rectangle of a given width and height.

• roundedRect constructs a rectangle with circular rounded corners.

> example = square 1 ||| rect 0.3 0.5
>       ||| eqTriangle 1 ||| roundedRect (0.7,0.4) 0.1

More special polygons will likely be added in future versions of the library.

Completing the hodgepodge in Diagrams.TwoD.Shapes for now, the functions hrule and vrule create horizontal and vertical lines, respectively.

> example = circle 1 ||| hrule 2 ||| circle 1

General polygons

The polygon function from Diagrams.TwoD.Polygons can be used to construct a wide variety of polygons. Its argument is a record of optional arguments that control the generated polygon:

• polyType specifies one of several methods for determining the vertices of the polygon:

  • PolyRegular indicates a regular polygon with a certain number of sides and a given radius.

  • PolySides specifies the vertices using a list of angles between edges, and a list of edge lengths.

  • PolyPolar specifies the vertices using polar coordinates: a list of central angles between vertices, and a list of vertex radii.

• polyOrient specifies the PolyOrientation: the polygon can be oriented with an edge parallel to the \(x\)-axis. with an edge parallel to the \(y\)-axis, or with an edge perpendicular to any given vector. You may also specify that no special orientation should be applied, in which case the first vertex of the polygon will be located along the positive \(x\)-axis.

• Additionally, a center other than the origin can be specified using polyCenter.

> poly1 = polygon with { polyType   = PolyRegular 13 5
>                      , polyOrient = OrientV }
> poly2 = polygon with { polyType   = PolyPolar (repeat (1/40 :: CircleFrac))
>                                               (take 40 $ cycle [2,7,4,6]) }
> example = (poly1 ||| strutX 1 ||| poly2) # lw 0.05

Notice the idiom of using with to construct a record of default options and selectively overriding particular options by name. with is a synonym for def from the type class Default, which specifies a default value for types which are instances. You can read more about this idiom in the section Faking optional named arguments.

Star polygons

A "star polygon" is a polygon where the edges do not connect consecutive vertices; for example:

> example = star (StarSkip 3) (regPoly 13 1) # stroke

Diagrams.TwoD.Polygons provides the star function for creating star polygons of this sort, although it is actually quite a bit more general.

As its second argument, star expects a list of points. One way to generate a list of points is with polygon-generating functions such as polygon or regPoly, or indeed, any function which can output any PathLike type (see the section about PathLike), since a list of points is an instance of the PathLike class. Of course, you are free to construct the list of points using whatever method you like!

As its first argument, star takes a value of type StarOpts, for which there are two possibilities:

• StarSkip specifies that every math:n th vertex should be connected by an edge.

  

  > example = stroke (star (StarSkip 2) (regPoly 8 1))
  >       ||| strutX 1
  >       ||| stroke (star (StarSkip 3) (regPoly 8 1))

  As you can see, star may result in a path with multiple components, if the argument to StarSkip evenly divides the number of vertices.

• StarFun takes as an argument a function of type (Int -> Int), which specifies which vertices should be connected to which other vertices. Given the function \(f\), vertex \(i\) is connected to vertex \(j\) if and only if \(f(i) \equiv j \pmod n\), where \(n\) is the number of vertices. This can be used as a compact, precise way of specifying how to connect a set of points (or as a fun way to visualize functions in \(Z_n\)!).

  

  > funs          = map (flip (^)) [2..6]
  > visualize f   = stroke' with { vertexNames = [[0 .. 6 :: Int]] }
  >                     (regPoly 7 1)
  >                   # lw 0
  >                   # showLabels
  >                   # fontSize 0.6
  >              <> star (StarFun f) (regPoly 7 1)
  >                   # stroke # lw 0.05 # lc red
  > example       = centerXY . hcat' with {sep = 0.5} $ map visualize funs

You may notice that all the above examples need to call stroke (or stroke'), which converts a path into a diagram. Many functions similar to star are polymorphic in their return type over any PathLike, but star is not. As we have seen, star may need to construct a path with multiple components, which is not supported by the PathLike class.

Superimposing diagrams with atop

The most fundamental way to combine two diagrams is to place one on top of the other with atop. The diagram d1 `atop` d2 is formed by placing d1's local origin on top of d2's local origin; that is, by identifying their local vector spaces.

> example = circle 1 `atop` square (sqrt 2)

As noted before, diagrams form a monoid with composition given by identification of vector spaces. atop is simply a synonym for mappend (or (<>)), specialized to two dimensions.

This also means that a list of diagrams can be stacked with mconcat; that is, mconcat [d1, d2, d3, ...] is the diagram with d1 on top of d2 on top of d3 on top of...

> example = mconcat [ circle 0.1 # fc green
>                   , eqTriangle 1 # scale 0.4 # fc yellow
>                   , square 1 # fc blue
>                   , circle 1 # fc red
>                   ]

Juxtaposing diagrams

Fundamentally, atop is actually the only way to compose diagrams; however, there are a number of other combining methods (all ultimately implemented in terms of atop) provided for convenience.

Two diagrams can be placed next to each other using beside. The first argument to beside is a vector specifying a direction. The second and third arguments are diagrams, which are placed next to each other so that the vector points from the first diagram to the second.

> example = beside (20,30) (circle 1 # fc orange) (circle 1.5 # fc purple)
>           # showOrigin

As can be seen from the above example, the length of the vector makes no difference, only its direction is taken into account. (To place diagrams at a certain fixed distance from each other, see cat'.) As can also be seen, the local origin of the new, combined diagram is at the point of tangency between the two subdiagrams.

To place diagrams next to each other while leaving the local origin of the combined diagram in the same place as the local origin of the first subdiagram, use append instead of beside:

> example = append (20,30) (circle 1 # fc orange) (circle 1.5 # fc purple)
>           # showOrigin

Since placing diagrams next to one another horizontally and vertically is quite common, special combinators are provided for convenience. (|||) and (===) are specializations of beside which juxtapose diagrams in the \(x\)- and \(y\)-directions, respectively.

> d1 = circle 1 # fc red
> d2 = square 1 # fc blue
> example = (d1 ||| d2) ||| strutX 3 ||| ( d1
>                                          ===
>                                          d2  )

See Bounding functions and local vector spaces for more information on what "next to" means, or see Bounding functions for precise details.

Concatenating diagrams

We have already seen one way to combine a list of diagrams, using mconcat to stack them. Several other methods for combining lists of diagrams are also provided in Diagrams.Combinators.

The simplest method of combining multiple diagrams is position, which takes a list of diagrams paired with points, and places the local origin of each diagram at the indicated point.

> example = position (zip (map mkPoint [-3, -2.8 .. 3]) (repeat dot))
>   where dot       = circle 0.2 # fc black
>         mkPoint x = P (x,x^2)

cat is like an iterated version of beside, which takes a direction vector and a list of diagrams, laying out the diagrams beside one another in a row. The local origins of the subdiagrams will be placed along a straight line in the direction of the given vector.

> example = cat (2,-1) (map p [3..8]) # showOrigin
>   where p n = regPoly n 1 # lw 0.03

Note, however, that the local origin of the final diagram is placed at the local origin of the first diagram in the list.

For more control over the way in which the diagrams are laid out, use cat', a variant of cat which also takes a CatOpts record. See the documentation for cat' and CatOpts to learn about the various possibilities.

> example = cat' (2,-1) with { catMethod = Distrib, sep = 2 } (map p [3..8])
>   where p n = regPoly n 1 # lw 0.03
>                           # scale (1 + fromIntegral n/4)
>                           # showOrigin

For convenience, Diagrams.TwoD.Combinators also provides hcat, hcat', vcat, and vcat', variants of cat and cat' which concatenate diagrams horizontally and vertically.

Finally, appends is like an iterated variant of append, with the important difference that multiple diagrams are placed next to a single central diagram without reference to one another; simply iterating append causes each of the previously appended diagrams to be taken into account when deciding where to place the next one.

> c        = circle 1 # lw 0.03
> dirs     = iterate (rotateBy (1/7)) unitX
> cdirs    = zip dirs (replicate 7 c)
> example1 = appends c cdirs
> example2 = foldl (\a (v,b) -> append v a b) c cdirs
> example  = example1 ||| strutX 3 ||| example2

Diagrams.Combinators also provides decoratePath and decorateTrail, which are described in Decorating trails and paths.

Attributes and styles

Every diagram has a style which is an arbitrary collection of attributes. This section will describe some of the default attributes which are provided by the diagrams library and recognized by most backends. However, you can easily create your own attributes as well; for details, see Style and attribute internals.

In many examples, you will see attributes applied to diagrams using the (#) operator. However, keep in mind that there is nothing special about this operator as far as attributes are concerned. It is merely backwards function application, which is used for attributes since it often reads better to have the main diagram come first, followed by modifications to its attributes.

In general, inner attributes (that is, attributes applied earlier) override outer ones. Note, however, that this is not a requirement. Each attribute may define its own specific method for combining multiple instances. See Style and attribute internals for more details.

Most of the attributes discussed in this section are defined in Diagrams.Attributes.

Color

Two-dimensional diagrams have two main colors, the color used to stroke the paths in the diagram and the color used to fill them. These can be set, respectively, with the lc (line color) and fc (fill color) functions.

> example = circle 0.2 # lc purple # fc yellow

By default, diagrams use a black line color and a completely transparent fill color.

Colors themselves are handled by the colour package, which provides a large set of predefined color names as well as many more sophisticated color operations; see its documentation for more information. The colour package uses a different type for colors with an alpha channel (i.e. transparency). To make use of transparent colors you can use lcA and fcA.

> import Data.Colour (withOpacity)
>
> colors  = map (blue `withOpacity`) [0.1, 0.2 .. 1.0]
> example = hcat' with { catMethod = Distrib, sep = 1 }
>                 (zipWith fcA colors (repeat (circle 1)))

Transparency can also be tweaked with the Opacity attribute, which sets the opacity/transparency of a diagram as a whole. Applying opacity p to a diagram, where p is a value between 0 and 1, results in a diagram p times as opaque.

> s c     = square 1 # fc c
> reds    = (s darkred ||| s red) === (s pink ||| s indianred)
> example = hcat' with { sep = 1 } . take 4 . iterate (opacity 0.7) $ reds

Line width

To alter the width of the lines used to stroke paths, use lw. The default line width is (arbitrarily) 0.01. You can also set the line width to zero if you do not want a path stroked at all.

Line width actually more subtle than you might think. Suppose you create a diagram consisting of a square, and another square twice as large next to it (using scale 2). How should they be drawn? Should the lines be the same width, or should the larger square use a line twice as thick?

In fact, in many situations the lines should actually be the same thickness, so a collection of shapes will be drawn in a uniform way. This is the default in diagrams. Specifically, the argument to lw is measured with respect to the final vector space of a complete, rendered diagram, not with respect to the local vector space at the time the lw function is applied. Put another way, subsequent transformations do not affect the line width. This is perhaps a bit confusing, but trying to get line widths to look reasonable would be a nightmare otherwise.

> example = (square 1
>       ||| square 1 # scale 2
>       ||| circle 1 # scaleX 3)   # lw 0.03

However, occasionally you do want subsequent transformations to affect line width. The freeze function is supplied for this purpose. Once freeze has been applied to a diagram, any subsequent transformations will affect the line width.

> example = (square 1
>       ||| square 1 # freeze # scale 2
>       ||| circle 1 # freeze # scaleX 3)  # lw 0.03

Note that line width does not affect the bounding function of diagrams at all. Future versions of the standard library may provide a function to convert a stroked path into an actual region, which would allow line width to be taken into account.

Other line parameters

Many rendering backends provide some control over the particular way in which lines are drawn. Currently, diagrams provides support for three aspects of line drawing:

• lineCap sets the LineCap style.

• lineJoin sets the LineJoin style.

• dashing allows for drawing dashed lines with arbitrary dashing patterns.

> path = fromVertices (map P [(0,0), (1,0.3), (2,0), (2.2,0.3)]) # lw 0.1
> example = centerXY . vcat' with { sep = 0.1 }
>           $ map (path #)
>             [ lineCap LineCapButt   . lineJoin LineJoinMiter
>             , lineCap LineCapRound  . lineJoin LineJoinRound
>             , lineCap LineCapSquare . lineJoin LineJoinBevel
>             , dashing [0.1,0.2,0.3,0.1] 0
>             ]

> myFun style = d # applyStyle style # lc red # ...
>   where d = ...

> foo = myFun (mempty # fontSize 10 # lw 0 # fc green)

2D Transformations

Any diagram can be transformed by applying arbitrary affine transformations to it. Affine transformations include linear transformations (rotation, scaling, reflection, shears --- anything which leaves the origin fixed and sends lines to lines) as well as translations. Diagrams.TwoD.Transform defines a number of common affine transformations in two-dimensional space. (To construct transformations more directly, see Graphics.Rendering.Diagrams.Transform.)

Every transformation comes in two variants, a noun form and a verb form. For example, there are two functions for scaling along the \(x\)-axis, scalingX and scaleX. The noun form constructs a transformation object, which can then be stored in a data structure, passed as an argument, combined with other transformations, etc., and ultimately applied to a diagram with the transform function. The verb form directly applies the transformation to a diagram. The verb form is much more common (and the documentation below will only discuss verb forms), but getting one's hands on a transformation can occasionally be useful.

Rotation

Use rotate to rotate a diagram couterclockwise by a given angle about the origin. Since rotate takes an angle, you must specify an angle type, as in rotate (80 :: Deg). In the common case that you wish to rotate by an angle specified as a certain fraction of a circle, like rotate (1/8 :: CircleFrac), you can use rotateBy instead. rotateBy is specialized to only accept fractions of a circle, so in this example you would only have to write rotateBy
(1/8).

You can also use rotateAbout in the case that you want to rotate about some point other than the origin.

> eff = text "F" <> square 1 # lw 0
> rs  = map rotateBy [1/7, 2/7 .. 6/7]
> example = hcat . map (eff #) $ rs

Scaling and reflection

Scaling by a given factor is accomplished with scale (which scales uniformly in all directions), scaleX (which scales along the \(x\)-axis only), or scaleY (which scales along the \(y\)-axis only). All of these can be used both for enlarging (with a factor greater than one) and shrinking (with a factor less than one). Using a negative factor results in a reflection (in the case of scaleX and scaleY) or a 180-degree rotation (in the case of scale).

> eff = text "F" <> square 1 # lw 0
> ts  = [ scale (1/2), id, scale 2,    scaleX 2,    scaleY 2
>       ,     scale (-1), scaleX (-1), scaleY (-1)
>       ]
>
> example = hcat . map (eff #) $ ts

Scaling by zero is forbidden. Let us never speak of it again.

For convenience, reflectX and reflectY perform reflection along the \(x\)- and \(y\)-axes, respectively; but I think you can guess how they are implemented. Their names can be confusing (does reflectX reflect along the \(x\)-axis or across the \(x\)-axis?) but you can just remember that reflectX = scaleX (-1).

To reflect in some line other than an axis, use reflectAbout.

> eff = text "F" <> square 1 # lw 0
> example = eff
>        <> reflectAbout (P (0.2,0.2)) (rotateBy (-1/10) unitX) eff

Conjugation

Diagrams.Transform exports useful transformation utilities which are not specific to two dimensions. At the moment there are only two: conjugate and under. The first simply performs conjugation: conjugate t1 t2 == inv t1 <> t2 <> t1, that is, performs t1, then t2, then undoes t1.

under performs a transformation using conjugation. It takes as arguments a function to perform some transformation as well as a transformation to conjugate by. For example, scaling by a factor of 2 along the diagonal line \(y = x\) can be accomplished thus:

> eff = text "F" <> square 1 # lw 0
> example = (scaleX 2 `under` rotation (-1/8 :: CircleFrac)) eff

The letter F is first rotated so that the desired scaling axis lies along the \(x\)-axis; then scaleX is performed; then it is rotated back to its original position.

Note that reflectAbout and rotateAbout are implemented using under.

Alignment

Since diagrams are always combined with respect to their local origins, moving a diagram's local origin affects the way it combines with others. The position of a diagram's local origin is referred to as its alignment.

The functions moveOriginBy and moveOriginTo are provided for explicitly moving a diagram's origin, by an absolute amount and to an absolute location, respectively. moveOriginBy and translate are actually dual, in the sense that

moveOriginBy v === translate (negateV v).

This duality comes about since translate moves a diagram with respect to its origin, whereas moveOriginBy moves the origin with respect to the diagram. Both are provided so that you can use whichever one corresponds to the most natural point of view in a given situation, without having to worry about inserting calls to negateV.

Often, however, one wishes to move a diagram's origin with respect to its bounding function. To this end, some general tools are provided in Diagrams.Align, and specialized 2D-specific ones by Diagrams.TwoD.Align.

Functions like alignT (align Top) and alignBR (align Bottom Right) move the local origin to the edge of the bounding region:

> s = square 1 # fc yellow
> x |-| y = x ||| strutX 0.5 ||| y
> example =  (s # showOrigin)
>        |-| (s # alignT  # showOrigin)
>        |-| (s # alignBR # showOrigin)

There are two things to note about the above example. First, notice how alignT and alignBR move the local origin of the square in the way you would expect. Second, notice that when placed "next to" each other using the (|||) operator, the squares are placed so that their local origins fall on a horizontal line.

Functions like alignY allow finer control over the alignment. In the below example, the origin is moved to a series of locations interpolating between the bottom and top of the square:

> s = square 1 # fc yellow
> example = hcat . map showOrigin
>         $ zipWith alignY [-1, -0.8 .. 1] (repeat s)

Segments

The most basic path component is a Segment, which is some sort of primitive path from one point to another. Segments are translationally invariant; that is, they have no inherent location, and applying a translation to a segment has no effect (however, other sorts of transformations, such as rotations and scales, have the effect you would expect). In other words, a segment is not a way to get from point A to point B; it is a way to get from wherever you are to somewhere else.

Currently, diagrams supports two types of segment, defined in Diagrams.Segment:

• A linear segment is simply a straight line, defined by an offset from its beginning point to its end point; you can construct one using straight.

• A Bézier segment is a cubic curve defined by an offset from its beginning to its end, along with two control points; you can construct one using bezier3. An example is shown below, with the endpoints shown in red and the control points in blue. Bézier curves always start off from the beginning point heading towards the first control point, and end up at the final point heading away from the last control point. That is, in any drawing of a Bézier curve like the one below, the curve will be tangent to the two dotted lines.

> illustrateBezier c1 c2 p2
>     =  endpt
>     <> endpt  # translate p2
>     <> ctrlpt # translate c1
>     <> ctrlpt # translate c2
>     <> l1
>     <> l2
>     <> fromSegments [bezier3 c1 c2 p2]
>   where
>     dashed  = dashing [0.1,0.1] 0
>     endpt   = circle 0.05 # fc red  # lw 0
>     ctrlpt  = circle 0.05 # fc blue # lw 0
>     l1      = fromOffsets [c1] # dashed
>     l2      = fromOffsets [p2 ^-^ c2] # translate c2 # dashed
>
> p2      = (3,-1) :: R2     -- endpoint
> [c1,c2] = [(1,2), (3,0)]   -- control points
>
> example = illustrateBezier c1 c2 p2

Diagrams.Segment also provides a few tools for working with segments:

• atParam for computing points along a segment;

• segOffset for computing the offset from the start of a segment to its endpoint;

• splitAtParam for splitting a segment into two smaller segments;

• arcLength for approximating the arc length of a segment;

• arcLengthToParam for approximating the parameter corresponding to a given arc length along the segment; and

• adjustSegment for extending or shrinking a segment.

Trails

Trails, defined in Diagrams.Path, are essentially lists of segments laid end-to-end. Since segments are translationally invariant, so are trails; that is, trails have no inherent starting location, and translating them has no effect.

Trails can also be open or closed: a closed trail is one with an implicit (linear) segment connecting the endpoint of the trail to the starting point.

To construct a Trail, you can use one of the following:

• fromSegments takes an explicit list of Segments.

• fromOffsets takes a list of vectors, and turns each one into a linear segment.

• fromVertices takes a list of vertices, generating linear segments between them.

• (~~) creates a simple linear trail between two points.

• cubicSpline creates a smooth curve passing through a given list of points; it is described in more detail in the section on Splines.

If you look at the types of these functions, you will note that they do not, in fact, return just Trails: they actually return any type which is an instance of PathLike, which includes Trails, Paths (to be covered in the next section), Diagrams, and lists of points. See the PathLike section for more on the PathLike class.

Trails form a Monoid with concatenation as the binary operation, and the empty (no-segment) trail as the identity element. The example below creates a two-segment trail called spike and then constructs a starburst path by concatenating a number of rotated copies. strokeT turns a trail into a diagram, with the start of the trail at the local origin.

> spike :: Trail R2
> spike = fromOffsets [(1,3), (1,-3)]
>
> burst = mconcat . take 13 . iterate (rotateBy (-1/13)) $ spike
>
> example = strokeT burst # fc yellow # lw 0.1 # lc orange

For details on the functions provided for manipulating trails, see the documentation for Diagrams.Path. One other function worth mentioning is explodeTrail, which turns each segment in a trail into its own individual Path. This is useful when you want to construct a trail but then do different things with its individual segments. For example, we could construct the same starburst as above but color the edges individually:

> spike :: Trail R2
> spike = fromOffsets [(1,3), (1,-3)]
>
> burst = mconcat . take 13 . iterate (rotateBy (-1/13)) $ spike
>
> colors = cycle [aqua, orange, deeppink, blueviolet, crimson, darkgreen]
>
> example = lw 0.1
>         . mconcat
>         . zipWith lc colors
>         . map stroke . explodeTrail origin
>         $ burst

(If we wanted to fill the starburst with yellow as before, we would have to separately draw another copy of the trail with a line width of zero before exploding it; this is left as an exercise for the reader.)

Paths

A Path, also defined in Diagrams.Path, is a (possibly empty) collection of trails, along with an absolute starting location for each trail. Paths of a single trail can be constructed using the same functions described in the previous section: fromSegments, fromOffsets, fromVertices, (~~), and cubicSpline.

Paths also form a Monoid, but the binary operation is superposition (just like that of diagrams). Paths with multiple components can be used, for example, to create shapes with holes:

> ring :: Path R2
> ring = circlePath 3 <> circlePath 2
>
> example = stroke ring # fc purple # fillRule EvenOdd

(See Fill rules for an explanation of the call to fillRule
EvenOdd.)

stroke turns a path into a diagram, just as strokeT turns a trail into a diagram. (In fact, strokeT really works by first turning the trail into a path and then calling stroke on the result.)

explodePath, similar to explodeTrail, turns the segments of a path into individual paths. Since a path is a collection of trails, each of which is a sequence of segments, explodePath actually returns a list of lists of paths.

For information on other path manipulation functions such as pathFromTrail, pathFromTrailAt, pathVertices, and pathOffsets, see the documentation in Diagrams.Path.

Decorating trails and paths

Paths (and trails) can be used not just to draw certain shapes, but also as tools for positioning other objects. To this end, diagrams provides decoratePath and decorateTrail, which position a list of objects at the vertices of a given path or trail, respectively.

For example, suppose we want to create an equilateral triangular arrangement of dots. One possibility is to create horizontal rows of dots, center them, and stack them vertically. However, this is annoying, because we must manually compute the proper vertical stacking distance between rows. Whether you think this sounds easy or not, it is certainly going to involve the sqrt function, or perhaps some trig, and we'd rather avoid all that.

Fortunately, there's an easier way: after creating the horizontal rows, we create the path corresponding to the left-hand side of the triangle (which can be done using a simple rotation), and then decorate it with the rows.

> dot = circle 1 # fc black
> mkRow n = hcat' with {sep = 0.5} (replicate n dot)
> mkTri n = decoratePath
>             (fromOffsets (replicate (n-1) (2.5 *^ unitX))
>                # rotateBy (1/6))
>             (map mkRow [n, n-1 .. 1])
> example = mkTri 5

The PathLike class

As you may have noticed by now, a large class of functions in the standard library---such as square, polygon, fromVertices, and so on---generate not just diagrams, but any type which is an instance of the PathLike type class.

The PathLike type class has only a single method, pathLike:

> pathLike :: Point (V p)
>          -> Bool
>          -> [Segment (V p)]
>          -> p

• The first argument is a starting point for the path-like thing; path-like things which are translationally invariant (such as Trails) simply ignore this argument.

• The second argument indicates whether the path-like thing should be closed.

• The third argument specifies the segments of the path-like thing.

Currently, there are four instances of PathLike:

• Trail: as noted before, the implementation of pathLike for Trails ignores the first argument, since Trails have no inherent starting location.

• Path: of course, pathLike can only construct paths of a single component.

• Diagram b R2: as long as the backend b knows how to render 2D paths, pathLike can construct a diagram by stroking the generated single-component path.

• [Point v]: this instance generates the vertices of the path.

It is quite convenient to be able to use, say, square 2 as a diagram, path, trail, or list of vertices, whichever suits one's needs. Otherwise, either four different functions would be needed for each primitive (like square, squarePath, squareTrail, and squareVertices, ugh), or else explicit conversion functions would have to be inserted when you wanted something other than what the square function gave you by default.

As an (admittedly contrived) example, the following diagram defines s as an alias for square 2 and then uses it at all four instances of PathLike:

> s = square 2  -- a squarish thing.
>
> blueSquares = decoratePath s {- 1 -}
>                 (replicate 4 (s {- 2 -} # scale 0.5) # fc blue)
> paths       = lc purple . stroke $ star (StarSkip 2) s {- 3 -}
> plus        = centerXY . lc green . strokeT
>             . mconcat . take 5 . iterate (rotateBy (1/5))
>             $ s {- 4 -}
> example = (blueSquares <> plus <> paths) # lw 0.05

Exercise: figure out which occurrence of s has which type. (Answers below.)

At its best, this type-directed behavior results in a "it just works/do what I mean" experience. However, it can occasionally be confusing, and care is needed. The biggest gotcha occurs when combining a number of shapes using (<>) or mconcat: diagrams, paths, trails, and lists of vertices all have Monoid instances, but they are all different, so the combination of shapes has different semantics depending on which type is inferred.

> ts = mconcat . take 3 . iterate (rotateBy (1/9)) $ eqTriangle 1
> example = (ts ||| stroke ts ||| strokeT ts ||| fromVertices ts) # fc red

The above example defines ts by generating three equilateral triangles offset by 1/9 rotations, then combining them with mconcat. The sneaky thing about this is that ts can have the type of any PathLike instance, and it has completely different meanings depending on which type is chosen. The example uses ts at each of the four PathLike types:

• Since example is a diagram, the first ts, used by itself, is also a diagram; hence it is interpreted as three equilateral triangle diagrams superimposed on one another with atop.

• stroke turns Paths into diagrams, so the second ts has type Path R2. Hence it is interpreted as three triangular paths superimposed into one three-component path, which is then stroked.

• strokeT turns Trails into diagrams, so the third occurrence of ts has type Trail R2. It is thus interpreted as three triangular trails (without the implicit closing segments) sequenced end-to-end into one long trail.

• The last occurrence of ts is a list of points, namely, the concatenation of the vertices of the three triangles. Turning this into a diagram with fromVertices generates a single-component, open path that visits each of the points in turn. The generated diagram looks passingly similar to the one from the second occurrence of ts, but a careful look reveals that they are quite different.

Of course, one way to avoid all this would be to give ts a specific type annotation, if you know which type you would like it to be. Then using it at a different type will result in a type error, rather than confusing semantics.

Answers to the square 2 type inference challenge:

1. Path R2

2. Diagram b R2

3. [P2]

4. Trail R2

The Closeable class

Creating closed paths can be accomplished with the close method of the Closeable type class. There is also an open method, which does what you would think. Currently, there are only two instances of Closeable: Trail and Path.

Splines

Constructing Bézier segments by hand is tedious. The Diagrams.CubicSpline module provides the cubicSpline function, which, given a list of points, constructs a smooth curved path passing through each point in turn. The first argument to cubicSpline is a boolean value indicating whether the path should be closed.

> pts = map P [(0,0), (2,3), (5,-2), (-4,1), (0,3)]
> dot = circle 0.2 # fc blue # lw 0
> mkPath closed = position (zip pts (repeat dot))
>              <> cubicSpline closed pts # lw 0.05
> example = mkPath False ||| strutX 2 ||| mkPath True

For more control over the generation of curved paths, see the diagrams-spiro package.

Fill rules

There are two main algorithms or "rules" used when determining which areas to fill with color when filling the interior of a path: the winding rule and the even-odd rule. The rule used to draw a path-based diagram can be set with fillRule. For simple, non-self-intersecting paths, determining which points are inside is quite simple, and the two algorithms give the same results. However, for self-intersecting paths, they usually result in different regions being filled.

> loopyStar = fc red
>           . mconcat . map (cubicSpline True)
>           . pathVertices
>           . star (StarSkip 3)
>           $ regPoly 7 1
> example = loopyStar # fillRule EvenOdd
>       ||| strutX 1
>       ||| loopyStar # fillRule Winding

• The even-odd rule specifies that a point is inside the path if a straight line extended from the point off to infinity (in one direction only) crosses the path an odd number of times. Points with an even number of crossings are outside the path. This rule is simple to implement and works perfectly well for non-self-intersecting paths. For self-intersecting paths, however, it results in a funny pattern of alternatingly filled and unfilled regions, as seen in the above example. Sometimes this pattern is desirable for its own sake.

• The winding rule specifies that a point is inside the path if its winding number is nonzero. The winding number measures how many times the path "winds" around the point, and can be intuitively computed as follows: imagine yourself standing at the given point, facing some point on the path. You hold one end of an (infinitely stretchy) rope; the other end of the rope is attached to a train sitting at the point on the path at which you are looking. Now the train begins traveling around the path. As it goes, you keep hold of your end of the rope while standing fixed in place, not turning at all. After the train has completed one circuit around the path, look at the rope: if it is wrapped around you some number of times, you are inside the path; if it is not wrapped around you, you are outside the path. More generally, we say that the number of times the rope is wrapped around you (positive for one direction and negative for the other) is the point's winding number.

  Draw a picture of you and the train

  For example, if you stand outside a circle looking at a train traveling around it, the rope will move from side to side as the train goes around the circle, but ultimately will return to exactly the state in which it started. If you are standing inside the circle, however, the rope will end up wrapped around you once.

  For paths with multiple components, the winding number is simply the sum of the winding numbers for the individual components. This means, for example, that "holes" can be created in shapes using a path component traveling in the opposite direction from the outer path.

  This rule does a much better job with self-intersecting paths, and it turns out to be (with some clever optimizations) not much more difficult to implement or inefficient than the even-odd rule.

Clipping

With backends that support clipping, paths can be used to clip other diagrams. Only the portion of a clipped diagram falling inside the clipping path will be drawn. Note that the diagram's bounding function is unaffected.

> example = square 3
>         # fc green
>         # lw 0.05
>         # clipBy (square 3.2 # rotateBy (1/10))

The V type function

Points and vectors

The Backend class

The Renderable class