manual/metapost.rst

   1 .. module:: metapost
   2
   3 ======================
   4 Module :mod:`metapost`
   5 ======================
   6
   7 .. sectionauthor:: Michael Schindler <m-schindler@users.sourceforge.net>
   8
   9 The :mod:`metapost` subpackage provides some of the path functionality of the
  10 MetaPost program.
  11
  12
  13 Class :class:`path` --- MetaPost-like paths
  14 -------------------------------------------
  15
  16 .. class:: path(pathitems)
  17
  18    This class represents a MetaPost-like path which is created from the given
  19    list of knots and curves/lines. It can find an optimal way through given
  20    points.
  21
  22    At points (knots), you can either specify a given tangent direction (angle
  23    in degrees) or a certain *curlyness* (relative to the curvature at the other
  24    end of a curve), or nothing. In the latter case, both the tangent and the
  25    *mock* curvature (an approximation to the real curvature, introduced by J. D.
  26    Hobby in MetaPost) will be continuous.
  27
  28    The shape of the cubic Bezier curves between two points is controlled by
  29    its *tension*, unless you choose to set the control points manually.
  30
  31    All possible path items are described below. They are either :ref:`knots` or
  32    :ref:`links`. Note that there is no explicit `closepath` class. Whether the
  33    path is open or closed depends on the type of knots used, begin endpoints or
  34    not. Note also that the number of knots and links must be equal for closed
  35    paths, and that you cannot create a path comprising closed subpaths.
  36
  37 Instances of the class :class:`path` inherit all properties of the Postscript
  38 paths in :mod:`path`.
  39
  40
  41 .. _knots:
  42
  43 Knots
  44 -----
  45
  46 .. class:: beginknot(x, y, curl=1, angle=None)
  47
  48    The first knot, starting an open path at the coordinates (*x*, *y*). The
  49    properties of the curve in that point can either be given by its curlyness
  50    (default) or the angle of its tangent vector (in degrees). The *curl*
  51    parameter is (as in MetaPost) the ratio of the curvatures at this point and
  52    at the other point of the curve connecting it.
  53
  54 .. class:: startknot(x, y, curl=1, angle=None)
  55
  56    Synonym for :class:`beginknot`.
  57
  58 .. class:: endknot(x, y, curl=1, angle=None)
  59
  60    The last knot of an open path. Curlyness and angle are the same as in
  61    :class:`beginknot`.
  62
  63 .. class:: smoothknot(x, y)
  64
  65    This knot is the standard knot of MetaPost. It guarantees continuous tangent
  66    vectors and *mock curvatures* of the two curves it connects.
  67
  68    Note: If one of the links is a line, the knot is changed to a
  69    :class:`roughknot` with either a specified angle (if the *keepangles*
  70    parameter is set in the line) or with *curl=1*.
  71
  72 .. class:: roughknot(x, y, left_curl=1, right_curl=None, left_angle=None, right_angle=None)
  73
  74    This knot is a possibly non-smooth knot, connecting two curves or lines. At
  75    each side of the knot (left/right) you can specify either the curlyness or
  76    the tangent angle.
  77
  78    Note: If one of the links is a line with the *keepangles* parameter set, the
  79    angles will be set eplicitly, regardless of any curlyness set.
  80
  81 .. class:: knot(x, y)
  82
  83    Synonym for :class:`smoothknot`.
  84
  85
  86 .. _links:
  87
  88 Links
  89 -----
  90
  91 .. class:: line(keepangles=False)
  92
  93    A straight line which corresponds to the MetaPost command "-". The option
  94    *keepangles* will guarantee a continuous tangent. (The curvature may become
  95    discontinuous, however.)
  96
  97 .. class:: tensioncurve(ltension=1, latleast=False, rtension=None, ratleast=None)
  98
  99    The standard type of curve in MetaPost. It corresponds to the MetaPost
 100    command ".." or to "..." if the *atleast* parameters are set to True. The
 101    tension parameters indicate the tensions at the beginning (l) and the end
 102    (r) of the curve. Set the parameters (l/r)atleast to True if you want to
 103    avoid inflection points.
 104
 105 .. class:: controlcurve(lcontrol, rcontrol)
 106
 107    A cubic Bezier curve which has its control points explicity set, similar to
 108    the :class:`path.curveto` class of the Postscript paths. The control points
 109    at the beginning (l) and the end (r) must be coordinate pairs (x, y).
 110
 111 .. class:: curve(ltension=1, latleast=False, rtension=None, ratleast=None)
 112
 113    Synonym for :class:`tensioncurve`.
 114
 115