Algorithm A General Polygon Clipping Library

A General Polygon Clipping Library Version 2.32 http://www.cs.man.ac.uk/~toby/alan/software/gpc.html

Alan Murta Advanced Interfaces Group Department of the computer science University of Manchester Manchester M13 9PL, UK

Abstract:this document describes a C library implementation of a new polygon clipping algorithm. The techniques used is descended from Vatti ' s polygon clipping method [1]. Subject and clip polygons may is convex or concave, self-intersecting, contain holes, or be comprised of several disjoint Contours. It extends the Vatti algorithm to allow horizontal edges in the source polygons, and to handle coincident edges in a robus t manner. Four types of clipping operation is supported: intersection, exclusive-or, UnionOr differenceof subject and clip polygons. The output may take the form of polygon outlines or tristrips. Introduction

A generic polygon (or ' polygon set ') consists of zero or more disjoint boundaries of arbitrary configuration. Each boundary are termed a ' contour ', and may be convex, concave or self-intersecting. Internal holes May is formed by contour nesting.

Figure 1: A Polygon set with four contours.

Figure 1 shows a polygon set comprised of four contours. Over-to-the-left is a seven sided concave contour. Lying completely within it is a four-sided contour, which forms a hole in the surrounding shape. A third, triangular contour intersects the boundary of the first. Finally, over-to-right is a disjoint self-intersecting four-sided contour. The interior of the polygon have been shaded for clarity.

The library supports four kinds of clipping (Boolean set) operation: difference, intersection exclus Ive-or or union of subject and clip polygon pairs. These is illustrated in Figure 2. In each case, the resulting polygon is shown shaded.

Figure 2: Difference, intersection, EXCLUSIVE-OR and union operations. Recent API Changes

The release of Version 2.30 featured some minor changes to the application programmer ' s interface. These included:

• An additional hole field in the gpc_polygon datatype to differentiate hole contours from external Contou Rs.
• A similar additional hole parameter to gpc_add_contour ().
• An extra parameter in the Gpc_read_polygon () and Gpc_write_polygon () functions to specify the Polygon da Tafile format (with or without hole contour flags).

Data types

The generic Polygon Clipper (GPC) library defines the following structure types for the representation of polygons:

          typedef struct/   * Polygon vertex */          {            double            x;            Double            y;          } Gpc_vertex;          typedef struct/   * Polygon Contour */          {            int               num_vertices;            Gpc_vertex       *vertex;                } gpc_vertex_list;          typedef struct/   * Polygon set */          {            int               num_contours;            int              *hole;            Gpc_vertex_list  *contour;               } Gpc_polygon;

The Clipper takes a pair of subject and clip polygons and combines them to form a result polygon. For each contour polygon in the result polygon, the hole value of the flags whether or not the given contour forms a h OLE or an external boundary.

Alternatively a collection of Tristrips may is generated as the result, this form being more suitable for rendering filled Shapes. (The polygon result form is better for drawing outlines, or as intermediate values in multi-clip operations.) Tristrip collections is represented using the following data type:

          typedef struct/   * Set of Tristrips */          {            int               num_strips;            Gpc_vertex_list  *strip;               } Gpc_tristrip;

Library functions

Eight functions is provided by the library. The reading and writing of data between polygon files and Gpc_polygon structures.

          void Gpc_read_polygon (FILE        *fp,                                int          read_hole_flags,                                gpc_polygon *polygon);            void Gpc_write_polygon (FILE        *fp,                                 int          write_hole_flags,                                 gpc_polygon *polygon);

A polygon is stored in an ASCII file using the format:

<num-contours> <num-vertices-in-first-contour> [< First-contour-hole-flag] <vertex-list>
<num-vertices-in-second-contour> [<second-contour-hole-flag;] < Vertex-list>

etc. The Hole-flag values is optional, their reading and writing being controlled by setting the second argument of Gpc_re Ad_polygon () and Gpc_write_polygon () to 1 (TRUE) or 0 (FALSE). Clip operations would correctly set the contour hole flags of the result polygon. This information are ignored by the user application if it's not required.

For example, a single polygon consisting of a triangular hole within a quadrilateral (with hole flags included) could take t He form:

          2          3          1            4.0   4.0            6.0   5.0            5.0   6.0          4          0            2.0   1.0            8.0   2.0            7.0   9.0            1.0   7.0

An interactive drawing-require the ability to construct a polygon contour-by-contour in an incremental fashion . The function gpc_add_contour () facilitates the merging of a new contour with an existing polygon. The final parameter have the value 1 (TRUE) or 0 (FALSE), and indicates whether or not the contour should be considered to is a hole. It is suggested, all contours be initially treated as non-hole (external) contours. Any subsequent clipping operation would set the result polygon hole flags correctly.

          void Gpc_add_contour (Gpc_polygon     *p,                               gpc_vertex_list *c,                               int              hole);

The clipping operation itself is performed by the function

          void Gpc_polygon_clip (Gpc_op       operation,                                Gpc_polygon *subject_p,                                gpc_polygon *clip_p,                                Gpc_polygon * Result_p);

Or, if a tristrip based result is required

          void Gpc_tristrip_clip (Gpc_op        operation,                                 Gpc_polygon  *subject_p,                                 gpc_polygon  *clip_p,                                 Gpc_tristrip *result_t);

In both cases the first parameter specifies the clip operation to be performed (namely Gpc_diff, gpc_int , gpc_xor or gpc_union). This was followed by subject and clip polygon parameters. The final parameter delivers the result, either as a polygon structure or as a collection of tristrips.

A polygon May is converted to the equivalent Tristrip form using the function

          void Gpc_polygon_to_tristrip (Gpc_polygon   *source_p,                                        gpc_tristrip *result_t);

Finally, the functions

          void Gpc_free_polygon (Gpc_polygon *p);          void Gpc_free_tristrip (Gpc_tristrip *t);

May is used to release the memory taken up by a polygon or trapezoid on the heap.

Hole and external contours

A Contour is classified as an external contour if it uppermost (or rightmost, when the contour top is horizontal ) vertex forms an external local maximum (EMX). If this vertex forms an internal local maximum (IMX) The contour is classified as a hole contour.

When Contour edges cross (in self intersecting shapes for example) the Clipper would always generate a local maximum vertex Below the intersection (or when one of the edges are horizontal, to the left of the intersection) which connects the Edge Parts which meet at the "intersection point" from below or from the left. The edge parts which emerge from the opposite side of the intersection point originate from a new local minimum vertex. The closed contours generated by the Clipper would never self-intersect.

Figure 3: Self-intersecting contours which decompose to an external contour containing a nested hole contour.

These rules has implications with regard to how self intersecting shapes decompose into a set of closed, non-intersecting Contours. The intersecting square examples of Figure 3, would each create the nested contours. In each case, the Upper/rightmost maximum vertex of the internal contour forms an internal maximum, therefore the Contou R is classed as a hole (shown dotted). The corresponding outer contour is considered external as it terminates with an external maximum vertex.

Figure 4: Self-intersecting contours which decompose into, touching external contours.

The examples of Figure 4, however, show how similar self intersecting shapes could each create the external contours which t Ouch at the points of intersection. In summary, the contour paths generated by the Clipper is affected not only by the shape of the input polygons, but also By their orientation.

Associating holes with external contours

The current version of the Clipper merely flags which contours is considered to be holes, and which form external Boundar ies. Discovering which holes lie within which external contours takes a little more work on the part of the user. One-to-associate holes H1, h2 ... Hn with external contours e1, e2 ... the Clipper to compute the difference of the ith hole Hi and each external contour Ej, for all J from 1 to m. Any difference which gives a empty result indicates that hole I lies within external contour J.

Coincident and near-coincident edges

The clipper would merge edges which is coincident. Adjacent subject and clip contours which share share a common edge would fuse to form a single contour under the union<  /c0> operation, and would produce a null result along their GKFX boundary under the intersection operation. Numerical precision limits is likely to cause the slight misregistration of coincident edges, resulting in a failure to M Erge. Increasing the value of the Gpc_epsilon constant in gpc.h would encourage the merging of near-coincident Edges. However, incorrect output polygon shapes may result if Gpc_epsilon is given too large a value.

A code Example

The following example program a clip/subject polygon pair are read from an input file. The intersection of these polygons is then calculated, and the result polygon was written to file. Hole classification information is neither read nor written in this example.

          #include <stdio.h>          #include "gpc.h"          int main (void)          {            Gpc_polygon subject, clip, result;            FILE *SFP, *CFP, *OFP;                sfp= fopen ("Subjfile", "R");            cfp= fopen ("Clipfile", "R");            Gpc_read_polygon (SFP, 0, &subject);            Gpc_read_polygon (CFP, 0, &clip);                Gpc_polygon_clip (Gpc_int, &subject, &clip, &result);            ofp= fopen ("outfile", "w");            Gpc_write_polygon (OFP, 0, &result);                Gpc_free_polygon (&subject);            Gpc_free_polygon (&clip);            Gpc_free_polygon (&result);                      Fclose (SFP);            Fclose (CFP);            Fclose (OFP);            return 0;          }

Known bugs

The following problems would hopefully be rectified within subsequent releases. Please see the release notes which follow for bugs report procedures.

Non-serious

Tristrip and polygonal output forms are not always being optimal in minimising triangle or vertex counts.

Release notes

This software was copyright©1997-1999, Advanced Interfaces Group, Department of Computer Science, University of Mancheste R. This software are free for non-commercial use. It May is copied, modified, and redistributed provided that the copyright notices which appear within the library source F Iles is preserved on all copies. The intellectual property rights of the algorithms used reside with the University of Manchester advanced Interfaces Group .

Software, in whole or in part, on support for any commercial product without the express consent of TH E author.

There is no warranty or other guarantee of fitness of this software for any purpose. It is provided solely "as is". Although no direct support for the use of this software would be given, bug reports could be sent to [email protected].

See the VERSIONS. TXT file for a revision the history.

References

[1]

Vatti, B.R, "A Generic solution to Polygon Clipping", Communications of the ACM, (7), July 1992, pp. 56-63. (Please don't contact us asking for copies of this paper; We is regrettably unable to supply them.)

Back to the GPC home page.

Algorithm A General Polygon Clipping Library