diagrams-lib-0.2: Embedded domain-specific language for declarative graphics

Diagrams.TwoD

Description

This module defines the two-dimensional vector space R^2, two-dimensional transformations, and various predefined two-dimensional shapes. This module re-exports useful functionality from a group of more specific modules:

Synopsis

# R^2

type R2 = (Double, Double)Source

The two-dimensional Euclidean vector space R^2.

type P2 = Point R2Source

Points in R^2.

The unit vector in the positive X direction.

The unit vector in the positive Y direction.

The unit vector in the negative X direction.

The unit vector in the negative Y direction.

Compute the direction of a vector, measured counterclockwise from the positive x-axis as a fraction of a full turn. The zero vector is arbitrarily assigned the direction 0.

# Angles

tau :: Floating a => aSource

The circle constant, i.e. the ratio of a circle's circumference to its radius.

class Num a => Angle a whereSource

Type class for types that measure angles.

Methods

toCircleFrac :: a -> CircleFracSource

Convert to a fraction of a circle.

Convert from a fraction of a circle.

Instances

 Angle Deg 360 degrees = 1 full circle. Angle Rad tau radians = 1 full circle. Angle CircleFrac

newtype CircleFrac Source

Newtype wrapper used to represent angles as fractions of a circle. For example, 13 = tau3 radians = 120 degrees.

Constructors

 CircleFrac FieldsgetCircleFrac :: Double

Newtype wrapper for representing angles in radians.

Constructors

Instances

newtype Deg Source

Newtype wrapper for representing angles in degrees.

Constructors

 Deg FieldsgetDeg :: Double

Instances

 Enum Deg Eq Deg Floating Deg Fractional Deg Num Deg Ord Deg Read Deg Real Deg RealFloat Deg RealFrac Deg Show Deg Angle Deg 360 degrees = 1 full circle.

fullCircle :: Angle a => aSource

An angle representing a full circle.

convertAngle :: (Angle a, Angle b) => a -> bSource

Convert between two angle representations.

# Paths

## Stroking

stroke :: Renderable (Path R2) b => Path R2 -> Diagram b R2Source

Convert a path into a diagram. The resulting diagram has the names 0, 1, ... assigned to each of the path's vertices.

Note that a bug in GHC 7.0.1 causes a context stack overflow when inferring the type of `stroke`. The solution is to give a type signature to expressions involving `stroke`, or (recommended) upgrade GHC (the bug is fixed in 7.0.2 onwards).

strokeT :: Renderable (Path R2) b => Trail R2 -> Diagram b R2Source

A composition of `stroke` and `pathFromTrail` for conveniently converting a trail directly into a diagram.

Note that a bug in GHC 7.0.1 causes a context stack overflow when inferring the type of `stroke` and hence of `strokeT` as well. The solution is to give a type signature to expressions involving `strokeT`, or (recommended) upgrade GHC (the bug is fixed in 7.0.2 onwards).

## Clipping

newtype Clip Source

`Clip` tracks the accumulated clipping paths applied to a diagram. Note that the semigroup structure on `Clip` is list concatenation, so applying multiple clipping paths is sensible. The clipping region is the intersection of all the applied clipping paths.

Constructors

 Clip [Path R2]

Instances

 Typeable Clip Semigroup Clip AttributeClass Clip Transformable Clip

clipBy :: (HasStyle a, V a ~ R2) => Path R2 -> a -> aSource

Clip a diagram by the given path:

• Only the parts of the diagram which lie in the interior of the path will be drawn.
• The bounding function of the diagram is unaffected.

# Shapes

## Rules

hrule :: (Backend b R2, Renderable (Path R2) b) => Double -> Diagram b R2Source

Create a centered horizontal line of the given length.

vrule :: (Backend b R2, Renderable (Path R2) b) => Double -> Diagram b R2Source

Create a centered vertical line of the given length.

## Circle-ish things

circle :: (Backend b R2, Renderable Ellipse b) => Diagram b R2Source

ellipse :: (Backend b R2, Renderable Ellipse b) => Double -> Diagram b R2Source

`ellipse e` constructs an ellipse with eccentricity `e` by scaling the unit circle in the X direction. The eccentricity must be within the interval [0,1).

arc :: (Angle a, PathLike p, V p ~ R2) => a -> a -> pSource

Given a start angle `s` and an end angle `e`, `arc s e` is the path of a radius one arc counterclockwise between the two angles.

## General polygons

polygon :: (Backend b R2, Renderable (Path R2) b) => PolygonOpts -> Diagram b R2Source

Create a regular polygon from the given options.

polygonPath :: (PathLike p, V p ~ R2) => PolygonOpts -> pSource

Create a closed regular polygonal path from the given options.

Generate the vertices of a regular polygon from the given options.

Constructors

 PolygonOpts Fieldssides :: IntNumber of sides; the default is 5. edgeSkip :: IntCreate star polygons by setting the edge skip to some number other than 1 (the default). With an edge skip of n, edges will connect every nth vertex. orientation :: PolygonOrientationDetermine how the polygon should be oriented.

Determine how a polygon should be oriented.

Constructors

 NoOrient No special orientation; one vertex will be at (1,0). This is the default. OrientToX Orient so the botommost edge is parallel to the x-axis. OrientToY Orient so the leftmost edge is parallel to the y-axis.

## Special polygons

square :: (Backend b R2, Renderable (Path R2) b) => Diagram b R2Source

A sqaure with its center at the origin and sides of length 1, oriented parallel to the axes.

rect :: (Backend b R2, Renderable (Path R2) b) => Double -> Double -> Diagram b R2Source

`rect w h` is an axis-aligned rectangle of width `w` and height `h`, centered at the origin.

starPolygon :: (Backend b R2, Renderable (Path R2) b) => Int -> Int -> Diagram b R2Source

`starPolygon p q` creates a star polygon, where `p` indicates the number of vertices, and an edge connects every `q`th vertex.

eqTriangle :: (Backend b R2, Renderable (Path R2) b) => Diagram b R2Source

An equilateral triangle, with radius 1 and base parallel to the x-axis.

## Other shapes

roundedRectPath :: (PathLike p, V p ~ R2) => R2 -> Double -> pSource

`roundedRectPath v r` generates a closed trail, or closed path centered at the origin, of an axis-aligned rectangle with diagonal `v` and circular rounded corners of radius `r`. `r` must be between `0` and half the smaller dimension of `v`, inclusive; smaller or larger values of `r` will be treated as `0` or half the smaller dimension of `v`, respectively. The trail or path begins with the right edge and proceeds counterclockwise.

# Transformations

## Rotation

rotation :: Angle a => a -> T2Source

Create a transformation which performs a rotation by the given angle. See also `rotate`.

rotate :: (Transformable t, V t ~ R2, Angle a) => a -> t -> tSource

Rotate by the given angle. Positive angles correspond to counterclockwise rotation, negative to clockwise. The angle can be expressed using any type which is an instance of `Angle`. For example, `rotate (14 :: 'CircleFrac')@, @rotate (pi2 :: Rad)`, and `rotate (90 :: Deg)` all represent the same transformation, namely, a counterclockwise rotation by a right angle.

Note that writing `rotate (1/4)`, with no type annotation, will yield an error since GHC cannot figure out which sort of angle you want to use. In this common situation you can use `rotateBy`, which is specialized to take a `CircleFrac` argument.

rotateBy :: (Transformable t, V t ~ R2) => CircleFrac -> t -> tSource

A synonym for `rotate`, specialized to only work with `CircleFrac` arguments; it can be more convenient to write `rotateBy (14)@ than @'rotate' (14 :: CircleFrac)`.

rotationAbout :: Angle a => P2 -> a -> T2Source

`rotationAbout p` is a rotation about the point `p` (instead of around the local origin).

rotateAbout :: (Transformable t, V t ~ R2, Angle a) => P2 -> a -> t -> tSource

`rotateAbout p` is like `rotate`, except it rotates around the point `p` instead of around the local origin.

## Scaling

Construct a transformation which scales by the given factor in the x (horizontal) direction.

scaleX :: (Transformable t, V t ~ R2) => Double -> t -> tSource

Scale a diagram by the given factor in the x (horizontal) direction. To scale uniformly, use `Graphics.Rendering.Diagrams.Transform.scale`.

Construct a transformation which scales by the given factor in the y (vertical) direction.

scaleY :: (Transformable t, V t ~ R2) => Double -> t -> tSource

Scale a diagram by the given factor in the y (vertical) direction. To scale uniformly, use `Graphics.Rendering.Diagrams.Transform.scale`.

scaling :: (HasLinearMap v, Fractional (Scalar v)) => Scalar v -> Transformation v

Create a uniform scaling transformation.

scale :: (Transformable t, Fractional (Scalar (V t))) => Scalar (V t) -> t -> t

Scale uniformly in every dimension by the given scalar.

scaleToX :: (Boundable t, Transformable t, V t ~ R2) => Double -> t -> tSource

`scaleToX w` scales a diagram in the x (horizontal) direction by whatever factor required to make its width `w`. `scaleToX` should not be applied to diagrams with a width of 0, such as `vrule`.

scaleToY :: (Boundable t, Transformable t, V t ~ R2) => Double -> t -> tSource

`scaleToY h` scales a diagram in the y (vertical) direction by whatever factor required to make its height `h`. `scaleToY` should not be applied to diagrams with a width of 0, such as `hrule`.

## Translation

Construct a transformation which translates by the given distance in the x (horizontal) direction.

translateX :: (Transformable t, V t ~ R2) => Double -> t -> tSource

Translate a diagram by the given distance in the x (horizontal) direction.

Construct a transformation which translates by the given distance in the y (vertical) direction.

translateY :: (Transformable t, V t ~ R2) => Double -> t -> tSource

Translate a diagram by the given distance in the y (vertical) direction.

translation :: HasLinearMap v => v -> Transformation v

Create a translation.

translate :: (Transformable t, HasLinearMap (V t)) => V t -> t -> t

Translate by a vector.

## Reflection

Construct a transformation which flips a diagram from left to right, i.e. sends the point (x,y) to (-x,y).

reflectX :: (Transformable t, V t ~ R2) => t -> tSource

Flip a diagram from left to right, i.e. send the point (x,y) to (-x,y).

Construct a transformation which flips a diagram from top to bottom, i.e. sends the point (x,y) to (x,-y).

reflectY :: (Transformable t, V t ~ R2) => t -> tSource

Flip a diagram from top to bottom, i.e. send the point (x,y) to (x,-y).

`reflectionAbout p v` is a reflection in the line determined by the point `p` and vector `v`.

reflectAbout :: (Transformable t, V t ~ R2) => P2 -> R2 -> t -> tSource

`reflectAbout p v` reflects a diagram in the line determined by the point `p` and the vector `v`.

# Combinators

strutX :: (Backend b R2, Monoid m) => Double -> AnnDiagram b R2 mSource

`strutX d` is an empty diagram with width `d` and height 0.

strutY :: (Backend b R2, Monoid m) => Double -> AnnDiagram b R2 mSource

`strutY d` is an empty diagram with height `d` and width 0.

(===) :: (HasOrigin a, Boundable a, V a ~ R2, Monoid a) => a -> a -> aSource

Place two diagrams (or other boundable objects) vertically adjacent to one another, with the first diagram above the second. Since Haskell ignores whitespace in expressions, one can thus write

```    c
===
d
```

to place `c` above `d`.

(|||) :: (HasOrigin a, Boundable a, V a ~ R2, Monoid a) => a -> a -> aSource

Place two diagrams (or other boundable objects) horizontally adjacent to one another, with the first diagram to the left of the second.

hcat :: (HasOrigin a, Boundable a, Qualifiable a, V a ~ R2, Monoid a) => [a] -> aSource

Lay out a list of boundable objects in a row from left to right, so that their local origins lie along a single horizontal line, with successive bounding regions tangent to one another.

• For more control over the spacing, see `hcat'`.
• To align the diagrams vertically (or otherwise), use alignment combinators (such as `alignT` or `alignB`) from Diagrams.TwoD.Align before applying `hcat`.
• For non-axis-aligned layout, see `cat`.

hcat' :: (HasOrigin a, Boundable a, Qualifiable a, V a ~ R2, Monoid a) => CatOpts R2 -> [a] -> aSource

A variant of `hcat` taking an extra `CatOpts` record to control the spacing. See the `cat'` documentation for a description of the possibilities.

vcat :: (HasOrigin a, Boundable a, Qualifiable a, V a ~ R2, Monoid a) => [a] -> aSource

Lay out a list of boundable objects in a column from top to bottom, so that their local origins lie along a single vertical line, with successive bounding regions tangent to one another.

• For more control over the spacing, see `vcat'`.
• To align the diagrams horizontally (or otherwise), use alignment combinators (such as `alignL` or `alignR`) from Diagrams.TwoD.Align before applying `vcat`.
• For non-axis-aligned layout, see `cat`.

vcat' :: (HasOrigin a, Boundable a, Qualifiable a, V a ~ R2, Monoid a) => CatOpts R2 -> [a] -> aSource

A variant of `vcat` taking an extra `CatOpts` record to control the spacing. See the `cat'` documentation for a description of the possibilities.

# Alignment

alignL :: (HasOrigin a, Boundable a, V a ~ R2) => a -> aSource

Align along the left edge, i.e. translate the diagram in a horizontal direction so that the local origin is on the left edge of the bounding region.

alignR :: (HasOrigin a, Boundable a, V a ~ R2) => a -> aSource

Align along the right edge.

alignT :: (HasOrigin a, Boundable a, V a ~ R2) => a -> aSource

Align along the top edge.

alignB :: (HasOrigin a, Boundable a, V a ~ R2) => a -> aSource

Align along the bottom edge.

alignTL :: (HasOrigin a, Boundable a, V a ~ R2) => a -> aSource

alignTR :: (HasOrigin a, Boundable a, V a ~ R2) => a -> aSource

alignBL :: (HasOrigin a, Boundable a, V a ~ R2) => a -> aSource

alignBR :: (HasOrigin a, Boundable a, V a ~ R2) => a -> aSource

alignX :: (HasOrigin a, Boundable a, V a ~ R2) => Rational -> a -> aSource

`alignX` moves the local origin horizontally as follows:

• `alignX (-1)` moves the local origin to the left edge of the bounding region;
• `align 1` moves the local origin to the right edge;
• any other argument interpolates linearly between these. For example, `alignX 0` centers, `alignX 2` moves the origin one "radius" to the right of the right edge, and so on.

alignY :: (HasOrigin a, Boundable a, V a ~ R2) => Rational -> a -> aSource

Like `alignX`, but moving the local origin vertically, with an argument of `1` corresponding to the top edge and `(-1)` corresponding to the bottom edge.

centerX :: (HasOrigin a, Boundable a, V a ~ R2) => a -> aSource

Center the local origin along the X-axis.

centerY :: (HasOrigin a, Boundable a, V a ~ R2) => a -> aSource

Center the local origin along the Y-axis.

centerXY :: (HasOrigin a, Boundable a, V a ~ R2) => a -> aSource

Center along both the X- and Y-axes.

# Utilities

width :: (Boundable a, V a ~ R2) => a -> DoubleSource

Compute the width of a diagram.

height :: (Boundable a, V a ~ R2) => a -> DoubleSource

Compute the height of a diagram.

size2D :: (Boundable a, V a ~ R2) => a -> (Double, Double)Source

Compute the width and height of a diagram.

extentX :: (Boundable a, V a ~ R2) => a -> (Double, Double)Source

Compute the absolute x-coordinate range of a diagram in R2, in the form (lo,hi).

extentY :: (Boundable a, V a ~ R2) => a -> (Double, Double)Source

Compute the absolute y-coordinate range of a diagram in R2, in the form (lo,hi).

center2D :: (Boundable a, V a ~ R2) => a -> P2Source

Compute the point at the center (in the x- and y-directions) of a diagram.

# Visual aids for understanding the internal model

showOrigin :: (Renderable Ellipse b, Backend b R2, Monoid m) => AnnDiagram b R2 m -> AnnDiagram b R2 mSource

Mark the origin of a diagram by placing a red dot 1/50th its size.