1GD::Polyline(3)       User Contributed Perl Documentation      GD::Polyline(3)
2
3
4

NAME

6       GD::Polyline - Polyline object and Polygon utilities (including
7       splines) for use with GD
8

SYNOPSIS

10               use GD;
11               use GD::Polyline;
12
13               # create an image
14               $image = new GD::Image (500,300);
15               $white  = $image->colorAllocate(255,255,255);
16               $black  = $image->colorAllocate(  0,  0,  0);
17               $red    = $image->colorAllocate(255,  0,  0);
18
19               # create a new polyline
20               $polyline = new GD::Polyline;
21
22               # add some points
23               $polyline->addPt(  0,  0);
24               $polyline->addPt(  0,100);
25               $polyline->addPt( 50,125);
26               $polyline->addPt(100,  0);
27
28               # polylines can use polygon methods (and vice versa)
29               $polyline->offset(200,100);
30
31               # rotate 60 degrees, about the centroid
32               $polyline->rotate(3.14159/3, $polyline->centroid());
33
34               # scale about the centroid
35               $polyline->scale(1.5, 2, $polyline->centroid());
36
37               # draw the polyline
38               $image->polydraw($polyline,$black);
39
40               # create a spline, which is also a polyine
41               $spline = $polyline->addControlPoints->toSpline;
42               $image->polydraw($spline,$red);
43
44               # output the png
45               binmode STDOUT;
46               print $image->png;
47

DESCRIPTION

49       Polyline.pm extends the GD module by allowing you to create polylines.
50       Think of a polyline as "an open polygon", that is, the last vertex is
51       not connected to the first vertex (unless you expressly add the same
52       value as both points).
53
54       For the remainder of this doc, "polyline" will refer to a GD::Polyline,
55       "polygon" will refer to a GD::Polygon that is not a polyline, and
56       "polything" and "$poly" may be either.
57
58       The big feature added to GD by this module is the means to create
59       splines, which are approximations to curves.
60

The Polyline Object

62       GD::Polyline defines the following class:
63
64       "GD::Polyline"
65            A polyline object, used for storing lists of vertices prior to
66            rendering a polyline into an image.
67
68       "new"
69            "GD::Polyline->new" class method
70
71            Create an empty polyline with no vertices.
72
73                    $polyline = new GD::Polyline;
74
75                    $polyline->addPt(  0,  0);
76                    $polyline->addPt(  0,100);
77                    $polyline->addPt( 50,100);
78                    $polyline->addPt(100,  0);
79
80                    $image->polydraw($polyline,$black);
81
82            In fact GD::Polyline is a subclass of GD::Polygon, so all polygon
83            methods (such as offset and transform) may be used on polylines.
84            Some new methods have thus been added to GD::Polygon (such as
85            rotate) and a few updated/modified/enhanced (such as scale) in
86            this module.  See section "New or Updated GD::Polygon Methods" for
87            more info.
88
89       Note that this module is very "young" and should be considered subject
90       to change in future releases, and/or possibly folded in to the existing
91       polygon object and/or GD module.
92

Updated Polygon Methods

94       The following methods (defined in GD.pm) are OVERRIDDEN if you use this
95       module.
96
97       All effort has been made to provide 100% backward compatibility, but if
98       you can confirm that has not been achieved, please consider that a bug
99       and let the the author of Polyline.pm know.
100
101       "scale"
102            "$poly->scale($sx, $sy, $cx, $cy)" object method -- UPDATE to
103            GD::Polygon::scale
104
105            Scale a polything in along x-axis by $sx and along the y-axis by
106            $sy, about centery point ($cx, $cy).
107
108            Center point ($cx, $cy) is optional -- if these are omitted, the
109            function will scale about the origin.
110
111            To flip a polything, use a scale factor of -1.  For example, to
112            flip the polything top to bottom about line y = 100, use:
113
114                    $poly->scale(1, -1, 0, 100);
115

New Polygon Methods

117       The following methods are added to GD::Polygon, and thus can be used by
118       polygons and polylines.
119
120       Don't forget: a polyline is a GD::Polygon, so GD::Polygon methods like
121       offset() can be used, and they can be used in GD::Image methods like
122       filledPolygon().
123
124       "rotate"
125            "$poly->rotate($angle, $cx, $cy)" object method
126
127            Rotate a polything through $angle (clockwise, in radians) about
128            center point ($cx, $cy).
129
130            Center point ($cx, $cy) is optional -- if these are omitted, the
131            function will rotate about the origin
132
133            In this function and other angle-oriented functions in
134            GD::Polyline, positive $angle corrensponds to clockwise rotation.
135            This is opposite of the usual Cartesian sense, but that is because
136            the raster is opposite of the usual Cartesian sense in that the
137            y-axis goes "down".
138
139       "centroid"
140            "($cx, $cy) = $poly->centroid($scale)" object method
141
142            Calculate and return ($cx, $cy), the centroid of the vertices of
143            the polything.  For example, to rotate something 180 degrees about
144            it's centroid:
145
146                    $poly->rotate(3.14159, $poly->centroid());
147
148            $scale is optional; if supplied, $cx and $cy are multiplied by
149            $scale before returning.  The main use of this is to shift an
150            polything to the origin like this:
151
152                    $poly->offset($poly->centroid(-1));
153
154       "segLength"
155            "@segLengths = $poly->segLength()" object method
156
157            In array context, returns an array the lengths of the segments in
158            the polything.  Segment n is the segment from vertex n to vertex
159            n+1.  Polygons have as many segments as vertices; polylines have
160            one fewer.
161
162            In a scalar context, returns the sum of the array that would have
163            been returned in the array context.
164
165       "segAngle"
166            "@segAngles = $poly->segAngle()" object method
167
168            Returns an array the angles of each segment from the x-axis.
169            Segment n is the segment from vertex n to vertex n+1.  Polygons
170            have as many segments as vertices; polylines have one fewer.
171
172            Returned angles will be on the interval 0 <= $angle < 2 * pi and
173            angles increase in a clockwise direction.
174
175       "vertexAngle"
176            "@vertexAngles = $poly->vertexAngle()" object method
177
178            Returns an array of the angles between the segment into and out of
179            each vertex.  For polylines, the vertex angle at vertex 0 and the
180            last vertex are not defined; however $vertexAngle[0] will be undef
181            so that $vertexAngle[1] will correspond to vertex 1.
182
183            Returned angles will be on the interval 0 <= $angle < 2 * pi and
184            angles increase in a clockwise direction.
185
186            Note that this calculation does not attempt to figure out the
187            "interior" angle with respect to "inside" or "outside" the
188            polygon, but rather, just the angle between the adjacent segments
189            in a clockwise sense.  Thus a polygon with all right angles will
190            have vertex angles of either pi/2 or 3*pi/2, depending on the way
191            the polygon was "wound".
192
193       "toSpline"
194            "$poly->toSpline()" object method & factory method
195
196            Create a new polything which is a reasonably smooth curve using
197            cubic spline algorithms, often referred to as Bezier curves.  The
198            "source" polything is called the "control polything".  If it is a
199            polyline, the control polyline must have 4, 7, 10, or some number
200            of vertices of equal to 3n+1.  If it is a polygon, the control
201            polygon must have 3, 6, 9, or some number of vertices of equal to
202            3n.
203
204                    $spline = $poly->toSpline();
205                    $image->polydraw($spline,$red);
206
207            In brief, groups of four points from the control polyline are
208            considered "control points" for a given portion of the spline: the
209            first and fourth are "anchor points", and the spline passes
210            through them; the second and third are "director points".  The
211            spline does not pass through director points, however the spline
212            is tangent to the line segment from anchor point to adjacent
213            director point.
214
215            The next portion of the spline reuses the previous portion's last
216            anchor point.  The spline will have a cusp (non-continuous slope)
217            at an anchor point, unless the anchor points and its adjacent
218            director point are colinear.
219
220            In the current implementation, toSpline() return a fixed number of
221            segments in the returned polyline per set-of-four control points.
222            In the future, this and other parameters of the algorithm may be
223            configurable.
224
225       "addControlPoints"
226            "$polyline->addControlPoints()" object method & factory method
227
228            So you say: "OK.  Splines sound cool.  But how can I get my anchor
229            points and its adjacent director point to be colinear so that I
230            have a nice smooth curves from my polyline?"  Relax!  For The
231            Lazy: addControlPoints() to the rescue.
232
233            addControlPoints() returns a polyline that can serve as the
234            control polyline for toSpline(), which returns another polyline
235            which is the spline.  Is your head spinning yet?  Think of it this
236            way:
237
238            +    If you have a polyline, and you have already put your control
239                 points where you want them, call toSpline() directly.
240                 Remember, only every third vertex will be "on" the spline.
241
242                 You get something that looks like the spline "inscribed"
243                 inside the control polyline.
244
245            +    If you have a polyline, and you want all of its vertices on
246                 the resulting spline, call addControlPoints() and then
247                 toSpline():
248
249                         $control = $polyline->addControlPoints();
250                         $spline  = $control->toSpline();
251                         $image->polyline($spline,$red);
252
253                 You get something that looks like the control polyline
254                 "inscribed" inside the spline.
255
256            Adding "good" control points is subjective; this particular
257            algorithm reveals its author's tastes.  In the future, you may be
258            able to alter the taste slightly via parameters to the algorithm.
259            For The Hubristic: please build a better one!
260
261            And for The Impatient: note that addControlPoints() returns a
262            polyline, so you can pile up the the call like this, if you'd
263            like:
264
265                    $image->polyline($polyline->addControlPoints()->toSpline(),$mauve);
266

New GD::Image Methods

268       "polyline"
269            "$image->polyline(polyline,color)" object method
270
271                    $image->polyline($polyline,$black)
272
273            This draws a polyline with the specified color.  Both real color
274            indexes and the special colors gdBrushed, gdStyled and
275            gdStyledBrushed can be specified.
276
277            Neither the polyline() method or the polygon() method are very
278            picky: you can call either method with either a GD::Polygon or a
279            GD::Polyline.  The method determines if the shape is "closed" or
280            "open" as drawn, not the object type.
281
282       "polydraw"
283            "$image->polydraw(polything,color)" object method
284
285                    $image->polydraw($poly,$black)
286
287            This method draws the polything as expected (polygons are closed,
288            polylines are open) by simply checking the object type and calling
289            either $image->polygon() or $image->polyline().
290

Examples

292       Please see file "polyline-examples.pl" that is included with the
293       distribution.
294

See Also

296       For more info on Bezier splines, see
297       http://www.webreference.com/dlab/9902/bezier.html.
298

Future Features

300       On the drawing board are additional features such as:
301
302               - polygon winding algorithms (to determine if a point is "inside" or "outside" the polygon)
303
304               - new polygon from bounding box
305
306               - find bounding polygon (tightest fitting simple convex polygon for a given set of vertices)
307
308               - addPts() method to add many points at once
309
310               - clone() method for polygon
311
312               - functions to interwork GD with SVG
313
314       Please provide input on other possible features you'd like to see.
315

Author

317       This module has been written by Daniel J. Harasty.  Please send
318       questions, comments, complaints, and kudos to him at harasty@cpan.org.
319
320       Thanks to Lincoln Stein for input and patience with me and this, my
321       first CPAN contribution.
322
324       The Polyline.pm module is copyright 2002, Daniel J. Harasty.  It is
325       distributed under the same terms as Perl itself.  See the "Artistic
326       License" in the Perl source code distribution for licensing terms.
327
328       The latest version of Polyline.pm is available at your favorite CPAN
329       repository and/or along with GD.pm by Lincoln D. Stein at
330       http://stein.cshl.org/WWW/software/GD.
331
332
333
334perl v5.12.0                      2006-08-23                   GD::Polyline(3)
Impressum