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{classdesc}{deformer}{}
  16   DUMMY
  17 \end{classdesc}
  18
  19 \begin{methoddesc}{__call__}{(specific parameters for the class)}
  20 Returns a deformer with modified parameters
  21 \end{methoddesc}
  22
  23 \begin{methoddesc}{deform}{path} Returns the deformed normpath on the basis of
  24 the \var{path}. This method allows using the deformers outside of a
  25 drawing call.
  26 \end{methoddesc}
  27
  28 The deformer classes are the following:
  29
  30 \begin{classdesc}{cycloid}{radius, halfloops=10, skipfirst=1*unit.t_cm,
  31 skiplast=1*unit.t_cm, curvesperhloop=3, sign=1, turnangle=45}
  32 This deformer creates a cycloid around a path. The outcome looks similar to
  33 a 3D spring stretched along the original path.
  34
  35 \var{radius}: the radius of the cycloid (this is the radius of the 3D spring)
  36
  37 \var{halfloops}: the number of half-loops of the cycloid
  38
  39 \var{skipfirst} and \var{skiplast}: the lengths on the original path not to be bent to a cycloid
  40
  41 \var{curvesperhloop}: the number of Bezier curves to approximate a half-loop
  42
  43 \var{sign}: with \code{sign>=0} starts the cycloid to the left of the path, \code{sign<0} to the right.
  44
  45 \var{turnangle}: the angle of perspective on the 3D spring. At
  46 \code{turnangle=0} one sees a sinusoidal curve, at \code{turnangle=90} one
  47 essentially sees a circle.
  48 \end{classdesc}
  49
  50 \begin{classdesc}{smoothed}{radius, softness=1, obeycurv=0, relskipthres=0.01}
  51 This deformer creates a smoothed variant of the original path. The smoothing is
  52 done on the basis of the corners of the original path, not on a global skope!
  53 Therefore, the result might not be what one would draw by hand. At each corner
  54 (or wherever two path elements meet) a piece of length $2\times$\var{radius} is
  55 taken out of the original path and replaced by a curve. This curve is
  56 determined by the tangent directions and the curvatures at its endpoints. Both
  57 are given from the original path, and therefore, the new curve fits into the
  58 gap in a \textit{geometrically smooth} way. Path elements that are shorter than
  59 \var{radius}$\times$\var{relskipthres} are ignored.
  60
  61 The new curve smoothing the corner consists either of one or of two Bezier
  62 curves, depending on the surrounding path elements. If there are straight lines
  63 before and after the new curve, then two Bezier curves are used. This optimises
  64 the bending of curves in rectangular boxes or polygons. Here, the curves have
  65 an additional degree of freedom that can be set with \var{softness} $\in(0,1]$.
  66 If one of the concerned path elements is curved, only one Bezier curve is used
  67 that is (not always uniquely) determined by its geometrical constraints. There
  68 are, nevertheless, some \textit{caveats}:
  69
  70 A curve that strictly obeys the sign and magnitude of the curvature might not
  71 look very smooth in some cases. Especially when connecting a curved with a
  72 straight piece, the smoothed path contains unwanted overshootings. To prevent
  73 this, the parameter default \var{obeycurv=0} releases the curvature constraints a
  74 little: The curvature may then change its sign (still looks smooth for human
  75 eyes) or, in more extreme cases, even its magnitude (does not look so smooth).
  76 If you really need a geometrically smooth path on the basis of Bezier curves,
  77 then set \var{obeycurv=1}.
  78 \end{classdesc}
  79
  80 \begin{classdesc}{parallel}{distance, relerr=0.05, sharpoutercorners=0, dointersection=1,
  81                        checkdistanceparams=[0.5], lookforcurvatures=11}%
  82 This deformer creates a parallel curve to a given path. The result is similar to
  83 what is usually referred to as the \emph{set with constant distance} to the set of
  84 points on the path. It differs in one important respect, because the
  85 \var{distance} parameter in the deformer is a signed distance. The resulting
  86 parallel normpath is constructed on the level of the original pathitems. For
  87 each of them a parallel pathitem is constructed. Then, they are connected by
  88 circular arcs (or by sharp edges) around the corners of the original path.
  89 Later, everything that is nearer to the original path than distance is cut away.
  90
  91 There are some caveats:
  92 \begin{itemize}
  93   \item When the original path is too curved then the parallel path would
  94   contain points with infinte curvature. The resulting path stops at such points
  95   and leaves the too strongly curved piece out.
  96   \item When the original path contains self-intersection, then the resulting
  97   parallel path is not continuous in the parameterisation of the original path.
  98   It may first take a piece that corresponds to ``later'' parameter values and
  99   then continue with an ``earlier'' one. Please don't get confused.
 100 \end{itemize}
 101
 102 The parameters are the following:
 103
 104 \var{distance} is the minimal (signed) distance between the original and the
 105 parallel paths.
 106
 107 \var{relerr} is the allowed error in the distance is given by
 108 \code{distance*relerr}.
 109
 110 \var{sharpoutercorners} connects the parallel pathitems by wegde build of
 111 straight lines, instead of taking circular arcs. This preserves the angle of the
 112 original corners.
 113
 114 \var{dointersection} is a boolean for performing the last step, the intersection
 115 step, in the path construction. Setting this to 0 gives the full parallel path,
 116 which can be favourable for self-intersecting paths.
 117
 118 \var{checkdistanceparams} is a list of parameter values in the interval (0,1)
 119 where the distance is checked on each parallel pathitem
 120
 121 \var{lookforcurvatures} is the number of points per normpathitem where its
 122 curvature is checked for critical values
 123
 124 \end{classdesc}
 125
 126 %%% Local Variables:
 127 %%% mode: latex
 128 %%% TeX-master: "manual.tex"
 129 %%% ispell-dictionary: "british"
 130 %%% End: