manual/box.tex

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