UL_POLYPOUR

Data members

Loop members

See also UL_SIGNAL

Note

The contours() loop member loops through the wires that are used to draw the outlines of the polygon pour's fill data. The fillings() loop member loops through the hatching wires that are used to draw the polygon pour when its hatched data member is set. When the hatched data member is not set, then fillings() does nothing. The wires() loop member always loops through the polygon wires as they were drawn by the user.

A polygon pour's fill results may consist of several distinct closed figures (called positive polygon contours), each of which can contain voids/holes (negative polygon contours) resulting from other objects being subtracted from the positive contour. Negative contours can again contain other positive contours and so on.

Invoking contours() and interpreting its results

If the contours() loop member is called without a second parameter, it loops through all of the contour wires, regardless of whether they belong to a positive polygon contour outline or a negative polygon contour hole. In this case, the wires looped through by contours() always start with a positive polygon contour. If you are interested in getting the positive and negative contour wires separately, you can call contours() with an additional integer parameter (see the second example below). The sign of that parameter determines whether a positive or a negative polygon contour will be returned, and the value indicates the index of that polygon contour. If there is no polygon contour with the given index, the statement will not be executed. An advantage of this method is that you don't need to determine the beginning and end of a particular polygon contour yourself (by comparing coordinates). For any given index, the statement will be executed for all the wires of that polygon contour. Passing the second parameter as 0 produces the same behavior as without a second parameter.

The wires of a polygon contour are directed end-to-end. To determine where one contour ends and the next one begins, simply store the (x1,y1) coordinates of the first wire and check them against (x2,y2) of each following wire. When these points are equivalent, the last wire of the polygon contour has been found.

Positive polygon contours (forming outer edges) are oriented clockwise, while negative polygon contours (forming hole edges) are oriented counter-clockwise. To determine "inside" and "outside" of the polygon pour, imagine sighting along any contour wire from its point (x1,y1) to (x2,y2). The "inside" of the polygon pour is always on the right side of the wire.

Example

board(B) {
  B.signals(S) {
    S.polypours(P) {
      int x0, y0, first = 1;
      P.contours(W) {
        if (first) {
           // a new polygon contouris starting
           x0 = W.x1;
           y0 = W.y1;
           }
        // ...
        // do something with the wire
        // ...
        if (first)
           first = 0;
        else if (W.x2 == x0 && W.y2 == y0) {
           // this was the last wire of the polygon contour,
           // so the next wire (if any) will be the first wire
           // of the next polygon contour
           first = 1;
           }
        }
      }
    }
  }
board(B) {
  B.signals(S) {
    S.polypours(P) {
      // process only the "positive" polygon contours:
      int i = 1;
      int active;
      do {
         active = 0;
         P.contours(W, i) {
           active = 1;
           // do something with the wire
           }
         i++;
         } while (active);
      }
    }
  }