Intuitively, a trail is a single, continuous path through space. However, a trail has no fixed starting point; it merely specifies how to move through space, not where. For example, "take three steps forward, then turn right twenty degrees and take two more steps" is an intuitive analog of a trail; these instructions specify a path through space from any given starting location. To be precise, trails are translation-invariant; applying a translation to a trail has no effect.

A Located Trail, on the other hand, is a trail paired with some concrete starting location ("start at the big tree on the corner, then take three steps forward, ..."). See the Diagrams.Located module for help working with Located values.

Formally, the semantics of a trail is a continuous (though not necessarily differentiable) function from the real interval [0,1] to vectors in some vector space. (In contrast, a Located trail is a continuous function from [0,1] to points in some affine space.)

There are two types of trails:

• A "line" (think of the "train", "subway", or "bus" variety, rather than the "straight" variety...) is a trail with two distinct endpoints. Actually, a line can have the same start and end points, but it is still drawn as if it had distinct endpoints: the two endpoints will have the appropriate end caps, and the trail will not be filled. Lines have a Monoid instance where mappend corresponds to concatenation, i.e. chaining one line after the other.
• A "loop" is required to end in the same place it starts (that is, t(0) = t(1)). Loops are filled and are drawn as one continuous loop, with the appropriate join at the start/endpoint rather than end caps. Loops do not have a Monoid instance.

To convert between lines and loops, see glueLine, closeLine, and cutLoop.

To construct trails, see emptyTrail, trailFromSegments, trailFromVertices, trailFromOffsets, and friends. You can also get any type of trail from any function which returns a TrailLike (e.g. functions in Diagrams.TwoD.Shapes, and many others; see Diagrams.TrailLike).

To extract information from trails, see withLine, isLoop, trailSegments, trailOffsets, trailVertices, and friends.

Make a line into a loop by "gluing" the endpoint to the starting point. In particular, the offset of the final segment is modified so that it ends at the starting point of the entire trail. Typically, you would first construct a line which you know happens to end where it starts, and then call glueLine to turn it into a loop.

glueLineEx = pad 1.1 . hsep 1
  $ [almostClosed # strokeLine, almostClosed # glueLine # strokeLoop]

almostClosed :: Trail' Line V2 Double
almostClosed = fromOffsets $ map r2 [(2, -1), (-3, -0.5), (-2, 1), (1, 0.5)]

glueLine is left inverse to cutLoop, that is,

  glueLine . cutLoop === id
  

Make a line into a loop by adding a new linear segment from the line's end to its start.

closeLine does not have any particularly nice theoretical properties, but can be useful e.g. when you want to make a closed polygon out of a list of points where the initial point is not repeated at the end. To use glueLine, one would first have to duplicate the initial vertex, like

glueLine . lineFromVertices $ ps ++ [head ps]

Using closeLine, however, one can simply

closeLine . lineFromVertices $ ps

closeLineEx = pad 1.1 . centerXY . hcat' (with & sep .~ 1)
  $ [almostClosed # strokeLine, almostClosed # closeLine # strokeLoop]

Turn a loop into a line by "cutting" it at the common start/end point, resulting in a line which just happens to start and end at the same place.

cutLoop is right inverse to glueLine, that is,

  glueLine . cutLoop === id
  

Trail is a wrapper around Trail', hiding whether the underlying Trail' is a line or loop (though which it is can be recovered; see e.g. withTrail).

Prism onto a Line.

Prism onto a Loop.

Prism onto a Located Line.

Prism onto a Located Loop.

Convert a Trail' into a Trail, hiding the type-level distinction between lines and loops.

Convert a line into a Trail. This is the same as wrapTrail, but with a more specific type, which can occasionally be convenient for fixing the type of a polymorphic expression.

Convert a loop into a Trail. This is the same as wrapTrail, but with a more specific type, which can occasionally be convenient for fixing the type of a polymorphic expression.

Modify a Trail, specifying two separate transformations for the cases of a line or a loop.

Modify a Trail by specifying a transformation on lines. If the trail is a line, the transformation will be applied directly. If it is a loop, it will first be cut using cutLoop, the transformation applied, and then glued back into a loop with glueLine. That is,

  onLine f === onTrail f (glueLine . f . cutLoop)
  

Note that there is no corresponding onLoop function, because there is no nice way in general to convert a line into a loop, operate on it, and then convert back.

glueTrail is a variant of glueLine which works on Trails. It performs glueLine on lines and is the identity on loops.

closeTrail is a variant of closeLine for Trail, which performs closeLine on lines and is the identity on loops.

cutTrail is a variant of cutLoop for Trail; it is the is the identity on lines and performs cutLoop on loops.

The empty line, which is the identity for concatenation of lines.

A wrapped variant of emptyLine.

Construct a line containing only linear segments from a list of vertices. Note that only the relative offsets between the vertices matters; the information about their absolute position will be discarded. That is, for all vectors v,

lineFromVertices === lineFromVertices . translate v

If you want to retain the position information, you should instead use the more general fromVertices function to construct, say, a Located (Trail' Line v) or a Located (Trail v).

import Diagrams.Coordinates
lineFromVerticesEx = pad 1.1 . centerXY . strokeLine
  $ lineFromVertices [origin, 0 ^& 1, 1 ^& 2, 5 ^& 1]

trailFromVertices === wrapTrail . lineFromVertices, for conveniently constructing a Trail instead of a Trail' Line.

Construct a line containing only linear segments from a list of vectors, where each vector represents the offset from one vertex to the next. See also fromOffsets.

import Diagrams.Coordinates
lineFromOffsetsEx = strokeLine $ lineFromOffsets [ 2 ^& 1, 2 ^& (-1), 2 ^& 0.5 ]

trailFromOffsets === wrapTrail . lineFromOffsets, for conveniently constructing a Trail instead of a Trail' Line.

Construct a line from a list of closed segments.

trailFromSegments === wrapTrail . lineFromSegments, for conveniently constructing a Trail instead of a Trail'.

Construct a loop from a list of closed segments and an open segment that completes the loop.

A generic eliminator for Trail', taking functions specifying what to do in the case of a line or a loop.

A generic eliminator for Trail, taking functions specifying what to do in the case of a line or a loop.

An eliminator for Trail based on eliminating lines: if the trail is a line, the given function is applied; if it is a loop, it is first converted to a line with cutLoop. That is,

withLine f === withTrail f (f . cutLoop)

Test whether a line is empty.

Test whether a trail is empty. Note that loops are never empty.

Determine whether a trail is a line.

Determine whether a trail is a loop.

Extract the segments of a trail. If the trail is a loop it will first have cutLoop applied.

Extract the segments comprising a line.

Extract the segments comprising a loop: a list of closed segments, and one final open segment.

Modify a line by applying a function to its list of segments.

Extract the offsets of the segments of a trail.

Compute the offset from the start of a trail to the end. Satisfies

  trailOffset === sumV . trailOffsets
  

but is more efficient.

trailOffsetEx = (strokeLine almostClosed <> showOffset) # centerXY # pad 1.1
  where showOffset = fromOffsets [trailOffset (wrapLine almostClosed)]
                   # strokeP # lc red

Extract the offsets of the segments of a line.

Compute the offset from the start of a line to the end. (Note, there is no corresponding loopOffset function because by definition it would be constantly zero.)

Extract the offsets of the segments of a loop.

Extract the points of a concretely located trail, i.e. the points where one segment ends and the next begins. Note that for loops, the starting point will not be repeated at the end. If you want this behavior, you can use cutTrail to make the loop into a line first, which happens to repeat the same point at the start and end, e.g. with trailPoints . mapLoc cutTrail.

Note that it does not make sense to ask for the points of a Trail by itself; if you want the points of a trail with the first point at, say, the origin, you can use trailPoints . (`at` origin).

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. For an unproblematic version which only yields vertices at which there is a sharp corner, excluding points where the trail is differentiable, see trailVertices.

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

Extract the segment join points of a concretely located line. See trailPoints for more information.

This function allows you "observe" the fact that lines are implemented as lists of segments, which may be problematic if we want to think of lines 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. For an unproblematic version which only yields vertices at which there is a sharp corner, excluding points where the trail is differentiable, see lineVertices.

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

Extract the segment join points of a concretely located loop. Note that the initial vertex is not repeated at the end. See trailPoints for more information.

This function allows you "observe" the fact that lines are implemented as lists of segments, which may be problematic if we want to think of lines 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. For an unproblematic version which only yields vertices at which there is a sharp corner, excluding points where the trail is differentiable, see lineVertices.

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

Extract the vertices of a concretely located 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 trailPoints.) The tolerance determines how close the tangents of two segments must be at their endpoints to consider the transition point to be differentiable.

Note that for loops, the starting vertex will not be repeated at the end. If you want this behavior, you can use cutTrail to make the loop into a line first, which happens to repeat the same vertex at the start and end, e.g. with trailVertices . mapLoc cutTrail.

It does not make sense to ask for the vertices of a Trail by itself; if you want the vertices of a trail with the first vertex at, say, the origin, you can use trailVertices . (`at` origin).

Extract the vertices of a concretely located line. See trailVertices for more information.

Extract the vertices of a concretely located loop. Note that the initial vertex is not repeated at the end. See trailVertices for more information.

Like trailVertices', with a default tolerance.

Like lineVertices', with a default tolerance.

Same as loopVertices', with a default tolerance.

Convert a concretely located trail into a list of located segments.

Convert a concretely located trail into a list of fixed segments. unfixTrail is almost its left inverse.

Convert a list of fixed segments into a located trail. Note that this may lose information: it throws away the locations of all but the first FixedSegment. This does not matter precisely when each FixedSegment begins where the previous one ends.

This is almost left inverse to fixTrail, that is, unfixTrail . fixTrail == id, except for the fact that unfixTrail will never yield a Loop. In the case of a loop, we instead have glueTrail . unfixTrail . fixTrail == id. On the other hand, it is not the case that fixTrail . unfixTrail == id since unfixTrail may lose information.

Reverse a trail. Semantically, if a trail given by a function t from [0,1] to vectors, then the reverse of t is given by t'(s) = t(1-s). reverseTrail is an involution, that is,

  reverseTrail . reverseTrail === id
  

Reverse a concretely located trail. The endpoint of the original trail becomes the starting point of the reversed trail, so the original and reversed trails comprise exactly the same set of points. reverseLocTrail is an involution, i.e.

  reverseLocTrail . reverseLocTrail === id
  

Reverse a line. See reverseTrail.

Reverse a concretely located line. See reverseLocTrail.

Reverse a loop. See reverseTrail.

Reverse a concretely located loop. See reverseLocTrail. Note that this is guaranteed to preserve the location.

Type tag for trails with distinct endpoints.

Type tag for "loopy" trails which return to their starting point.

A SegTree represents a sequence of closed segments, stored in a fingertree so we can easily recover various monoidal measures of the segments (number of segments, arc length, envelope...) and also easily slice and dice them according to the measures (e.g., split off the smallest number of segments from the beginning which have a combined arc length of at least 5).

Given a default result (to be used in the case of an empty trail), and a function to map a single measure to a result, extract the given measure for a trail and use it to compute a result. Put another way, lift a function on a single measure (along with a default value) to a function on an entire trail.

Compute the number of segments of anything measured by SegMeasure (e.g. SegMeasure itself, Segment, SegTree, Trails...)

Compute the total offset of anything measured by SegMeasure.

A newtype wrapper around trails which exists solely for its Parametric, DomainBounds and EndValues instances. The idea is that if tr is a trail, you can write, e.g.

  getSegment tr atParam 0.6
  

or

  atStart (getSegment tr)
  

to get the segment at parameter 0.6 or the first segment in the trail, respectively.

The codomain for GetSegment, i.e. the result you get from calling atParam, atStart, or atEnd, is GetSegmentCodomain, which is a newtype wrapper around Maybe (v, Segment Closed v, AnIso' n n). Nothing results if the trail is empty; otherwise, you get:

• the offset from the start of the trail to the beginning of the segment,
• the segment itself, and
• a reparameterization isomorphism: in the forward direction, it translates from parameters on the whole trail to a parameters on the segment. Note that for technical reasons you have to call cloneIso on the AnIso' value to get a real isomorphism you can use.

Create a GetSegment wrapper around a trail, after which you can call atParam, atStart, or atEnd to extract a segment.