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

Copyright | (c) 2011 diagrams-lib team (see LICENSE)
License | BSD-style (see LICENSE)
Maintainer | diagrams-discuss@googlegroups.com
Safe Haskell | None
Language | Haskell2010

Diagrams.Path

Contents

- Paths
- Constructing paths
- Eliminating paths
- Modifying paths
- Miscellaneous

Description

This module defines paths, which are collections of concretely located `Trail`s. Many drawing systems (cairo, svg, ...) have a similar notion of "path". Note that paths with multiple trails are necessary for being able to draw e.g. filled objects with holes in them.

Synopsis

- newtype Path v n = Path [Located (Trail v n)]
- pathTrails :: Path v n -> [Located (Trail v n)]
- class ToPath t where
- pathFromTrail :: (Metric v, OrderedField n) => Trail v n -> Path v n
- pathFromTrailAt :: (Metric v, OrderedField n) => Trail v n -> Point v n -> Path v n
- pathFromLocTrail :: (Metric v, OrderedField n) => Located (Trail v n) -> Path v n
- pathPoints :: (Metric v, OrderedField n) => Path v n -> [[Point v n]]
- pathVertices' :: (Metric v, OrderedField n) => n -> Path v n -> [[Point v n]]
- pathVertices :: (Metric v, OrderedField n) => Path v n -> [[Point v n]]
- pathOffsets :: (Metric v, OrderedField n) => Path v n -> [v n]
- pathCentroid :: (Metric v, OrderedField n) => Path v n -> Point v n
- pathLocSegments :: (Metric v, OrderedField n) => Path v n -> [[Located (Segment Closed v n)]]
- fixPath :: (Metric v, OrderedField n) => Path v n -> [[FixedSegment v n]]
- scalePath :: (HasLinearMap v, Metric v, OrderedField n) => n -> Path v n -> Path v n
- reversePath :: (Metric v, OrderedField n) => Path v n -> Path v n
- explodePath :: (V t ~ v, N t ~ n, TrailLike t) => Path v n -> [[t]]
- partitionPath :: (Located (Trail v n) -> Bool) -> Path v n -> (Path v n, Path v n)

# Paths

newtype Path v n Source #

A path is a (possibly empty) list of `Located` `Trail`s. Hence, unlike trails, paths are not translationally invariant, and they form a monoid under superposition (placing one path on top of another) rather than concatenation.

Constructors

Path [Located (Trail v n)] |

Instances

Eq (v n) => Eq (Path v n) Source # |
Methods (==) :: Path v n -> Path v n -> Bool # (/=) :: Path v n -> Path v n -> Bool #
Ord (v n) => Ord (Path v n) Source # |
Methods compare :: Path v n -> Path v n -> Ordering # (<) :: Path v n -> Path v n -> Bool # (<=) :: Path v n -> Path v n -> Bool # (>) :: Path v n -> Path v n -> Bool # (>=) :: Path v n -> Path v n -> Bool # max :: Path v n -> Path v n -> Path v n # min :: Path v n -> Path v n -> Path v n #
Show (v n) => Show (Path v n) Source # |
Methods showsPrec :: Int -> Path v n -> ShowS # show :: Path v n -> String # showList :: [Path v n] -> ShowS #
Generic (Path v n) Source # |
Associated Types type Rep (Path v n) :: * -> * # Methods from :: Path v n -> Rep (Path v n) x # to :: Rep (Path v n) x -> Path v n #
Semigroup (Path v n) Source # |
Methods (<>) :: Path v n -> Path v n -> Path v n # sconcat :: NonEmpty (Path v n) -> Path v n # stimes :: Integral b => b -> Path v n -> Path v n #
Monoid (Path v n) Source # |
Methods mempty :: Path v n # mappend :: Path v n -> Path v n -> Path v n # mconcat :: [Path v n] -> Path v n #
(OrderedField n, Metric v, Serialize (v n), Serialize (V (v n) (N (v n)))) => Serialize (Path v n) Source # |
Methods put :: Putter (Path v n) # get :: Get (Path v n) #
(Metric v, OrderedField n) => Juxtaposable (Path v n) Source # |
Methods juxtapose :: Vn (Path v n) -> Path v n -> Path v n -> Path v n #
(Metric v, OrderedField n) => Enveloped (Path v n) Source # |
Methods getEnvelope :: Path v n -> Envelope (V (Path v n)) (N (Path v n)) #
(HasLinearMap v, Metric v, OrderedField n) => Transformable (Path v n) Source # |
Methods transform :: Transformation (V (Path v n)) (N (Path v n)) -> Path v n -> Path v n #
(Additive v, Num n) => HasOrigin (Path v n) Source # |
Methods moveOriginTo :: Point (V (Path v n)) (N (Path v n)) -> Path v n -> Path v n #
AsEmpty (Path v n) Source # |
Methods _Empty :: Prism' (Path v n) () #
Wrapped (Path v n) Source # |
Associated Types type Unwrapped (Path v n) :: * # Methods _Wrapped' :: Iso' (Path v n) (Unwrapped (Path v n)) #
(Metric v, OrderedField n) => Reversing (Path v n) Source # | Same as `reversePath`.
Methods reversing :: Path v n -> Path v n #
(Metric v, OrderedField n) => Alignable (Path v n) Source # |
Methods alignBy' :: (InSpace v n (Path v n), Fractional n, HasOrigin (Path v n)) => (v n -> Path v n -> Point v n) -> v n -> n -> Path v n -> Path v n Source # defaultBoundary :: (((* -> *) ~ V (Path v n)) v, (* ~ N (Path v n)) n) => v n -> Path v n -> Point v n Source # alignBy :: (InSpace v n (Path v n), Fractional n, HasOrigin (Path v n)) => v n -> n -> Path v n -> Path v n Source #
(Metric v, OrderedField n) => TrailLike (Path v n) Source # | Paths are trail-like; a trail can be used to construct a singleton path.
Methods trailLike :: Located (Trail (V (Path v n)) (N (Path v n))) -> Path v n Source #
ToPath (Path v n) Source # |
Methods toPath :: Path v n -> Path (V (Path v n)) (N (Path v n)) Source #
(HasLinearMap v, Metric v, OrderedField n) => Renderable (Path v n) NullBackend Source # |
Methods render :: NullBackend -> Path v n -> Render NullBackend (V (Path v n)) (N (Path v n)) #
(Metric v, Metric u, OrderedField n, (~) * r (Path u n)) => Deformable (Path v n) r Source # |
Methods deform' :: N (Path v n) -> Deformation (V (Path v n)) (V r) (N (Path v n)) -> Path v n -> r Source # deform :: Deformation (V (Path v n)) (V r) (N (Path v n)) -> Path v n -> r Source #
(Metric v, Metric u, OrderedField n, (~) * r (Path u n)) => AffineMappable (Path v n) r Source # |
Methods amap :: AffineMap (V (Path v n)) (V r) (N r) -> Path v n -> r Source #
(Metric v, Metric u, OrderedField n, OrderedField m, (~) * r (Path u m)) => LinearMappable (Path v n) r Source # |
Methods vmap :: (Vn (Path v n) -> Vn r) -> Path v n -> r Source #
Rewrapped (Path v n) (Path v' n') Source # |
Cons (Path v n) (Path v' n') (Located (Trail v n)) (Located (Trail v' n')) Source # |
Methods _Cons :: Prism (Path v n) (Path v' n') (Located (Trail v n), Path v n) (Located (Trail v' n'), Path v' n') #
Snoc (Path v n) (Path v' n') (Located (Trail v n)) (Located (Trail v' n')) Source # |
Methods _Snoc :: Prism (Path v n) (Path v' n') (Path v n, Located (Trail v n)) (Path v' n', Located (Trail v' n')) #
Each (Path v n) (Path v' n') (Located (Trail v n)) (Located (Trail v' n')) Source # |
Methods each :: Traversal (Path v n) (Path v' n') (Located (Trail v n)) (Located (Trail v' n')) #
type Rep (Path v n) Source # |
type Rep (Path v n) = D1 (MetaData "Path" "Diagrams.Path" "diagrams-lib-1.4.2-IGFptljWWr6De8Z1yVkBCn" True) (C1 (MetaCons "Path" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Located (Trail v n)])))
type V (Path v n) Source # |
type V (Path v n) = v
type N (Path v n) Source # |
type N (Path v n) = n
type Unwrapped (Path v n) Source # |
type Unwrapped (Path v n) = [Located (Trail v n)]

pathTrails :: Path v n -> [Located (Trail v n)] Source #

Extract the located trails making up a `Path`.

# Constructing paths

Since paths are `TrailLike`, any function producing a `TrailLike` can be used to construct a (singleton) path. The functions in this section are provided for convenience.

class ToPath t where Source #

Type class for things that can be converted to a `Path`.

Note that this class is very different from `TrailLike`. `TrailLike` is usually the result of a library function to give you a convenient, polymorphic result (`Path`, `Diagram` etc.).

Minimal complete definition

toPath

Methods

toPath :: (Metric (V t), OrderedField (N t)) => t -> Path (V t) (N t) Source #

`toPath` takes something that can be converted to `Path` and returns the `Path`.

Instances

ToPath a => ToPath [a] Source # |
Methods toPath :: [a] -> Path (V [a]) (N [a]) Source #
ToPath (Located [Segment Closed v n]) Source # |
Methods toPath :: Located [Segment Closed v n] -> Path (V (Located [Segment Closed v n])) (N (Located [Segment Closed v n])) Source #
ToPath (Located (Segment Closed v n)) Source # |
Methods toPath :: Located (Segment Closed v n) -> Path (V (Located (Segment Closed v n))) (N (Located (Segment Closed v n))) Source #
ToPath (Located (Trail v n)) Source # |
Methods toPath :: Located (Trail v n) -> Path (V (Located (Trail v n))) (N (Located (Trail v n))) Source #
ToPath (Located (Trail' l v n)) Source # |
Methods toPath :: Located (Trail' l v n) -> Path (V (Located (Trail' l v n))) (N (Located (Trail' l v n))) Source #
ToPath (FixedSegment v n) Source # |
Methods toPath :: FixedSegment v n -> Path (V (FixedSegment v n)) (N (FixedSegment v n)) Source #
ToPath (Trail v n) Source # |
Methods toPath :: Trail v n -> Path (V (Trail v n)) (N (Trail v n)) Source #
ToPath (Path v n) Source # |
Methods toPath :: Path v n -> Path (V (Path v n)) (N (Path v n)) Source #
ToPath (Trail' l v n) Source # |
Methods toPath :: Trail' l v n -> Path (V (Trail' l v n)) (N (Trail' l v n)) Source #

pathFromTrail :: (Metric v, OrderedField n) => Trail v n -> Path v n Source #

Convert a trail to a path beginning at the origin.

pathFromTrailAt :: (Metric v, OrderedField n) => Trail v n -> Point v n -> Path v n Source #

Convert a trail to a path with a particular starting point.

pathFromLocTrail :: (Metric v, OrderedField n) => Located (Trail v n) -> Path v n Source #

Convert a located trail to a singleton path. This is equivalent to `trailLike`, but provided with a more specific name and type for convenience.

# Eliminating paths

pathPoints :: (Metric v, OrderedField n) => Path v n -> [[Point v n]] Source #

Extract the points of a path, resulting in a separate list of points for each component trail. Here a point is any place where two segments join; see also `pathVertices` and `trailPoints`.

This function allows you "observe" the fact that trails are implemented as lists of segments, which may be problematic if we want to think of trails as parametric vector functions. This also means that the behavior of this function may not be stable under future changes to the implementation of trails and paths. For an unproblematic version which only yields vertices at which there is a sharp corner, excluding points differentiable points, see `pathVertices`.

This function is not re-exported from Diagrams.Prelude; to use it, import Diagrams.Path.

pathVertices' :: (Metric v, OrderedField n) => n -> Path v n -> [[Point v n]] Source #

Extract the vertices of a path, resulting in a separate list of vertices for each component trail. Here a vertex is defined as a non-differentiable point on the trail, i.e. a sharp corner. (Vertices are thus a subset of the places where segments join; if you want all joins between segments, see `pathPoints`.) The tolerance determines how close the tangents of two segments must be at their endpoints to consider the transition point to be differentiable. See `trailVertices` for more information.

pathVertices :: (Metric v, OrderedField n) => Path v n -> [[Point v n]] Source #

Like `pathVertices'`, with a default tolerance.

pathOffsets :: (Metric v, OrderedField n) => Path v n -> [v n] Source #

Compute the total offset of each trail comprising a path (see `trailOffset`).

pathCentroid :: (Metric v, OrderedField n) => Path v n -> Point v n Source #

Compute the centroid of a path (i.e. the average location of its vertices; see `pathVertices`).

pathLocSegments :: (Metric v, OrderedField n) => Path v n -> [[Located (Segment Closed v n)]] Source #

Convert a path into a list of lists of located segments.

fixPath :: (Metric v, OrderedField n) => Path v n -> [[FixedSegment v n]] Source #

Convert a path into a list of lists of `FixedSegment`s.

# Modifying paths

scalePath :: (HasLinearMap v, Metric v, OrderedField n) => n -> Path v n -> Path v n Source #

Scale a path using its centroid (see `pathCentroid`) as the base point for the scale.

reversePath :: (Metric v, OrderedField n) => Path v n -> Path v n Source #

Reverse all the component trails of a path.

# Miscellaneous

explodePath :: (V t ~ v, N t ~ n, TrailLike t) => Path v n -> [[t]] Source #

"Explode" a path by exploding every component trail (see `explodeTrail`).

partitionPath :: (Located (Trail v n) -> Bool) -> Path v n -> (Path v n, Path v n) Source #

Partition a path into two paths based on a predicate on trails: the first containing all the trails for which the predicate returns `True`, and the second containing the remaining trails.