Static annotations which can be placed at a particular node of a diagram tree.

Apply a static annotation at the root of a diagram.

Make a diagram into a hyperlink. Note that only some backends will honor hyperlink annotations.

Change the transparency of a Diagram as a group.

Change the transparency of a Diagram as a group.

Apply a general Key-Value annotation

Monoidal annotations which travel up the diagram tree, i.e. which are aggregated from component diagrams to the whole:

• envelopes (see Diagrams.Core.Envelope). The envelopes are "deletable" meaning that at any point we can throw away the existing envelope and replace it with a new one; sometimes we want to consider a diagram as having a different envelope unrelated to its "natural" envelope.
• traces (see Diagrams.Core.Trace), also deletable.
• name/subdiagram associations (see Diagrams.Core.Names)
• query functions (see Diagrams.Core.Query)

Monoidal annotations which travel down the diagram tree, i.e. which accumulate along each path to a leaf (and which can act on the upwards-travelling annotations):

• styles (see Diagrams.Core.Style)
• names (see Diagrams.Core.Names)

Inject a transformation into a default downwards annotation value.

Extract the (total) transformation from a downwards annotation value.

A leaf in a QDiagram tree is either a Prim, or a "delayed" QDiagram which expands to a real QDiagram once it learns the "final context" in which it will be rendered. For example, in order to decide how to draw an arrow, we must know the precise transformation applied to it (since the arrow head and tail are scale-invariant).

The fundamental diagram type. The type variables are as follows:

• b represents the backend, such as SVG or Cairo. Note that each backend also exports a type synonym B for itself, so the type variable b may also typically be instantiated by B, meaning "use whatever backend is in scope".
• v represents the vector space of the diagram. Typical instantiations include V2 (for a two-dimensional diagram) or V3 (for a three-dimensional diagram).
• n represents the numerical field the diagram uses. Typically this will be a concrete numeric type like Double.
• m is the monoidal type of "query annotations": each point in the diagram has a value of type m associated to it, and these values are combined according to the Monoid instance for m. Most often, m is simply instantiated to Any, associating a simple Bool value to each point indicating whether the point is inside the diagram; Diagram is a synonym for QDiagram with m thus instantiated to Any.

Diagrams can be combined via their Monoid instance, transformed via their Transformable instance, and assigned attributes via their HasStyle instance.

Note that the Q in QDiagram stands for "Queriable", as distinguished from Diagram, where m is fixed to Any. This is not really a very good name, but it's probably not worth changing it at this point.

Diagram b is a synonym for QDiagram b (V b) (N b) Any. That is, the default sort of diagram is one where querying at a point simply tells you whether the diagram contains that point or not. Transforming a default diagram into one with a more interesting query can be done via the Functor instance of QDiagram b v n or the value function.

Create a diagram from a single primitive, along with an envelope, trace, subdiagram map, and query function.

Create a diagram from a generic QDiaLeaf, along with an envelope, trace, subdiagram map, and query function.

Create a "point diagram", which has no content, no trace, an empty query, and a point envelope.

Lens onto the Envelope of a QDiagram.

Lens onto the Trace of a QDiagram.

Lens onto the SubMap of a QDiagram (i.e. an association from names to subdiagrams).

Get a list of names of subdiagrams and their locations.

Get the query function associated with a diagram.

A convenient synonym for mappend on diagrams, designed to be used infix (to help remember which diagram goes on top of which when combining them, namely, the first on top of the second).

Attach an atomic name to a certain subdiagram, computed from the given diagram /with the mapping from name to subdiagram included/. The upshot of this knot-tying is that if d' = d # named x, then lookupName x d' == Just d' (instead of Just d).

Lookup the most recent diagram associated with (some qualification of) the given name.

Given a name and a diagram transformation indexed by a subdiagram, perform the transformation using the most recent subdiagram associated with (some qualification of) the name, or perform the identity transformation if the name does not exist.

Given a name and a diagram transformation indexed by a list of subdiagrams, perform the transformation using the collection of all such subdiagrams associated with (some qualification of) the given name.

Given a list of names and a diagram transformation indexed by a list of subdiagrams, perform the transformation using the list of most recent subdiagrams associated with (some qualification of) each name. Do nothing (the identity transformation) if any of the names do not exist.

"Localize" a diagram by hiding all the names, so they are no longer visible to the outside.

Replace the envelope of a diagram.

Replace the trace of a diagram.

A Subdiagram represents a diagram embedded within the context of a larger diagram. Essentially, it consists of a diagram paired with any accumulated information from the larger context (transformations, attributes, etc.).

Turn a diagram into a subdiagram with no accumulated context.

Turn a subdiagram into a normal diagram, including the enclosing context. Concretely, a subdiagram is a pair of (1) a diagram and (2) a "context" consisting of an extra transformation and attributes. getSub simply applies the transformation and attributes to the diagram to get the corresponding "top-level" diagram.

Extract the "raw" content of a subdiagram, by throwing away the context.

Get the location of a subdiagram; that is, the location of its local origin with respect to the vector space of its parent diagram. In other words, the point where its local origin "ended up".

Create a "point subdiagram", that is, a pointDiagram (with no content and a point envelope) treated as a subdiagram with local origin at the given point. Note this is not the same as mkSubdiagram . pointDiagram, which would result in a subdiagram with local origin at the parent origin, rather than at the given point.

A SubMap is a map associating names to subdiagrams. There can be multiple associations for any given name.

Construct a SubMap from a list of associations between names and subdiagrams.

Add a name/diagram association to a submap.

Look for the given name in a name map, returning a list of subdiagrams associated with that name. If no names match the given name exactly, return all the subdiagrams associated with names of which the given name is a suffix.

A value of type Prim b v n is an opaque (existentially quantified) primitive which backend b knows how to render in vector space v.

Abstract diagrams are rendered to particular formats by backends. Each backend/vector space combination must be an instance of the Backend class.

A minimal complete definition consists of Render, Result, Options, and renderRTree. However, most backends will want to implement adjustDia as well; the default definition does nothing. Some useful standard definitions are provided in the Diagrams.TwoD.Adjust module from the diagrams-lib package.

A DTree is a raw tree representation of a QDiagram, with all the u-annotations removed. It is used as an intermediate type by diagrams-core; backends should not need to make use of it. Instead, backends can make use of RTree, which DTree gets compiled and optimized to.

An RTree is a compiled and optimized representation of a QDiagram, which can be used by backends. They have the following invariant which backends may rely upon:

• RPrim nodes never have any children.

Prism onto a style of an RNode.

Prism onto an annotation of an RNode.

Prism onto a Prim of an RNode.

Prism onto an empty RNode.

A null backend which does no actual rendering. It is provided mainly for convenience in situations where you must give a diagram a concrete, monomorphic type, but don't actually care which one. See D for more explanation and examples.

It is courteous, when defining a new primitive P, to make an instance

instance Renderable P NullBackend where
  render _ _ = mempty

This ensures that the trick with D annotations can be used for diagrams containing your primitive.

The D type is provided for convenience in situations where you must give a diagram a concrete, monomorphic type, but don't care which one. Such situations arise when you pass a diagram to a function which is polymorphic in its input but monomorphic in its output, such as width, height, phantom, or names. Such functions compute some property of the diagram, or use it to accomplish some other purpose, but do not result in the diagram being rendered. If the diagram does not have a monomorphic type, GHC complains that it cannot determine the diagram's type.

For example, here is the error we get if we try to compute the width of an image (this example requires diagrams-lib):

  ghci> width (image (uncheckedImageRef "foo.png" 200 200))
  <interactive>:11:8:
      No instance for (Renderable (DImage n0 External) b0)
        arising from a use of image
      The type variables n0, b0 are ambiguous
      Possible fix: add a type signature that fixes these type variable(s)
      Note: there is a potential instance available:
        instance Fractional n => Renderable (DImage n a) NullBackend
          -- Defined in Image
      Possible fix:
        add an instance declaration for
        (Renderable (DImage n0 External) b0)
      In the first argument of width, namely
        `(image (uncheckedImageRef "foo.png" 200 200))'
      In the expression:
        width (image (uncheckedImageRef "foo.png" 200 200))
      In an equation for it:
          it = width (image (uncheckedImageRef "foo.png" 200 200))
  

GHC complains that there is no instance for Renderable (DImage n0 External) b0; what is really going on is that it does not have enough information to decide what backend to use (hence the uninstantiated n0 and b0). This is annoying because we know that the choice of backend cannot possibly affect the width of the image (it's 200! it's right there in the code!); but there is no way for GHC to know that.

The solution is to annotate the call to image with the type D V2 Double, like so:

  ghci> width (image (uncheckedImageRef "foo.png" 200 200) :: D V2 Double)
  200.00000000000006
  

(It turns out the width wasn't 200 after all...)

As another example, here is the error we get if we try to compute the width of a radius-1 circle:

  ghci> width (circle 1)
  <interactive>:12:1:
      Couldn't match expected type V2 with actual type `V a0'
      The type variable a0 is ambiguous
      Possible fix: add a type signature that fixes these type variable(s)
      In the expression: width (circle 1)
      In an equation for it: it = width (circle 1)
  

There's even more ambiguity here. Whereas image always returns a Diagram, the circle function can produce any TrailLike type, and the width function can consume any Enveloped type, so GHC has no idea what type to pick to go in the middle. However, the solution is the same:

  ghci> width (circle 1 :: D V2 Double)
  1.9999999999999998
  

Constraint for numeric types that are RealFloat and Typeable, which often occur together. This is used to shorten shorten type constraint contexts.

The Renderable type class connects backends to primitives which they know how to render.