manual/deformer.tex

   1 \section{Module \module{deformer}}
   2 \label{deformer}
   3
   4 \declaremodule{}{deformer}
   5 \modulesynopsis{Path deformers}
   6
   7 The \module{deformer} module provides techniques to generate modulated paths.
   8 All classes in the \module{deformer} module can be used as attributes when
   9 drawing/stroking paths onto a canvas, but also independently for manipulating
  10 previously created paths. The difference to the classes in the \module{deco}
  11 module is that here, a totally new path is constructed.
  12
  13 All classes of the \module{deformer} module provide the following methods:
  14
  15 \begin{methoddesc}{__call__}{(specific parameters for the class)}
  16 Returns a deformer with modified parameters
  17 \end{methoddesc}
  18
  19 \begin{methoddesc}{deform}{path} Returns the deformed normpath on the basis of
  20 the \var{path}. This method allows using the deformers outside of a
  21 drawing call.
  22 \end{methoddesc}
  23
  24 The deformer classes are the following:
  25
  26 \begin{classdesc}{cycloid}{radius, halfloops=10, skipfirst=1*unit.t_cm,
  27 skiplast=1*unit.t_cm, curvesperhloop=3, sign=1, turnangle=45}
  28 This deformer creates a cycloid around a path. The outcome looks similar to
  29 a 3D spring stretched along the original path.
  30
  31 \var{radius}: the radius of the cycloid (this is the radius of the 3D spring)
  32
  33 \var{halfloops}: the number of half-loops of the cycloid
  34
  35 \var{skipfirst} and \var{skiplast}: the lengths on the original path not to be bent to a cycloid
  36
  37 \var{curvesperhloop}: the number of Bezier curves to approximate a half-loop
  38
  39 \var{sign}: with \code{sign>=0} starts the cycloid to the left of the path, \code{sign<0} to the right.
  40
  41 \var{turnangle}: the angle of perspective on the 3D spring. At
  42 \code{turnangle=0} one sees a sinusoidal curve, at \code{turnangle=90} one
  43 essentially sees a circle.
  44 \end{classdesc}
  45
  46 \begin{classdesc}{smoothed}{radius, softness=1, obeycurv=0, relskipthres=0.01}
  47 This deformer creates a smoothed variant of the original path. The smoothing is
  48 done on the basis of the corners of the original path, not on a global skope!
  49 Therefore, the result might not be what one would draw by hand. At each corner
  50 (or wherever two path elements meet) a piece of length $2\times$\var{radius} is
  51 taken out of the original path and replaced by a curve. This curve is
  52 determined by the tangent directions and the curvatures at its endpoints. Both
  53 are given from the original path, and therefore, the new curve fits into the
  54 gap in a \textit{geometrically smooth} way. Path elements that are shorter than
  55 \var{radius}$\times$\var{relskipthres} are ignored.
  56
  57 The new curve smoothing the corner consists either of one or of two Bezier
  58 curves, depending on the surrounding path elements. If there are straight lines
  59 before and after the new curve, then two Bezier curves are used. This optimises
  60 the bending of curves in rectangular boxes or polygons. Here, the curves have
  61 an additional degree of freedom that can be set with \var{softness} $\in(0,1]$.
  62 If one of the concerned path elements is curved, only one Bezier curve is used
  63 that is (not always uniquely) determined by its geometrical constraints. There
  64 are, nevertheless, some \textit{caveats}:
  65
  66 A curve that strictly obeys the sign and magnitude of the curvature might not
  67 look very smooth in some cases. Especially when connecting a curved with a
  68 straight piece, the smoothed path contains unwanted overshootings. To prevent
  69 this, the parameter default \var{obeycurv=0} releases the curvature constraints a
  70 little: The curvature may then change its sign (still looks smooth for human
  71 eyes) or, in more extreme cases, even its magnitude (does not look so smooth).
  72 If you really need a geometrically smooth path on the basis of Bezier curves,
  73 then set \var{obeycurv=1}.
  74 \end{classdesc}
  75
  76 %%% Local Variables:
  77 %%% mode: latex
  78 %%% TeX-master: "manual.tex"
  79 %%% ispell-dictionary: "british"
  80 %%% End: