Maintainer	diagrams-discuss@googlegroups.com

Diagrams.TwoD

Contents

R^2
Angles
Paths
- Stroking
- Clipping
Shapes
Transformations
Combinators
Alignment
Utilities
Visual aids for understanding the internal model

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:

Diagrams.TwoD.Types defines basic types for two-dimensional diagrams, including types representing the 2D Euclidean vector space and various systems of angle measurement.
Diagrams.TwoD.Align defines alignment combinators specialized to two dimensions (see Diagrams.Align for more general alignment).
Diagrams.TwoD.Combinators defines ways of combining diagrams specialized to two dimensions (see also Diagrams.Combinators for more general combining).
Diagrams.TwoD.Transform defines R^2-specific transformations such as rotation by an angle, and scaling, translation, and reflection in the X and Y directions.
Diagrams.TwoD.Ellipse defines ellipses.
Diagrams.TwoD.Arc defines circular arcs.
Diagrams.TwoD.Path exports various operations on two-dimensional paths when viewed as regions of the plane.
Diagrams.TwoD.Shapes defines other two-dimensional shapes, e.g. various polygons.
Diagrams.TwoD.Util defines some two-dimensional utilities, such as unit vectors and functions for computing the size and extent of diagrams in R^2.
Diagrams.TwoD.Model defines some aids for visualizing diagrams' internal model (local origins, bounding regions, etc.)

Synopsis

R^2

type R2 = (Double, Double)Source

The two-dimensional Euclidean vector space R^2.

type P2 = Point R2 Source

Points in R^2.

unitX :: R2 Source

The unit vector in the positive X direction.

unitY :: R2 Source

The unit vector in the positive Y direction.

unit_X :: R2 Source

The unit vector in the negative X direction.

unit_Y :: R2 Source

The unit vector in the negative Y direction.

direction :: R2 -> CircleFrac Source

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 -> CircleFrac Source

Convert to a fraction of a circle.

fromCircleFrac :: CircleFrac -> aSource

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
Fields getCircleFrac :: Double

newtype Rad Source

Newtype wrapper for representing angles in radians.

Constructors

Rad
Fields getRad :: Double

Instances

Enum Rad
Eq Rad
Floating Rad
Fractional Rad
Num Rad
Ord Rad
Read Rad
Real Rad
RealFloat Rad
RealFrac Rad
Show Rad
Angle Rad	tau radians = 1 full circle.

newtype Deg Source

Newtype wrapper for representing angles in degrees.

Constructors

Deg
Fields getDeg :: 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 R2 Source

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 R2 Source

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 R2 Source

Create a centered horizontal line of the given length.

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

Create a centered vertical line of the given length.

Circle-ish things

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

A circle of radius 1.

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

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 R2 Source

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.

polygonVertices :: PolygonOpts -> [P2]Source

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

data PolygonOpts Source

Constructors

PolygonOpts
Fields sides :: Int Number of sides; the default is 5. edgeSkip :: Int Create 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 :: PolygonOrientation Determine how the polygon should be oriented.

Instances

Eq PolygonOpts
Ord PolygonOpts
Read PolygonOpts
Show PolygonOpts
Default PolygonOpts

data PolygonOrientation Source

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.

Instances

Eq PolygonOrientation
Ord PolygonOrientation
Read PolygonOrientation
Show PolygonOrientation

Special polygons

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

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 R2 Source

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 R2 Source

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

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

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.

roundedRect :: (Backend b R2, Renderable (Path R2) b) => R2 -> Double -> Diagram b R2 Source

Transformations

Rotation

rotation :: Angle a => a -> T2 Source

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 -> T2 Source

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

scalingX :: Double -> T2 Source

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.

scalingY :: Double -> T2 Source

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

translationX :: Double -> T2 Source

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.

translationY :: Double -> T2 Source

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

reflectionX :: T2 Source

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).

reflectionY :: T2 Source

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 :: P2 -> R2 -> T2 Source

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 -> Double Source

Compute the width of a diagram.

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

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 -> P2 Source

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.

Enum CircleFrac
Eq CircleFrac
Floating CircleFrac
Fractional CircleFrac
Num CircleFrac
Ord CircleFrac
Read CircleFrac
Real CircleFrac
RealFloat CircleFrac
RealFrac CircleFrac
Show CircleFrac
Angle CircleFrac