diagrams-core-1.3.0.5: Core libraries for diagrams EDSL

Copyright(c) 2011-2015 diagrams-core team (see LICENSE)
LicenseBSD-style (see LICENSE)
Maintainerdiagrams-discuss@googlegroups.com
Safe HaskellNone
LanguageHaskell2010

Diagrams.Core

Contents

Description

The core library of primitives forming the basis of an embedded domain-specific language for describing and rendering diagrams. Normal users of the diagrams library should almost never need to import anything from this package directly; instead, import modules (especially Diagrams.Prelude) from the diagrams-lib package, which re-exports most things of value to users.

For most library code needing access to core internals, it should be sufficient to import this module, which simply re-exports useful functionality from other modules in the core library. Library writers needing finer-grained access or functionality may occasionally find it useful to directly import one of the constituent core modules.

The diagrams library relies heavily on custom types and classes. Many of the relevant definitions are in the Diagrams.Core.Types module. Indeed the definition of the diagram type QDiagram is contained in: QDiagram.

The best place to start when learning about diagrams' types is the user manual: http://projects.haskell.org/diagrams/doc/manual.html#type-reference The following list shows which types are contained in each module of Diagrams.Core.

Synopsis

Associated vector spaces

type family V a :: * -> * Source

Many sorts of objects have an associated vector space in which they "live". The type function V maps from object types to the associated vector space. The resulting vector space has kind * -> * which means it takes another value (a number) and returns a concrete vector. For example V2 has kind * -> * and V2 Double is a vector.

Instances

type V [a] = V a Source 
type V (Set a) = V a Source 
type V (Split m) = V m Source 
type V (Deletable m) = V m Source 
type V (Option a) = V a Source 
type V (TransInv t) = V t Source 
type V (a -> b) = V b Source 
type V (a, b) = V a Source 
type V (Map k a) = V a Source 
type V (Point v n) = v Source 
type V ((:+:) m n) = V m Source 
type V (Measured n a) = V a Source 
type V (Transformation v n) = v Source 
type V (Style v n) = v Source 
type V (Attribute v n) = v Source 
type V (Trace v n) = v Source 
type V (Envelope v n) = v Source 
type V (a, b, c) = V a Source 
type V (Query v n m) = v Source 
type V (Prim b v n) = v Source 
type V (SubMap b v n m) = v Source 
type V (Subdiagram b v n m) = v Source 
type V (QDiagram b v n m) = v Source 

type family N a :: * Source

The numerical field for the object, the number type used for calculations.

Instances

type N [a] = N a Source 
type N (Set a) = N a Source 
type N (Split m) = N m Source 
type N (Deletable m) = N m Source 
type N (Option a) = N a Source 
type N (TransInv t) = N t Source 
type N (a -> b) = N b Source 
type N (a, b) = N a Source 
type N (Map k a) = N a Source 
type N (Point v n) = n Source 
type N ((:+:) m n) = N m Source 
type N (Measured n a) = N a Source 
type N (Transformation v n) = n Source 
type N (Style v n) = n Source 
type N (Attribute v n) = n Source 
type N (Trace v n) = n Source 
type N (Envelope v n) = n Source 
type N (a, b, c) = N a Source 
type N (Query v n m) = n Source 
type N (Prim b v n) = n Source 
type N (SubMap b v n m) = n Source 
type N (Subdiagram b v n m) = n Source 
type N (QDiagram b v n m) = n Source 

type Vn a = V a (N a) Source

Conveient type alias to retrieve the vector type associated with an object's vector space. This is usually used as Vn a ~ v n where v is the vector space and n is the numerical field.

class (V a ~ v, N a ~ n, Additive v, Num n) => InSpace v n a Source

InSpace v n a means the type a belongs to the vector space v n, where v is Additive and n is a Num.

Instances

((~) (* -> *) (V a) v, (~) * (N a) n, Additive v, Num n) => InSpace v n a Source 

class (V a ~ V b, N a ~ N b) => SameSpace a b Source

SameSpace a b means the types a and b belong to the same vector space v n.

Instances

((~) (* -> *) (V a) (V b), (~) * (N a) (N b)) => SameSpace a b Source 

Points

data Point f a :: (* -> *) -> * -> *

A handy wrapper to help distinguish points from vectors at the type level

Instances

Unbox (f a) => Vector Vector (Point f a) 
Unbox (f a) => MVector MVector (Point f a) 
Monad f => Monad (Point f) 
Functor f => Functor (Point f) 
Applicative f => Applicative (Point f) 
Foldable f => Foldable (Point f) 
Traversable f => Traversable (Point f) 
Generic1 (Point f) 
Distributive f => Distributive (Point f) 
Representable f => Representable (Point f) 
Serial1 f => Serial1 (Point f) 
Additive f => Affine (Point f) 
R4 f => R4 (Point f) 
R3 f => R3 (Point f) 
R2 f => R2 (Point f) 
R1 f => R1 (Point f) 
Metric f => Metric (Point f) 
Additive f => Additive (Point f) 
Apply f => Apply (Point f) 
Bind f => Bind (Point f) 
Eq1 f => Eq1 (Point f) 
Ord1 f => Ord1 (Point f) 
Read1 f => Read1 (Point f) 
Show1 f => Show1 (Point f) 
Eq (f a) => Eq (Point f a) 
Fractional (f a) => Fractional (Point f a) 
(Data (f a), Typeable (* -> *) f, Typeable * a) => Data (Point f a) 
Num (f a) => Num (Point f a) 
Ord (f a) => Ord (Point f a) 
Read (f a) => Read (Point f a) 
Show (f a) => Show (Point f a) 
Ix (f a) => Ix (Point f a) 
Generic (Point f a) 
Storable (f a) => Storable (Point f a) 
Binary (f a) => Binary (Point f a) 
Serial (f a) => Serial (Point f a) 
Serialize (f a) => Serialize (Point f a) 
NFData (f a) => NFData (Point f a) 
Hashable (f a) => Hashable (Point f a) 
Unbox (f a) => Unbox (Point f a) 
Ixed (f a) => Ixed (Point f a) 
Wrapped (Point f a) 
Epsilon (f a) => Epsilon (Point f a) 
(Additive v, Num n) => HasOrigin (Point v n) Source 
(Additive v, Num n) => Transformable (Point v n) Source 
(Additive v, Ord n) => Traced (Point v n) Source

The trace of a single point is the empty trace, i.e. the one which returns no intersection points for every query. Arguably it should return a single finite distance for vectors aimed directly at the given point, but due to floating-point inaccuracy this is problematic. Note that the envelope for a single point is not the empty envelope (see Diagrams.Core.Envelope).

(OrderedField n, Metric v) => Enveloped (Point v n) Source 
(~) * t (Point g b) => Rewrapped (Point f a) t 
Traversable f => Each (Point f a) (Point f b) a b 
data MVector s (Point f a) = MV_P !(MVector s (f a)) 
type Rep1 (Point f) = D1 D1Point (C1 C1_0Point (S1 NoSelector (Rec1 f))) 
type Rep (Point f) = Rep f 
type Diff (Point f) = f 
type Rep (Point f a) = D1 D1Point (C1 C1_0Point (S1 NoSelector (Rec0 (f a)))) 
data Vector (Point f a) = V_P !(Vector (f a)) 
type Index (Point f a) = Index (f a) 
type IxValue (Point f a) = IxValue (f a) 
type Unwrapped (Point f a) = f a 
type N (Point v n) = n Source 
type V (Point v n) = v Source 

origin :: (Additive f, Num a) => Point f a

Vector spaces have origins.

(*.) :: (Functor v, Num n) => n -> Point v n -> Point v n Source

Scale a point by a scalar. Specialized version of '(*^)'.

relative :: (Additive f, Num a) => Point f a -> Iso' (Point f a) (f a)

An isomorphism between points and vectors, given a reference point.

Transformations

Utilities

basis :: (Additive t, Traversable t, Num a) => [t a]

Produce a default basis for a vector space. If the dimensionality of the vector space is not statically known, see basisFor.

dimension :: forall a v. (V a ~ v, Additive v, Traversable v) => a -> Int Source

Get the dimension of an object whose vector space is an instance of HasLinearMap, e.g. transformations, paths, diagrams, etc.

determinant :: (Additive v, Traversable v, Num n) => Transformation v n -> n Source

The determinant of (the linear part of) a Transformation.

isReflection :: (Additive v, Traversable v, Num n, Ord n) => Transformation v n -> Bool Source

Determine whether a Transformation includes a reflection component, that is, whether it reverses orientation.

Invertible linear transformations

data u :-: v infixr 7 Source

(v1 :-: v2) is a linear map paired with its inverse.

Instances

Monoid ((:-:) v v) Source

Invertible linear maps from a vector space to itself form a monoid under composition.

Semigroup ((:-:) a a) Source 

(<->) :: (u -> v) -> (v -> u) -> u :-: v Source

Create an invertible linear map from two functions which are assumed to be linear inverses.

linv :: (u :-: v) -> v :-: u Source

Invert a linear map.

lapp :: (u :-: v) -> u -> v Source

Apply a linear map to a vector.

General transformations

data Transformation v n Source

General (affine) transformations, represented by an invertible linear map, its transpose, and a vector representing a translation component.

By the transpose of a linear map we mean simply the linear map corresponding to the transpose of the map's matrix representation. For example, any scale is its own transpose, since scales are represented by matrices with zeros everywhere except the diagonal. The transpose of a rotation is the same as its inverse.

The reason we need to keep track of transposes is because it turns out that when transforming a shape according to some linear map L, the shape's normal vectors transform according to L's inverse transpose. (For a more detailed explanation and proof, see https://wiki.haskell.org/Diagrams/Dev/Transformations.) This is exactly what we need when transforming bounding functions, which are defined in terms of perpendicular (i.e. normal) hyperplanes.

For more general, non-invertible transformations, see Diagrams.Deform (in diagrams-lib).

Instances

(Additive v, Num n) => Monoid (Transformation v n) Source 
(Additive v, Num n) => Semigroup (Transformation v n) Source

Transformations are closed under composition; t1 <> t2 is the transformation which performs first t2, then t1.

(Additive v, Num n) => HasOrigin (Transformation v n) Source 
(Additive v, Num n) => Transformable (Transformation v n) Source 
(Transformable a, (~) (* -> *) (V a) v, (~) * (N a) n) => Action (Transformation v n) a Source

Transformations can act on transformable things.

type N (Transformation v n) = n Source 
type V (Transformation v n) = v Source 

inv :: (Functor v, Num n) => Transformation v n -> Transformation v n Source

Invert a transformation.

transp :: Transformation v n -> v n :-: v n Source

Get the transpose of a transformation (ignoring the translation component).

transl :: Transformation v n -> v n Source

Get the translational component of a transformation.

dropTransl :: (Additive v, Num n) => Transformation v n -> Transformation v n Source

Drop the translational component of a transformation, leaving only the linear part.

apply :: Transformation v n -> v n -> v n Source

Apply a transformation to a vector. Note that any translational component of the transformation will not affect the vector, since vectors are invariant under translation.

papply :: (Additive v, Num n) => Transformation v n -> Point v n -> Point v n Source

Apply a transformation to a point.

fromLinear :: (Additive v, Num n) => (v n :-: v n) -> (v n :-: v n) -> Transformation v n Source

Create a general affine transformation from an invertible linear transformation and its transpose. The translational component is assumed to be zero.

Some specific transformations

translation :: v n -> Transformation v n Source

Create a translation.

translate :: (Num (N t), Transformable t) => Vn t -> t -> t Source

Translate by a vector.

moveTo :: (InSpace v n t, HasOrigin t) => Point v n -> t -> t Source

Translate the object by the translation that sends the origin to the given point. Note that this is dual to moveOriginTo, i.e. we should have

  moveTo (origin .^+ v) === moveOriginTo (origin .^- v)
  

For types which are also Transformable, this is essentially the same as translate, i.e.

  moveTo (origin .^+ v) === translate v
  

place :: (InSpace v n t, HasOrigin t) => t -> Point v n -> t Source

A flipped variant of moveTo, provided for convenience. Useful when writing a function which takes a point as an argument, such as when using withName and friends.

scaling :: (Additive v, Fractional n) => n -> Transformation v n Source

Create a uniform scaling transformation.

scale :: (InSpace v n a, Eq n, Fractional n, Transformable a) => n -> a -> a Source

Scale uniformly in every dimension by the given scalar.

avgScale :: (Additive v, Traversable v, Floating n) => Transformation v n -> n Source

Compute the "average" amount of scaling performed by a transformation. Satisfies the properties

  avgScale (scaling k) == k
  avgScale (t1 <> t2)  == avgScale t1 * avgScale t2
  

The Transformable class

class Transformable t where Source

Type class for things t which can be transformed.

Methods

transform :: Transformation (V t) (N t) -> t -> t Source

Apply a transformation to an object.

Instances

Transformable t => Transformable [t] Source 
(Transformable t, Ord t) => Transformable (Set t) Source 
Transformable m => Transformable (Deletable m) Source 
(Num (N t), Additive (V t), Transformable t) => Transformable (TransInv t) Source 
((~) (* -> *) (V t) v, (~) * (N t) n, (~) (* -> *) (V t) (V s), (~) * (N t) (N s), Functor v, Num n, Transformable t, Transformable s) => Transformable (s -> t) Source 
(Transformable t, Transformable s, (~) (* -> *) (V t) (V s), (~) * (N t) (N s)) => Transformable (t, s) Source 
Transformable t => Transformable (Map k t) Source 
(Additive v, Num n) => Transformable (Point v n) Source 
(Additive v, Num n) => Transformable (Transformation v n) Source 
(Additive v, Traversable v, Floating n) => Transformable (Style v n) Source 
(Additive v, Traversable v, Floating n) => Transformable (Attribute v n) Source

TAttributes are transformed directly, MAttributes have their local scale multiplied by the average scale of the transform. Plain Attributes are unaffected.

(Additive v, Num n) => Transformable (Trace v n) Source 
(Metric v, Floating n) => Transformable (Envelope v n) Source 
(Transformable t, Transformable s, Transformable u, (~) (* -> *) (V s) (V t), (~) * (N s) (N t), (~) (* -> *) (V s) (V u), (~) * (N s) (N u)) => Transformable (t, s, u) Source 
(Additive v, Num n) => Transformable (Query v n m) Source 
Transformable (Prim b v n) Source

The Transformable instance for Prim just pushes calls to transform down through the Prim constructor.

(Metric v, Floating n) => Transformable (SubMap b v n m) Source 
(Metric v, Floating n) => Transformable (Subdiagram b v n m) Source 
(OrderedField n, Metric v, Semigroup m) => Transformable (QDiagram b v n m) Source

Diagrams can be transformed by transforming each of their components appropriately.

Translational invariance

newtype TransInv t Source

TransInv is a wrapper which makes a transformable type translationally invariant; the translational component of transformations will no longer affect things wrapped in TransInv.

Constructors

TransInv t 

eye :: (HasBasis v, Num n) => v (v n) Source

Identity matrix.

Names

data AName Source

Atomic names. AName is just an existential wrapper around things which are Typeable, Ord and Show.

data Name Source

A (qualified) name is a (possibly empty) sequence of atomic names.

Instances

Eq Name Source 
Ord Name Source 
Show Name Source 
Monoid Name Source 
Semigroup Name Source 
Wrapped Name Source 
Qualifiable Name Source

Of course, names can be qualified using (.>).

IsName Name Source 
Rewrapped Name Name Source 
Action Name (SubMap b v n m)

A name acts on a name map by qualifying every name in it.

type Unwrapped Name = [AName] Source 

class (Typeable a, Ord a, Show a) => IsName a where Source

Class for those types which can be used as names. They must support Typeable (to facilitate extracting them from existential wrappers), Ord (for comparison and efficient storage) and Show.

To make an instance of IsName, you need not define any methods, just declare it.

WARNING: it is not recommended to use GeneralizedNewtypeDeriving in conjunction with IsName, since in that case the underlying type and the newtype will be considered equivalent when comparing names. For example:

    newtype WordN = WordN Int deriving (Show, Ord, Eq, Typeable, IsName)
  

is unlikely to work as intended, since (1 :: Int) and (WordN 1) will be considered equal as names. Instead, use

    newtype WordN = WordN Int deriving (Show, Ord, Eq, Typeable, IsName)
    instance IsName WordN
  

Minimal complete definition

Nothing

Methods

toName :: a -> Name Source

class Qualifiable q where Source

Instances of Qualifiable are things which can be qualified by prefixing them with a name.

Methods

(.>>) :: IsName a => a -> q -> q infixr 5 Source

Qualify with the given name.

Instances

Qualifiable Name Source

Of course, names can be qualified using (.>).

Qualifiable a => Qualifiable [a] Source 
(Ord a, Qualifiable a) => Qualifiable (Set a) Source 
Qualifiable a => Qualifiable (TransInv a) Source 
Qualifiable a => Qualifiable (b -> a) Source 
(Qualifiable a, Qualifiable b) => Qualifiable (a, b) Source 
Qualifiable a => Qualifiable (Map k a) Source 
Qualifiable a => Qualifiable (Measured n a) Source 
(Qualifiable a, Qualifiable b, Qualifiable c) => Qualifiable (a, b, c) Source 
Qualifiable (SubMap b v n m) Source

SubMaps are qualifiable: if ns is a SubMap, then a |> ns is the same SubMap except with every name qualified by a.

(Metric v, OrderedField n, Semigroup m) => Qualifiable (QDiagram b v n m) Source

Diagrams can be qualified so that all their named points can now be referred to using the qualification prefix.

(.>) :: (IsName a1, IsName a2) => a1 -> a2 -> Name infixr 5 Source

Convenient operator for writing qualified names with atomic components of different types. Instead of writing toName a1 <> toName a2 <> toName a3 you can just write a1 .> a2 .> a3.

Subdiagram maps

newtype SubMap b v n m Source

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

Constructors

SubMap (Map Name [Subdiagram b v n m]) 

Instances

Action Name (SubMap b v n m) Source

A name acts on a name map by qualifying every name in it.

Functor (SubMap b v n) Source 
Monoid (SubMap b v n m) Source

SubMaps form a monoid with the empty map as the identity, and map union as the binary operation. No information is ever lost: if two maps have the same name in their domain, the resulting map will associate that name to the concatenation of the information associated with that name.

Semigroup (SubMap b v n m) Source 
Wrapped (SubMap b v n m) Source 
(OrderedField n, Metric v) => HasOrigin (SubMap b v n m) Source 
(Metric v, Floating n) => Transformable (SubMap b v n m) Source 
Qualifiable (SubMap b v n m) Source

SubMaps are qualifiable: if ns is a SubMap, then a |> ns is the same SubMap except with every name qualified by a.

Rewrapped (SubMap b v n m) (SubMap b' v' n' m') Source 
type Unwrapped (SubMap b v n m) = Map Name [Subdiagram b v n m] Source 
type N (SubMap b v n m) = n Source 
type V (SubMap b v n m) = v Source 

fromNames :: IsName a => [(a, Subdiagram b v n m)] -> SubMap b v n m Source

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

rememberAs :: IsName a => a -> QDiagram b v n m -> SubMap b v n m -> SubMap b v n m Source

Add a name/diagram association to a submap.

lookupSub :: IsName nm => nm -> SubMap b v n m -> Maybe [Subdiagram b v n m] Source

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.

Attributes and styles

class (Typeable a, Semigroup a) => AttributeClass a Source

Every attribute must be an instance of AttributeClass, which simply guarantees Typeable and Semigroup constraints. The Semigroup instance for an attribute determines how it will combine with other attributes of the same type.

data Attribute v n :: * where Source

An existential wrapper type to hold attributes. Some attributes are simply inert/static; some are affected by transformations; and some are affected by transformations and can be modified generically.

Constructors

Attribute :: AttributeClass a => a -> Attribute v n 
MAttribute :: AttributeClass a => Measured n a -> Attribute v n 
TAttribute :: (AttributeClass a, Transformable a, V a ~ v, N a ~ n) => a -> Attribute v n 

Instances

Typeable * n => Show (Attribute v n) Source

Shows the kind of attribute and the type contained in the attribute.

Typeable * n => Semigroup (Attribute v n) Source

Attributes form a semigroup, where the semigroup operation simply returns the right-hand attribute when the types do not match, and otherwise uses the semigroup operation specific to the (matching) types.

(Additive v, Traversable v, Floating n) => Transformable (Attribute v n) Source

TAttributes are transformed directly, MAttributes have their local scale multiplied by the average scale of the transform. Plain Attributes are unaffected.

Each (Style v n) (Style v' n') (Attribute v n) (Attribute v' n') Source 
type N (Attribute v n) = n Source 
type V (Attribute v n) = v Source 

data Style v n Source

A Style is a heterogeneous collection of attributes, containing at most one attribute of any given type.

Instances

Typeable * n => Show (Style v n) Source

Show the attributes in the style.

Typeable * n => Monoid (Style v n) Source

The empty style contains no attributes.

Typeable * n => Semigroup (Style v n) Source

Combine a style by combining the attributes; if the two styles have attributes of the same type they are combined according to their semigroup structure.

Ixed (Style v n) Source 
At (Style v n) Source 
Wrapped (Style v n) Source 
(Additive v, Traversable v, Floating n) => Transformable (Style v n) Source 
Typeable * n => HasStyle (Style v n) Source 
Action (Style v n) m Source

Styles have no action on other monoids.

Rewrapped (Style v n) (Style v' n') Source 
Each (Style v n) (Style v' n') (Attribute v n) (Attribute v' n') Source 
type Index (Style v n) = TypeRep Source 
type IxValue (Style v n) = Attribute v n Source 
type Unwrapped (Style v n) = HashMap TypeRep (Attribute v n) Source 
type N (Style v n) = n Source 
type V (Style v n) = v Source 

class HasStyle a where Source

Type class for things which have a style.

Methods

applyStyle :: Style (V a) (N a) -> a -> a Source

Apply a style by combining it (on the left) with the existing style.

Instances

HasStyle a => HasStyle [a] Source 
(HasStyle a, Ord a) => HasStyle (Set a) Source 
HasStyle b => HasStyle (a -> b) Source 
(HasStyle a, HasStyle b, (~) (* -> *) (V a) (V b), (~) * (N a) (N b)) => HasStyle (a, b) Source 
HasStyle a => HasStyle (Map k a) Source 
HasStyle b => HasStyle (Measured n b) Source 
Typeable * n => HasStyle (Style v n) Source 
(Metric v, OrderedField n, Semigroup m) => HasStyle (QDiagram b v n m) Source 

getAttr :: forall a v n. AttributeClass a => Style v n -> Maybe a Source

Extract an attribute from a style of a particular type. If the style contains an attribute of the requested type, it will be returned wrapped in Just; otherwise, Nothing is returned.

Trying to extract a measured attibute will fail. It either has to be unmeasured with unmeasureAttrs or use the atMAttr lens.

atAttr :: AttributeClass a => Lens' (Style v n) (Maybe a) Source

Lens onto a plain attribute of a style.

atMAttr :: (AttributeClass a, Typeable n) => Lens' (Style v n) (Maybe (Measured n a)) Source

Lens onto a measured attribute of a style.

atTAttr :: (V a ~ v, N a ~ n, AttributeClass a, Transformable a) => Lens' (Style v n) (Maybe a) Source

Lens onto a transformable attribute of a style.

applyAttr :: (AttributeClass a, HasStyle d) => a -> d -> d Source

Apply an attribute to an instance of HasStyle (such as a diagram or a style). If the object already has an attribute of the same type, the new attribute is combined on the left with the existing attribute, according to their semigroup structure.

applyMAttr :: (AttributeClass a, N d ~ n, HasStyle d, Typeable n) => Measured n a -> d -> d Source

Apply a measured attribute to an instance of HasStyle (such as a diagram or a style). If the object already has an attribute of the same type, the new attribute is combined on the left with the existing attribute, according to their semigroup structure.

applyTAttr :: (AttributeClass a, Transformable a, V a ~ V d, N a ~ N d, HasStyle d) => a -> d -> d Source

Apply a transformable attribute to an instance of HasStyle (such as a diagram or a style). If the object already has an attribute of the same type, the new attribute is combined on the left with the existing attribute, according to their semigroup structure.

Envelopes

newtype Envelope v n Source

Every diagram comes equipped with an envelope. What is an envelope?

Consider first the idea of a bounding box. A bounding box expresses the distance to a bounding plane in every direction parallel to an axis. That is, a bounding box can be thought of as the intersection of a collection of half-planes, two perpendicular to each axis.

More generally, the intersection of half-planes in every direction would give a tight "bounding region", or convex hull. However, representing such a thing intensionally would be impossible; hence bounding boxes are often used as an approximation.

An envelope is an extensional representation of such a "bounding region". Instead of storing some sort of direct representation, we store a function which takes a direction as input and gives a distance to a bounding half-plane as output. The important point is that envelopes can be composed, and transformed by any affine transformation.

Formally, given a vector v, the envelope computes a scalar s such that

  • for every point u inside the diagram, if the projection of (u - origin) onto v is s' *^ v, then s' <= s.
  • s is the smallest such scalar.

There is also a special "empty envelope".

The idea for envelopes came from Sebastian Setzer; see http://byorgey.wordpress.com/2009/10/28/collecting-attributes/#comment-2030. See also Brent Yorgey, Monoids: Theme and Variations, published in the 2012 Haskell Symposium: http://www.cis.upenn.edu/~byorgey/pub/monoid-pearl.pdf; video: http://www.youtube.com/watch?v=X-8NCkD2vOw.

Constructors

Envelope (Option (v n -> Max n)) 

Instances

Show (Envelope v n) Source 
Ord n => Monoid (Envelope v n) Source 
Ord n => Semigroup (Envelope v n) Source 
Wrapped (Envelope v n) Source 
(Metric v, Fractional n) => HasOrigin (Envelope v n) Source

The local origin of an envelope is the point with respect to which bounding queries are made, i.e. the point from which the input vectors are taken to originate.

(Metric v, Floating n) => Transformable (Envelope v n) Source 
(Metric v, OrderedField n) => Enveloped (Envelope v n) Source 
(Metric v, OrderedField n) => Juxtaposable (Envelope v n) Source 
Rewrapped (Envelope v n) (Envelope v' n') Source 
type Unwrapped (Envelope v n) = Option (v n -> Max n) Source 
type N (Envelope v n) = n Source 
type V (Envelope v n) = v Source 

appEnvelope :: Envelope v n -> Maybe (v n -> n) Source

onEnvelope :: ((v n -> n) -> v n -> n) -> Envelope v n -> Envelope v n Source

mkEnvelope :: (v n -> n) -> Envelope v n Source

class (Metric (V a), OrderedField (N a)) => Enveloped a where Source

Enveloped abstracts over things which have an envelope.

Methods

getEnvelope :: a -> Envelope (V a) (N a) Source

Compute the envelope of an object. For types with an intrinsic notion of "local origin", the envelope will be based there. Other types (e.g. Trail) may have some other default reference point at which the envelope will be based; their instances should document what it is.

Instances

Enveloped b => Enveloped [b] Source 
Enveloped b => Enveloped (Set b) Source 
Enveloped t => Enveloped (TransInv t) Source 
(Enveloped a, Enveloped b, (~) (* -> *) (V a) (V b), (~) * (N a) (N b)) => Enveloped (a, b) Source 
Enveloped b => Enveloped (Map k b) Source 
(OrderedField n, Metric v) => Enveloped (Point v n) Source 
(Metric v, OrderedField n) => Enveloped (Envelope v n) Source 
(OrderedField n, Metric v, Monoid' m) => Enveloped (Subdiagram b v n m) Source 
(Metric v, OrderedField n, Monoid' m) => Enveloped (QDiagram b v n m) Source 

envelopeVMay :: Enveloped a => Vn a -> a -> Maybe (Vn a) Source

Compute the vector from the local origin to a separating hyperplane in the given direction, or Nothing for the empty envelope.

envelopeV :: Enveloped a => Vn a -> a -> Vn a Source

Compute the vector from the local origin to a separating hyperplane in the given direction. Returns the zero vector for the empty envelope.

envelopePMay :: (V a ~ v, N a ~ n, Enveloped a) => v n -> a -> Maybe (Point v n) Source

Compute the point on a separating hyperplane in the given direction, or Nothing for the empty envelope.

envelopeP :: (V a ~ v, N a ~ n, Enveloped a) => v n -> a -> Point v n Source

Compute the point on a separating hyperplane in the given direction. Returns the origin for the empty envelope.

diameter :: (V a ~ v, N a ~ n, Enveloped a) => v n -> a -> n Source

Compute the diameter of a enveloped object along a particular vector. Returns zero for the empty envelope.

radius :: (V a ~ v, N a ~ n, Enveloped a) => v n -> a -> n Source

Compute the "radius" (1/2 the diameter) of an enveloped object along a particular vector.

size :: (V a ~ v, N a ~ n, Enveloped a, HasBasis v) => a -> v n Source

The smallest positive vector that bounds the envelope of an object.

Traces

newtype Trace v n Source

Every diagram comes equipped with a trace. Intuitively, the trace for a diagram is like a raytracer: given a line (represented as a base point and a direction vector), the trace computes a sorted list of signed distances from the base point to all intersections of the line with the boundary of the diagram.

Note that the outputs are not absolute distances, but multipliers relative to the input vector. That is, if the base point is p and direction vector is v, and one of the output scalars is s, then there is an intersection at the point p .+^ (s *^ v).

Constructors

Trace 

Fields

appTrace :: Point v n -> v n -> SortedList n
 

Instances

Show (Trace v n) Source 
Ord n => Monoid (Trace v n) Source 
Ord n => Semigroup (Trace v n) Source 
Wrapped (Trace v n) Source 
(Additive v, Num n) => HasOrigin (Trace v n) Source 
(Additive v, Num n) => Transformable (Trace v n) Source 
(Additive v, Ord n) => Traced (Trace v n) Source 
Rewrapped (Trace v n) (Trace v' n') Source 
type Unwrapped (Trace v n) = Point v n -> v n -> SortedList n Source 
type N (Trace v n) = n Source 
type V (Trace v n) = v Source 

data SortedList a Source

A newtype wrapper around a list which maintains the invariant that the list is sorted. The constructor is not exported; use the smart constructor mkSortedList (which sorts the given list) instead.

Instances

Ord a => Monoid (SortedList a) Source

SortedList forms a monoid with merge and the empty list.

Ord a => Semigroup (SortedList a) Source

SortedList forms a semigroup with merge as composition.

mkSortedList :: Ord a => [a] -> SortedList a Source

A smart constructor for the SortedList type, which sorts the input to ensure the SortedList invariant.

getSortedList :: SortedList a -> [a] Source

Project the (guaranteed sorted) list out of a SortedList wrapper.

mkTrace :: (Point v n -> v n -> SortedList n) -> Trace v n Source

class (Additive (V a), Ord (N a)) => Traced a where Source

Traced abstracts over things which have a trace.

Methods

getTrace :: a -> Trace (V a) (N a) Source

Compute the trace of an object.

Instances

Traced b => Traced [b] Source 
Traced b => Traced (Set b) Source 
Traced t => Traced (TransInv t) Source 
(Traced a, Traced b, SameSpace a b) => Traced (a, b) Source 
Traced b => Traced (Map k b) Source 
(Additive v, Ord n) => Traced (Point v n) Source

The trace of a single point is the empty trace, i.e. the one which returns no intersection points for every query. Arguably it should return a single finite distance for vectors aimed directly at the given point, but due to floating-point inaccuracy this is problematic. Note that the envelope for a single point is not the empty envelope (see Diagrams.Core.Envelope).

(Additive v, Ord n) => Traced (Trace v n) Source 
(OrderedField n, Metric v, Semigroup m) => Traced (Subdiagram b v n m) Source 
(Metric v, OrderedField n, Semigroup m) => Traced (QDiagram b v n m) Source 

traceV :: (n ~ N a, Num n, Traced a) => Point (V a) n -> V a n -> a -> Maybe (V a n) Source

Compute the vector from the given point p to the "smallest" boundary intersection along the given vector v. The "smallest" boundary intersection is defined as the one given by p .+^ (s *^ v) for the smallest (most negative) value of s. Return Nothing if there is no intersection. See also traceP.

See also rayTraceV which uses the smallest positive intersection, which is often more intuitive behavior.

traceP :: (n ~ N a, Traced a, Num n) => Point (V a) n -> V a n -> a -> Maybe (Point (V a) n) Source

Compute the "smallest" boundary point along the line determined by the given point p and vector v. The "smallest" boundary point is defined as the one given by p .+^ (s *^ v) for the smallest (most negative) value of s. Return Nothing if there is no such boundary point. See also traceV.

See also rayTraceP which uses the smallest positive intersection, which is often more intuitive behavior.

maxTraceV :: (n ~ N a, Num n, Traced a) => Point (V a) n -> V a n -> a -> Maybe (V a n) Source

Like traceV, but computes a vector to the "largest" boundary point instead of the smallest. (Note, however, the "largest" boundary point may still be in the opposite direction from the given vector, if all the boundary points are, as in the third example shown below.)

maxTraceP :: (n ~ N a, Num n, Traced a) => Point (V a) n -> V a n -> a -> Maybe (Point (V a) n) Source

Like traceP, but computes the "largest" boundary point instead of the smallest. (Note, however, the "largest" boundary point may still be in the opposite direction from the given vector, if all the boundary points are.)

rayTraceV :: (n ~ N a, Traced a, Num n) => Point (V a) n -> V a n -> a -> Maybe (V a n) Source

Compute the vector from the given point to the closest boundary point of the given object in the given direction, or Nothing if there is no such boundary point (as in the third example below). Note that unlike traceV, only positive boundary points are considered, i.e. boundary points corresponding to a positive scalar multiple of the direction vector. This is intuitively the "usual" behavior of a raytracer, which only considers intersections "in front of" the camera. Compare the second example diagram below with the second example shown for traceV.

rayTraceP :: (n ~ N a, Traced a, Num n) => Point (V a) n -> V a n -> a -> Maybe (Point (V a) n) Source

Compute the boundary point on an object which is closest to the given base point in the given direction, or Nothing if there is no such boundary point. Note that unlike traceP, only positive boundary points are considered, i.e. boundary points corresponding to a positive scalar multiple of the direction vector. This is intuitively the "usual" behavior of a raytracer, which only considers intersection points "in front of" the camera.

maxRayTraceV :: (n ~ N a, Traced a, Num n) => Point (V a) n -> V a n -> a -> Maybe (V a n) Source

Like rayTraceV, but computes a vector to the "largest" boundary point instead of the smallest. Considers only positive boundary points.

maxRayTraceP :: (n ~ N a, Traced a, Num n) => Point (V a) n -> V a n -> a -> Maybe (Point (V a) n) Source

Like rayTraceP, but computes the "largest" boundary point instead of the smallest. Considers only positive boundary points.

Things with local origins

class HasOrigin t where Source

Class of types which have an intrinsic notion of a "local origin", i.e. things which are not invariant under translation, and which allow the origin to be moved.

One might wonder why not just use Transformable instead of having a separate class for HasOrigin; indeed, for types which are instances of both we should have the identity

  moveOriginTo (origin .^+ v) === translate (negated v)
  

The reason is that some things (e.g. vectors, Trails) are transformable but are translationally invariant, i.e. have no origin.

Methods

moveOriginTo :: Point (V t) (N t) -> t -> t Source

Move the local origin to another point.

Note that this function is in some sense dual to translate (for types which are also Transformable); moving the origin itself while leaving the object "fixed" is dual to fixing the origin and translating the diagram.

Instances

HasOrigin t => HasOrigin [t] Source 
(HasOrigin t, Ord t) => HasOrigin (Set t) Source 
HasOrigin (TransInv t) Source 
(HasOrigin t, HasOrigin s, SameSpace s t) => HasOrigin (s, t) Source 
HasOrigin t => HasOrigin (Map k t) Source 
(Additive v, Num n) => HasOrigin (Point v n) Source 
HasOrigin t => HasOrigin (Measured n t) Source 
(Additive v, Num n) => HasOrigin (Transformation v n) Source 
(Additive v, Num n) => HasOrigin (Trace v n) Source 
(Metric v, Fractional n) => HasOrigin (Envelope v n) Source

The local origin of an envelope is the point with respect to which bounding queries are made, i.e. the point from which the input vectors are taken to originate.

(Additive v, Num n) => HasOrigin (Query v n m) Source 
(OrderedField n, Metric v) => HasOrigin (SubMap b v n m) Source 
(Metric v, OrderedField n) => HasOrigin (Subdiagram b v n m) Source 
(Metric v, OrderedField n, Semigroup m) => HasOrigin (QDiagram b v n m) Source

Every diagram has an intrinsic "local origin" which is the basis for all combining operations.

moveOriginBy :: (V t ~ v, N t ~ n, Num n, HasOrigin t) => v n -> t -> t Source

Move the local origin by a relative vector.

Juxtaposable things

class Juxtaposable a where Source

Class of things which can be placed "next to" other things, for some appropriate notion of "next to".

Methods

juxtapose :: Vn a -> a -> a -> a Source

juxtapose v a1 a2 positions a2 next to a1 in the direction of v. In particular, place a2 so that v points from the local origin of a1 towards the old local origin of a2; a1's local origin becomes a2's new local origin. The result is just a translated version of a2. (In particular, this operation does not combine a1 and a2 in any way.)

Instances

juxtaposeDefault :: (Enveloped a, HasOrigin a) => Vn a -> a -> a -> a Source

Default implementation of juxtapose for things which are instances of Enveloped and HasOrigin. If either envelope is empty, the second object is returned unchanged.

Queries

newtype Query v n m Source

A query is a function that maps points in a vector space to values in some monoid. Queries naturally form a monoid, with two queries being combined pointwise.

The idea for annotating diagrams with monoidal queries came from the graphics-drawingcombinators package, http://hackage.haskell.org/package/graphics-drawingcombinators.

Constructors

Query 

Fields

runQuery :: Point v n -> m
 

Instances

Functor (Query v n) Source 
Applicative (Query v n) Source 
Monoid m => Monoid (Query v n m) Source 
Semigroup m => Semigroup (Query v n m) Source 
Wrapped (Query v n m) Source 
(Additive v, Num n) => HasOrigin (Query v n m) Source 
(Additive v, Num n) => Transformable (Query v n m) Source 
Rewrapped (Query v a m) (Query v' a' m') Source 
type Unwrapped (Query v n m) = Point v n -> m Source 
type N (Query v n m) = n Source 
type V (Query v n m) = v Source 

Primitives

data Prim b v n where Source

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.

Constructors

Prim :: (Transformable p, Typeable p, Renderable p b) => p -> Prim b (V p) (N p) 

Instances

Transformable (Prim b v n) Source

The Transformable instance for Prim just pushes calls to transform down through the Prim constructor.

Renderable (Prim b v n) b Source

The Renderable instance for Prim just pushes calls to render down through the Prim constructor.

type N (Prim b v n) = n Source 
type V (Prim b v n) = v Source 

Diagrams

data QDiagram b v n m Source

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.

Instances

Functor (QDiagram b v n) Source 
(Metric v, OrderedField n, Semigroup m) => Monoid (QDiagram b v n m) Source

Diagrams form a monoid since each of their components do: the empty diagram has no primitives, an empty envelope, an empty trace, no named subdiagrams, and a constantly empty query function.

Diagrams compose by aligning their respective local origins. The new diagram has all the primitives and all the names from the two diagrams combined, and query functions are combined pointwise. The first diagram goes on top of the second. "On top of" probably only makes sense in vector spaces of dimension lower than 3, but in theory it could make sense for, say, 3-dimensional diagrams when viewed by 4-dimensional beings.

(Metric v, OrderedField n, Semigroup m) => Semigroup (QDiagram b v n m) Source 
Wrapped (QDiagram b v n m) Source 
(Metric v, OrderedField n, Semigroup m) => HasOrigin (QDiagram b v n m) Source

Every diagram has an intrinsic "local origin" which is the basis for all combining operations.

(OrderedField n, Metric v, Semigroup m) => Transformable (QDiagram b v n m) Source

Diagrams can be transformed by transforming each of their components appropriately.

(Metric v, OrderedField n, Semigroup m) => Qualifiable (QDiagram b v n m) Source

Diagrams can be qualified so that all their named points can now be referred to using the qualification prefix.

(Metric v, OrderedField n, Semigroup m) => HasStyle (QDiagram b v n m) Source 
(Metric v, OrderedField n, Semigroup m) => Traced (QDiagram b v n m) Source 
(Metric v, OrderedField n, Monoid' m) => Enveloped (QDiagram b v n m) Source 
(Metric v, OrderedField n, Monoid' m) => Juxtaposable (QDiagram b v n m) Source 
Rewrapped (QDiagram b v n m) (QDiagram b' v' n' m') Source 
type Unwrapped (QDiagram b v n m) = DUALTree (DownAnnots v n) (UpAnnots b v n m) Annotation (QDiaLeaf b v n m) Source 
type N (QDiagram b v n m) = n Source 
type V (QDiagram b v n m) = v Source 

type Diagram b = QDiagram b (V b) (N b) Any Source

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.

mkQD :: Prim b v n -> Envelope v n -> Trace v n -> SubMap b v n m -> Query v n m -> QDiagram b v n m Source

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

pointDiagram :: (Metric v, Fractional n) => Point v n -> QDiagram b v n m Source

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

envelope :: (OrderedField n, Metric v, Monoid' m) => Lens' (QDiagram b v n m) (Envelope v n) Source

Lens onto the Envelope of a QDiagram.

trace :: (Metric v, OrderedField n, Semigroup m) => Lens' (QDiagram b v n m) (Trace v n) Source

Lens onto the Trace of a QDiagram.

subMap :: (Metric v, Semigroup m, OrderedField n) => Lens' (QDiagram b v n m) (SubMap b v n m) Source

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

names :: (Metric v, Semigroup m, OrderedField n) => QDiagram b v n m -> [(Name, [Point v n])] Source

Get a list of names of subdiagrams and their locations.

query :: Monoid m => QDiagram b v n m -> Query v n m Source

Get the query function associated with a diagram.

sample :: Monoid m => QDiagram b v n m -> Point v n -> m Source

Sample a diagram's query function at a given point.

value :: Monoid m => m -> QDiagram b v n Any -> QDiagram b v n m Source

Set the query value for True points in a diagram (i.e. points "inside" the diagram); False points will be set to mempty.

resetValue :: (Eq m, Monoid m) => QDiagram b v n m -> QDiagram b v n Any Source

Reset the query values of a diagram to True/False: any values equal to mempty are set to False; any other values are set to True.

clearValue :: QDiagram b v n m -> QDiagram b v n Any Source

Set all the query values of a diagram to False.

nameSub :: (IsName nm, Metric v, OrderedField n, Semigroup m) => (QDiagram b v n m -> Subdiagram b v n m) -> nm -> QDiagram b v n m -> QDiagram b v n m Source

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

withName :: (IsName nm, Metric v, Semigroup m, OrderedField n) => nm -> (Subdiagram b v n m -> QDiagram b v n m -> QDiagram b v n m) -> QDiagram b v n m -> QDiagram b v n m Source

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.

withNameAll :: (IsName nm, Metric v, Semigroup m, OrderedField n) => nm -> ([Subdiagram b v n m] -> QDiagram b v n m -> QDiagram b v n m) -> QDiagram b v n m -> QDiagram b v n m Source

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.

withNames :: (IsName nm, Metric v, Semigroup m, OrderedField n) => [nm] -> ([Subdiagram b v n m] -> QDiagram b v n m -> QDiagram b v n m) -> QDiagram b v n m -> QDiagram b v n m Source

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 :: forall b v n m. (Metric v, OrderedField n, Semigroup m) => QDiagram b v n m -> QDiagram b v n m Source

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

href :: (Metric v, OrderedField n, Semigroup m) => String -> QDiagram b v n m -> QDiagram b v n m Source

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

opacityGroup :: (Metric v, OrderedField n, Semigroup m) => Double -> QDiagram b v n m -> QDiagram b v n m Source

Change the transparency of a Diagram as a group.

groupOpacity :: (Metric v, OrderedField n, Semigroup m) => Double -> QDiagram b v n m -> QDiagram b v n m Source

Change the transparency of a Diagram as a group.

setEnvelope :: forall b v n m. (OrderedField n, Metric v, Monoid' m) => Envelope v n -> QDiagram b v n m -> QDiagram b v n m Source

Replace the envelope of a diagram.

setTrace :: forall b v n m. (OrderedField n, Metric v, Semigroup m) => Trace v n -> QDiagram b v n m -> QDiagram b v n m Source

Replace the trace of a diagram.

atop :: (OrderedField n, Metric v, Semigroup m) => QDiagram b v n m -> QDiagram b v n m -> QDiagram b v n m infixl 6 Source

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

Subdiagrams

data Subdiagram b v n m Source

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

Constructors

Subdiagram (QDiagram b v n m) (DownAnnots v n) 

Instances

Functor (Subdiagram b v n) Source 
(Metric v, OrderedField n) => HasOrigin (Subdiagram b v n m) Source 
(Metric v, Floating n) => Transformable (Subdiagram b v n m) Source 
(OrderedField n, Metric v, Semigroup m) => Traced (Subdiagram b v n m) Source 
(OrderedField n, Metric v, Monoid' m) => Enveloped (Subdiagram b v n m) Source 
type N (Subdiagram b v n m) = n Source 
type V (Subdiagram b v n m) = v Source 

mkSubdiagram :: QDiagram b v n m -> Subdiagram b v n m Source

Turn a diagram into a subdiagram with no accumulated context.

getSub :: (Metric v, OrderedField n, Semigroup m) => Subdiagram b v n m -> QDiagram b v n m Source

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.

rawSub :: Subdiagram b v n m -> QDiagram b v n m Source

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

location :: (Additive v, Num n) => Subdiagram b v n m -> Point v n Source

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

subPoint :: (Metric v, OrderedField n, Semigroup m) => Point v n -> Subdiagram b v n m Source

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.

Measurements

data Measured n a Source

'Measured n a' is an object that depends on local, normalized and global scales. The normalized and global scales are calculated when rendering a diagram.

For attributes, the local scale gets multiplied by the average scale of the transform.

type Measure n = Measured n n Source

A measure is a Measured number.

fromMeasured :: Num n => n -> n -> Measured n a -> a Source

fromMeasured globalScale normalizedScale measure -> a

output :: Num n => n -> Measure n Source

Output units don't change.

local :: Num n => n -> Measure n Source

Local units are scaled by the average scale of a transform.

global :: Num n => n -> Measure n Source

Global units are ?

normalized :: Num n => n -> Measure n Source

Normalized units get scaled so that one normalized unit is the size of the final diagram.

scaleLocal :: Num n => n -> Measured n a -> Measured n a Source

Scale the local units of a Measured thing.

atLeast :: Ord n => Measure n -> Measure n -> Measure n Source

Calculate the smaller of two measures.

atMost :: Ord n => Measure n -> Measure n -> Measure n Source

Calculate the larger of two measures.

Backends

class Backend b v n where Source

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.

Minimal complete definition

renderRTree

Associated Types

data Render b v n :: * Source

An intermediate representation used for rendering primitives. (Typically, this will be some sort of monad, but it need not be.) The Renderable class guarantees that a backend will be able to convert primitives into this type; how these rendered primitives are combined into an ultimate Result is completely up to the backend.

type Result b v n :: * Source

The result of running/interpreting a rendering operation.

data Options b v n :: * Source

Backend-specific rendering options.

Methods

adjustDia :: (Additive v, Monoid' m, Num n) => b -> Options b v n -> QDiagram b v n m -> (Options b v n, Transformation v n, QDiagram b v n m) Source

adjustDia allows the backend to make adjustments to the final diagram (e.g. to adjust the size based on the options) before rendering it. It returns a modified options record, the transformation applied to the diagram (which can be used to convert attributes whose value is Measure, or transform e.g. screen coordinates back into local diagram coordinates), and the adjusted diagram itself.

See the diagrams-lib package (particularly the Diagrams.TwoD.Adjust module) for some useful implementations.

renderRTree :: b -> Options b v n -> RTree b v n Annotation -> Result b v n Source

Given some options, take a representation of a diagram as a tree and render it. The RTree has already been simplified and has all measurements converted to Output units.

Instances

class Transformable t => Renderable t b where Source

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

Methods

render :: b -> t -> Render b (V t) (N t) Source

Given a token representing the backend and a transformable object, render it in the appropriate rendering context.

Instances

Renderable (Prim b v n) b Source

The Renderable instance for Prim just pushes calls to render down through the Prim constructor.

renderDia :: (Backend b v n, HasLinearMap v, Metric v, Typeable v, Typeable n, OrderedField n, Monoid' m) => b -> Options b v n -> QDiagram b v n m -> Result b v n Source

Render a diagram.

renderDiaT :: (Backend b v n, HasLinearMap v, Metric v, Typeable v, Typeable n, OrderedField n, Monoid' m) => b -> Options b v n -> QDiagram b v n m -> (Transformation v n, Result b v n) Source

Render a diagram, returning also the transformation which was used to convert the diagram from its ("global") coordinate system into the output coordinate system. The inverse of this transformation can be used, for example, to convert output/screen coordinates back into diagram coordinates. See also adjustDia.

The null backend

data NullBackend Source

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.

type D v n = QDiagram NullBackend v n Any Source

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
  

Convenience classes

class (HasBasis v, Traversable v) => HasLinearMap v Source

HasLinearMap is a poor man's class constraint synonym, just to help shorten some of the ridiculously long constraint sets.

Instances

class (Additive v, Representable v, Rep v ~ E v) => HasBasis v Source

An Additive vector space whose representation is made up of basis elements.

Instances

(Additive v, Representable v, (~) * (Rep v) (E v)) => HasBasis v Source 

class (Floating s, Ord s) => OrderedField s Source

When dealing with envelopes we often want scalars to be an ordered field (i.e. support all four arithmetic operations and be totally ordered) so we introduce this class as a convenient shorthand.

Instances

class (Typeable n, RealFloat n) => TypeableFloat n Source

Class of numbers that are RealFloat and Typeable. This class is used to shorten type constraints.

Instances

class (Semigroup m, Monoid m) => Monoid' m

The Monoid' class is a synonym for things which are instances of both Semigroup and Monoid. Ideally, the Monoid class itself will eventually include a Semigroup superclass and we can get rid of this.

Instances

(Semigroup m, Monoid m) => Monoid' m