manual/box.rst

   1
   2 .. module:: box
   3
   4 **************************************
   5 Module :mod:`box`: Convex box handling
   6 **************************************
   7
   8 This module has a quite internal character, but might still be useful from the
   9 users point of view. It might also get further enhanced to cover a broader range
  10 of standard arranging problems.
  11
  12 In the context of this module a box is a convex polygon having optionally a
  13 center coordinate, which plays an important role for the box alignment. The
  14 center might not at all be central, but it should be within the box. The
  15 convexity is necessary in order to keep the problems to be solved by this module
  16 quite a bit easier and unambiguous.
  17
  18 Directions (for the alignment etc.) are usually provided as pairs (dx, dy)
  19 within this module. It is required, that at least one of these two numbers is
  20 unequal to zero. No further assumptions are taken.
  21
  22
  23 Polygon
  24 =======
  25
  26 A polygon is the most general case of a box. It is an instance of the class
  27 ``polygon``. The constructor takes a list of points (which are (x, y) tuples) in
  28 the keyword argument ``corners`` and optionally another (x, y) tuple as the
  29 keyword argument ``center``. The corners have to be ordered counterclockwise. In
  30 the following list some methods of this ``polygon`` class are explained:
  31
  32 ``path(centerradius=None, bezierradius=None, beziersoftness=1)``:
  33    returns a path of the box; the center might be marked by a small circle of
  34    radius ``centerradius``; the corners might be rounded using the parameters
  35    ``bezierradius`` and ``beziersoftness``. For each corner of the box there may be
  36    one value for beziersoftness and two bezierradii. For convenience, it is not
  37    necessary to specify the whole list (for beziersoftness) and the whole list of
  38    lists (bezierradius) here. You may give a single value and/or a 2-tuple instead.
  39
  40 ``transform(*trafos)``:
  41    performs a list of transformations to the box
  42
  43 ``reltransform(*trafos)``:
  44    performs a list of transformations to the box relative to the box center
  45
  46 .. _fig_boxalign:
  47 .. figure:: boxalign.*
  48    :align:  center
  49
  50    circle and line alignment examples (equal direction and distance)
  51
  52 ``circlealignvector(a, dx, dy)``:
  53    returns a vector (a tuple (x, y)) to align the box at a circle with radius ``a``
  54    in the direction (``dx``, ``dy``); see figure :ref:`fig_boxalign`
  55
  56 ``linealignvector(a, dx, dy)``:
  57    as above, but align at a line with distance ``a``
  58
  59 ``circlealign(a, dx, dy)``:
  60    as circlealignvector, but perform the alignment instead of returning the vector
  61
  62 ``linealign(a, dx, dy)``:
  63    as linealignvector, but perform the alignment instead of returning the vector
  64
  65 ``extent(dx, dy)``:
  66    extent of the box in the direction (``dx``, ``dy``)
  67
  68 ``pointdistance(x, y)``:
  69    distance of the point (``x``, ``y``) to the box; the point must be outside of
  70    the box
  71
  72 ``boxdistance(other)``:
  73    distance of the box to the box ``other``; when the boxes are overlapping,
  74    ``BoxCrossError`` is raised
  75
  76 ``bbox()``:
  77    returns a bounding box instance appropriate to the box
  78
  79
  80 Functions working on a box list
  81 ===============================
  82
  83 ``circlealignequal(boxes, a, dx, dy)``:
  84    Performs a circle alignment of the boxes ``boxes`` using the parameters ``a``,
  85    ``dx``, and ``dy`` as in the ``circlealign`` method. For the length of the
  86    alignment vector its largest value is taken for all cases.
  87
  88 ``linealignequal(boxes, a, dx, dy)``:
  89    as above, but performing a line alignment
  90
  91 ``tile(boxes, a, dx, dy)``:
  92    tiles the boxes ``boxes`` with a distance ``a`` between the boxes (in addition
  93    the maximal box extent in the given direction (``dx``, ``dy``) is taken into
  94    account)
  95
  96
  97 Rectangular boxes
  98 =================
  99
 100 For easier creation of rectangular boxes, the module provides the specialized
 101 class ``rect``. Its constructor first takes four parameters, namely the x, y
 102 position and the box width and height. Additionally, for the definition of the
 103 position of the center, two keyword arguments are available. The parameter
 104 ``relcenter`` takes a tuple containing a relative x, y position of the center
 105 (they are relative to the box extent, thus values between ``0`` and ``1`` should
 106 be used). The parameter ``abscenter`` takes a tuple containing the x and y
 107 position of the center. This values are measured with respect to the lower left
 108 corner of the box. By default, the center of the rectangular box is set to this
 109 lower left corner.
 110