This article covers a small part of the internals of Diagrams, a Haskell library for drawing static and animated diagrams. In particular, I give an overview of how a diagram is represented, how paths work, and how attributes are applied to diagrams. The Diagrams library has a lot in it, so not everything can be covered in great detail in such a short article.

Understanding the internals of Diagrams is not necessary for using it effectively – you can make complex diagrams without knowing any of how it works. You might be interested in the internals if you want to extend the library, or add a new rendering backend, or just fix a bug or add documentation. This material might also be of interest to people who want to see examples of type classes, existential types and heterogeneous lists.

### Example

Throughout we’ll have a running example:

Let’s ignore the `renderSvg` and `writeFile` parts, because they are just for producing the SVG format after the diagram has been rendered. For brevity’s sake let’s ignore `renderDia`, and concentrate on the diagram itself.

The unit square is defined as a 4-sided polygon with radius `sqrt(2)/2`, oriented along the X-axis.

This polygon ends up being defined as a closed path of straight lines between the corners of the square at points (±0.5, ±0.5).

### Paths, trails and segments

To understand how this is represented, we need some Diagrams terminology. A “segment” is either a straight line or a Bézier curve, and doesn’t have any fixed position in space, which means translating a segment has no effect. A “trail” is a sequence of segments connected end-to-end. These still don’t have any fixed position, so can’t be translated. Trails can be open or closed. Finally, a “path” is a list of trails, plus a starting point for each trail. Because each trail in a path is fixed in some position, a path can be translated and one path can be placed on top of another.

So, our polygon above is a path with a single trail. The trail’s starting point is (0.5, -0.5), and the trail has three straight-line segments, defined by the vectors (0,1), (-1,0) and (0,-1). The trail is closed, so there is an implicit connection from the end of the trail back to the starting point.

Because it is being passed to `renderDia`, and the `fc` and `clipBy` modifications don’t alter its type, `unitSquare` must have the type `Diagram b v`. In this case, the backend `b` will be SVG and the vector space `v` will be `R2`. A diagram can be made from a path via the `stroke` function.

`stroke` and its friend `stroke'` deal with several things we’re not going to consider here: envelopes, traces, names and queries. For our purposes, all `stroke` does is wrap the path in a `Prim` type, and pass it `mkQD`, which makes a diagram from a single primitive.

### Diagram representation

The basic diagram type `QDiagram` is a wrapper around a DUAL tree. A DUAL tree is an n-ary tree with data at the leaves and annotations that travel either up or down the tree. (A DUAL tree can also have data in the internal nodes, but Diagrams currently doesn’t use this feature.) For Diagrams, the primitives are the leaf data, transformations and styles are the downwards-travelling annotations, and envelopes, traces, names and queries are the upwards-travelling annotations. Here we will only concern ourselves with the leaves and the down-annotations, the L and D in DUAL.

Because all we have is a primitive – our path – we have only some leaf data and no annotations. The path is passed to the `leaf` function, which makes a leaf node. Now we have a diagram (tree) which consists of a single primitive (leaf node).

### Attributes and styles

Now that we have a diagram, let’s consider next `unitSquare # fc red`. `fc` is defined, via `fillColor` as:

Because `Diagram` is a member of the `HasStyle` type class, you can read the type informally as `c -> Diagram -> Diagram`. `SomeColor` is a wrapper that contains a value whose type is a member of the `Color` type class. The `Last` semigroup just keeps the “last” value: ```Last a <> Last b <> Last c == Last c```. Finally, `FillColor` is a wrapper indicating which attribute we’re setting.

`applyAttr` is defined like this:

`attrToStyle` converts an attribute into a `Style`. A `Style` is a container for carrying several attributes together: a `Style` value is just a `Map` from `String`s to `Attribute` values:

where an `Attribute` value is of some type in the `AttributeClass` type class – in this case, that type is `FillColor`. Let’s look at the definition of `attrToStyle`:

The argument `a` is something like `FillColor (Last (SomeColor red))`. Starting from the left, you can see we are making a new `Style` value of a map containing a single key-value pair. The key is a string representation of whatever type `a` has – in this example it’s `FillColor`. The value part is `a` itself, wrapped up in type `Attribute`.

Note that there are two kinds of `Attribute`: transformable and non-transformable. `FillColor` is one of the non-transformable kind: transformations like scaling and translation don’t affect a diagram’s fill colour.

Now the style we have created needs to be applied to the diagram. The instance of `HasStyle` for a diagram defines `applyStyle` like this:

Intuitively, we know that applying a style to a diagram must somehow insert the style into the diagram tree as a down-annotation. The type of a down-annotation is:

This is a heterogeneous list – you can think of `:::` as a cons, like `:`, but at the type level. The `Transformation` type represents an affine transformation. The `Split` type is just like a regular monoid, but allows us to split the accumulated values into two halves. In Diagrams, this is used to separate the transformations into the frozen and unfrozen transformations. The `:+:` operator represents a monoid coproduct – we will skip the details, but here it means that we have an interleaving of the transformation pairs with style values, and every transformation acts on all the styles that follow it.

The definition of `applyStyle` can be read as: take the style, put it the right part of the coproduct (`inR`), put that into a `DownAnnots` value (`inj`), and insert the the `DownAnnots` value into the tree at the root (`D.applyD`). The “over QD” part just means to do all this inside the `QD` wrapper around the tree.

Let’s now apply the `clipBy` attribute.

This is like the fill colour attribute, except the clip path is transformable. A `circle` is a like a `unitSquare`, except instead of being a path made of straight lines, it’s a path made of curves. The clipping attribute means that the only part of the square that will be shown is whatever overlaps with the circle. In this case, it’s like looking at the square through a circle-shaped hole.

### Conclusion

Here I’ve only scratched the surface of Diagrams. If you want to learn more, the source code is easy to read once you’ve learned your way around the types and modules.