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

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

Diagrams.TwoD.Offset

Contents

- Offsets
- Expansions

Description

Compute offsets to segments in two dimensions. More details can be found in the manual at https://diagrams.github.io/doc/manual.html#offsets-of-segments-trails-and-paths.

Synopsis

- offsetSegment :: RealFloat n => n -> n -> Segment Closed V2 n -> Located (Trail V2 n)
- data OffsetOpts d = OffsetOpts {
  - _offsetJoin :: LineJoin
  - _offsetMiterLimit :: d
  - _offsetEpsilon :: d
  }
- offsetJoin :: Lens' (OffsetOpts d) LineJoin
- offsetMiterLimit :: Lens' (OffsetOpts d) d
- offsetEpsilon :: Lens' (OffsetOpts d) d
- offsetTrail :: RealFloat n => n -> Located (Trail V2 n) -> Located (Trail V2 n)
- offsetTrail' :: RealFloat n => OffsetOpts n -> n -> Located (Trail V2 n) -> Located (Trail V2 n)
- offsetPath :: RealFloat n => n -> Path V2 n -> Path V2 n
- offsetPath' :: RealFloat n => OffsetOpts n -> n -> Path V2 n -> Path V2 n
- data ExpandOpts d = ExpandOpts {
  - _expandJoin :: LineJoin
  - _expandMiterLimit :: d
  - _expandCap :: LineCap
  - _expandEpsilon :: d
  }
- expandJoin :: Lens' (ExpandOpts d) LineJoin
- expandMiterLimit :: Lens' (ExpandOpts d) d
- expandCap :: Lens' (ExpandOpts d) LineCap
- expandEpsilon :: Lens' (ExpandOpts d) d
- expandTrail :: RealFloat n => n -> Located (Trail V2 n) -> Path V2 n
- expandTrail' :: (OrderedField n, RealFloat n, RealFrac n) => ExpandOpts n -> n -> Located (Trail V2 n) -> Path V2 n
- expandPath :: RealFloat n => n -> Path V2 n -> Path V2 n
- expandPath' :: RealFloat n => ExpandOpts n -> n -> Path V2 n -> Path V2 n

# Offsets

offsetSegment Source #

Arguments

:: RealFloat n |
=> n | Epsilon factor that when multiplied to the absolute value of the radius gives a value that represents the maximum allowed deviation from the true offset. In the current implementation each result segment should be bounded by arcs that are plus or minus epsilon factor from the radius of curvature of the offset.
-> n | Offset from the original segment, positive is on the right of the curve, negative is on the left.
-> Segment Closed V2 n | Original segment
-> Located (Trail V2 n) | Resulting located (at the offset) trail.

data OffsetOpts d Source #

Compute the offset of a segment. Given a segment compute the offset curve that is a fixed distance from the original curve. For linear segments nothing special happens, the same linear segment is returned with a point that is offset by a perpendicular vector of the given offset length.

Cubic segments require a search for a subdivision of cubic segments that gives an approximation of the offset within the given epsilon factor (the given epsilon factor is applied to the radius giving a concrete epsilon value). We must do this because the offset of a cubic is not a cubic itself (the degree of the curve increases). Cubics do, however, approach constant curvature as we subdivide. In light of this we scale the handles of the offset cubic segment in proportion to the radius of curvature difference between the original subsegment and the offset which will have a radius increased by the offset parameter.

In the following example the blue lines are the original segments and the alternating green and red lines are the resulting offset trail segments.

Note that when the original curve has a cusp, the offset curve forms a radius around the cusp, and when there is a loop in the original curve, there can be two cusps in the offset curve.

Options for specifying line join and segment epsilon for an offset involving multiple segments.

Constructors

OffsetOpts |

Fields

- _offsetJoin :: LineJoin
- _offsetMiterLimit :: d
- _offsetEpsilon :: d

#### Instances

Instances details

Show d => Show (OffsetOpts d) Source # |
Instance details Defined in Diagrams.TwoD.Offset Methods showsPrec :: Int -> OffsetOpts d -> ShowS Source # show :: OffsetOpts d -> String Source # showList :: [OffsetOpts d] -> ShowS Source #
Fractional d => Default (OffsetOpts d) Source # | The default offset options use the default `LineJoin` (`LineJoinMiter`), a miter limit of 10, and epsilon factor of 0.01.
Instance details Defined in Diagrams.TwoD.Offset Methods def :: OffsetOpts d Source #
Eq d => Eq (OffsetOpts d) Source # |
Instance details Defined in Diagrams.TwoD.Offset Methods (==) :: OffsetOpts d -> OffsetOpts d -> Bool Source # (/=) :: OffsetOpts d -> OffsetOpts d -> Bool Source #

offsetJoin :: Lens' (OffsetOpts d) LineJoin Source #

Specifies the style of join for between adjacent offset segments.

offsetMiterLimit :: Lens' (OffsetOpts d) d Source #

Specifies the miter limit for the join.

offsetEpsilon :: Lens' (OffsetOpts d) d Source #

Epsilon perimeter for `offsetSegment`.

offsetTrail :: RealFloat n => n -> Located (Trail V2 n) -> Located (Trail V2 n) Source #

Offset a `Trail` with the default options and a given radius. See `offsetTrail'`.

offsetTrail' Source #

Arguments

:: RealFloat n |
=> OffsetOpts n |
-> n | Radius of offset. A negative value gives an offset on the left for a line and on the inside for a counter-clockwise loop.
-> Located (Trail V2 n) |
-> Located (Trail V2 n) |

Offset a `Trail` with options and by a given radius. This generates a new trail that is always radius `r` away from the given `Trail` (depending on the line join option) on the right.

The styles applied to an outside corner can be seen here (with the original trail in blue and the result of `offsetTrail'` in green):

When a negative radius is given, the offset trail will be on the left:

When offseting a counter-clockwise loop a positive radius gives an outer loop while a negative radius gives an inner loop (both counter-clockwise).

offsetPath :: RealFloat n => n -> Path V2 n -> Path V2 n Source #

Offset a `Path` with the default options and given radius. See `offsetPath'`.

offsetPath' :: RealFloat n => OffsetOpts n -> n -> Path V2 n -> Path V2 n Source #

Offset a `Path` by applying `offsetTrail'` to each trail in the path.

# Expansions

data ExpandOpts d Source #

Options for specifying how a `Trail` should be expanded.

Constructors

ExpandOpts |

Fields

- _expandJoin :: LineJoin
- _expandMiterLimit :: d
- _expandCap :: LineCap
- _expandEpsilon :: d

#### Instances

Instances details

Show d => Show (ExpandOpts d) Source # |
Instance details Defined in Diagrams.TwoD.Offset Methods showsPrec :: Int -> ExpandOpts d -> ShowS Source # show :: ExpandOpts d -> String Source # showList :: [ExpandOpts d] -> ShowS Source #
Fractional d => Default (ExpandOpts d) Source # | The default `ExpandOpts` is the default `LineJoin` (`LineJoinMiter`), miter limit of 10, default `LineCap` (`LineCapButt`), and epsilon factor of 0.01.
Instance details Defined in Diagrams.TwoD.Offset Methods def :: ExpandOpts d Source #
Eq d => Eq (ExpandOpts d) Source # |
Instance details Defined in Diagrams.TwoD.Offset Methods (==) :: ExpandOpts d -> ExpandOpts d -> Bool Source # (/=) :: ExpandOpts d -> ExpandOpts d -> Bool Source #

expandJoin :: Lens' (ExpandOpts d) LineJoin Source #

Specifies the style of join for between adjacent offset segments.

expandMiterLimit :: Lens' (ExpandOpts d) d Source #

Specifies the miter limit for the join.

expandCap :: Lens' (ExpandOpts d) LineCap Source #

Specifies how the ends are handled.

expandEpsilon :: Lens' (ExpandOpts d) d Source #

Epsilon perimeter for `offsetSegment`.

expandTrail :: RealFloat n => n -> Located (Trail V2 n) -> Path V2 n Source #

Expand a `Trail` with the given radius and default options. See `expandTrail'`.

expandTrail' Source #

Arguments

:: (OrderedField n, RealFloat n, RealFrac n) |
=> ExpandOpts n |
-> n | Radius of offset. Only non-negative values allowed. For a line this gives a loop of the offset. For a loop this gives two loops, the outer counter-clockwise and the inner clockwise.
-> Located (Trail V2 n) |
-> Path V2 n |

Expand a `Trail` with the given options and radius `r` around a given `Trail`. Expanding can be thought of as generating the loop that, when filled, represents stroking the trail with a radius `r` brush.

The cap styles applied to an outside corner can be seen here (with the original trail in white and the result of `expandTrail'` filled in green):

Loops result in a path with an inner and outer loop:

expandPath :: RealFloat n => n -> Path V2 n -> Path V2 n Source #

Expand a `Path` with the given radius and default options. See `expandPath'`.

expandPath' :: RealFloat n => ExpandOpts n -> n -> Path V2 n -> Path V2 n Source #

Expand a `Path` using `expandTrail'` on each trail in the path.