Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GD::Polyline(3)	      User Contributed Perl Documentation      GD::Polyline(3)

NAME
       GD::Polyline - Polyline object and Polygon utilities (including
       splines)	for use	with GD

SYNOPSIS
	       use GD;
	       use GD::Polyline;

	       # create	an image
	       $image =	new GD::Image (500,300);
	       $white  = $image->colorAllocate(255,255,255);
	       $black  = $image->colorAllocate(	 0,  0,	 0);
	       $red    = $image->colorAllocate(255,  0,	 0);

	       # create	a new polyline
	       $polyline = new GD::Polyline;

	       # add some points
	       $polyline->addPt(  0,  0);
	       $polyline->addPt(  0,100);
	       $polyline->addPt( 50,125);
	       $polyline->addPt(100,  0);

	       # polylines can use polygon methods (and	vice versa)
	       $polyline->offset(200,100);

	       # rotate	60 degrees, about the centroid
	       $polyline->rotate(3.14159/3, $polyline->centroid());

	       # scale about the centroid
	       $polyline->scale(1.5, 2,	$polyline->centroid());

	       # draw the polyline
	       $image->polydraw($polyline,$black);

	       # create	a spline, which	is also	a polyine
	       $spline = $polyline->addControlPoints->toSpline;
	       $image->polydraw($spline,$red);

	       # output	the png
	       binmode STDOUT;
	       print $image->png;

DESCRIPTION
       Polyline.pm extends the GD module by allowing you to create polylines.
       Think of	a polyline as "an open polygon", that is, the last vertex is
       not connected to	the first vertex (unless you expressly add the same
       value as	both points).

       For the remainder of this doc, "polyline" will refer to a GD::Polyline,
       "polygon" will refer to a GD::Polygon that is not a polyline, and
       "polything" and "$poly" may be either.

       The big feature added to	GD by this module is the means to create
       splines,	which are approximations to curves.

The Polyline Object
       GD::Polyline defines the	following class:

       "GD::Polyline"
	    A polyline object, used for	storing	lists of vertices prior	to
	    rendering a	polyline into an image.

       "new"
	    "GD::Polyline->new"	class method

	    Create an empty polyline with no vertices.

		    $polyline =	new GD::Polyline;

		    $polyline->addPt(  0,  0);
		    $polyline->addPt(  0,100);
		    $polyline->addPt( 50,100);
		    $polyline->addPt(100,  0);

		    $image->polydraw($polyline,$black);

	    In fact GD::Polyline is a subclass of GD::Polygon, so all polygon
	    methods (such as offset and	transform) may be used on polylines.
	    Some new methods have thus been added to GD::Polygon (such as
	    rotate) and	a few updated/modified/enhanced	(such as scale)	in
	    this module.  See section "New or Updated GD::Polygon Methods" for
	    more info.

       Note that this module is	very "young" and should	be considered subject
       to change in future releases, and/or possibly folded in to the existing
       polygon object and/or GD	module.

Updated	Polygon	Methods
       The following methods (defined in GD.pm)	are OVERRIDDEN if you use this
       module.

       All effort has been made	to provide 100%	backward compatibility,	but if
       you can confirm that has	not been achieved, please consider that	a bug
       and let the the author of Polyline.pm know.

       "scale"
	    "$poly->scale($sx, $sy, $cx, $cy)" object method --	UPDATE to
	    GD::Polygon::scale

	    Scale a polything in along x-axis by $sx and along the y-axis by
	    $sy, about centery point ($cx, $cy).

	    Center point ($cx, $cy) is optional	-- if these are	omitted, the
	    function will scale	about the origin.

	    To flip a polything, use a scale factor of -1.  For	example, to
	    flip the polything top to bottom about line	y = 100, use:

		    $poly->scale(1, -1,	0, 100);

New Polygon Methods
       The following methods are added to GD::Polygon, and thus	can be used by
       polygons	and polylines.

       Don't forget: a polyline	is a GD::Polygon, so GD::Polygon methods like
       offset()	can be used, and they can be used in GD::Image methods like
       filledPolygon().

       "rotate"
	    "$poly->rotate($angle, $cx,	$cy)" object method

	    Rotate a polything through $angle (clockwise, in radians) about
	    center point ($cx, $cy).

	    Center point ($cx, $cy) is optional	-- if these are	omitted, the
	    function will rotate about the origin

	    In this function and other angle-oriented functions	in
	    GD::Polyline, positive $angle corresponds to clockwise rotation.
	    This is opposite of	the usual Cartesian sense, but that is because
	    the	raster is opposite of the usual	Cartesian sense	in that	the
	    y-axis goes	"down".

       "centroid"
	    "($cx, $cy)	= $poly->centroid($scale)" object method

	    Calculate and return ($cx, $cy), the centroid of the vertices of
	    the	polything.  For	example, to rotate something 180 degrees about
	    it's centroid:

		    $poly->rotate(3.14159, $poly->centroid());

	    $scale is optional;	if supplied, $cx and $cy are multiplied	by
	    $scale before returning.  The main use of this is to shift an
	    polything to the origin like this:

		    $poly->offset($poly->centroid(-1));

       "segLength"
	    "@segLengths = $poly->segLength()" object method

	    In array context, returns an array the lengths of the segments in
	    the	polything.  Segment n is the segment from vertex n to vertex
	    n+1.  Polygons have	as many	segments as vertices; polylines	have
	    one	fewer.

	    In a scalar	context, returns the sum of the	array that would have
	    been returned in the array context.

       "segAngle"
	    "@segAngles	= $poly->segAngle()" object method

	    Returns an array the angles	of each	segment	from the x-axis.
	    Segment n is the segment from vertex n to vertex n+1.  Polygons
	    have as many segments as vertices; polylines have one fewer.

	    Returned angles will be on the interval 0 <= $angle	< 2 * pi and
	    angles increase in a clockwise direction.

       "vertexAngle"
	    "@vertexAngles = $poly->vertexAngle()" object method

	    Returns an array of	the angles between the segment into and	out of
	    each vertex.  For polylines, the vertex angle at vertex 0 and the
	    last vertex	are not	defined; however $vertexAngle[0] will be undef
	    so that $vertexAngle[1] will correspond to vertex 1.

	    Returned angles will be on the interval 0 <= $angle	< 2 * pi and
	    angles increase in a clockwise direction.

	    Note that this calculation does not	attempt	to figure out the
	    "interior" angle with respect to "inside" or "outside" the
	    polygon, but rather, just the angle	between	the adjacent segments
	    in a clockwise sense.  Thus	a polygon with all right angles	will
	    have vertex	angles of either pi/2 or 3*pi/2, depending on the way
	    the	polygon	was "wound".

       "toSpline"
	    "$poly->toSpline()"	object method _	factory	method

	    Create a new polything which is a reasonably smooth	curve using
	    cubic spline algorithms, often referred to as Bezier curves.  The
	    "source" polything is called the "control polything".  If it is a
	    polyline, the control polyline must	have 4,	7, 10, or some number
	    of vertices	of equal to 3n+1.  If it is a polygon, the control
	    polygon must have 3, 6, 9, or some number of vertices of equal to
	    3n.

		    $spline = $poly->toSpline();
		    $image->polydraw($spline,$red);

	    In brief, groups of	four points from the control polyline are
	    considered "control	points"	for a given portion of the spline: the
	    first and fourth are "anchor points", and the spline passes
	    through them; the second and third are "director points".  The
	    spline does	not pass through director points, however the spline
	    is tangent to the line segment from	anchor point to	adjacent
	    director point.

	    The	next portion of	the spline reuses the previous portion's last
	    anchor point.  The spline will have	a cusp (non-continuous slope)
	    at an anchor point,	unless the anchor points and its adjacent
	    director point are colinear.

	    In the current implementation, toSpline() return a fixed number of
	    segments in	the returned polyline per set-of-four control points.
	    In the future, this	and other parameters of	the algorithm may be
	    configurable.

       "addControlPoints"
	    "$polyline->addControlPoints()" object method _ factory method

	    So you say:	"OK.  Splines sound cool.  But how can I get my	anchor
	    points and its adjacent director point to be colinear so that I
	    have a nice	smooth curves from my polyline?"  Relax!  For The
	    Lazy: addControlPoints() to	the rescue.

	    addControlPoints() returns a polyline that can serve as the
	    control polyline for toSpline(), which returns another polyline
	    which is the spline.  Is your head spinning	yet?  Think of it this
	    way:

	    +	 If you	have a polyline, and you have already put your control
		 points	where you want them, call toSpline() directly.
		 Remember, only	every third vertex will	be "on"	the spline.

		 You get something that	looks like the spline "inscribed"
		 inside	the control polyline.

	    +	 If you	have a polyline, and you want all of its vertices on
		 the resulting spline, call addControlPoints() and then
		 toSpline():

			 $control = $polyline->addControlPoints();
			 $spline  = $control->toSpline();
			 $image->polyline($spline,$red);

		 You get something that	looks like the control polyline
		 "inscribed" inside the	spline.

	    Adding "good" control points is subjective;	this particular
	    algorithm reveals its author's tastes.  In the future, you may be
	    able to alter the taste slightly via parameters to the algorithm.
	    For	The Hubristic: please build a better one!

	    And	for The	Impatient: note	that addControlPoints()	returns	a
	    polyline, so you can pile up the call like this, if	you'd like:

		    $image->polyline($polyline->addControlPoints()->toSpline(),$mauve);

New GD::Image Methods
       "polyline"
	    "$image->polyline(polyline,color)" object method

		    $image->polyline($polyline,$black)

	    This draws a polyline with the specified color.  Both real color
	    indexes and	the special colors gdBrushed, gdStyled and
	    gdStyledBrushed can	be specified.

	    Neither the	polyline() method or the polygon() method are very
	    picky: you can call	either method with either a GD::Polygon	or a
	    GD::Polyline.  The method determines if the	shape is "closed" or
	    "open" as drawn, not the object type.

       "polydraw"
	    "$image->polydraw(polything,color)"	object method

		    $image->polydraw($poly,$black)

	    This method	draws the polything as expected	(polygons are closed,
	    polylines are open)	by simply checking the object type and calling
	    either $image->polygon() or	$image->polyline().

Examples
       Please see file "polyline-examples.pl" that is included with the
       distribution.

See Also
       For more	info on	Bezier splines,	see
       http://www.webreference.com/dlab/9902/bezier.html.

Future Features
       On the drawing board are	additional features such as:

	       - polygon winding algorithms (to	determine if a point is	"inside" or "outside" the polygon)

	       - new polygon from bounding box

	       - find bounding polygon (tightest fitting simple	convex polygon for a given set of vertices)

	       - addPts() method to add	many points at once

	       - clone() method	for polygon

	       - functions to interwork	GD with	SVG

       Please provide input on other possible features you'd like to see.

Author
       This module has been written by Daniel J. Harasty.  Please send
       questions, comments, complaints,	and kudos to him at harasty@cpan.org.

       Thanks to Lincoln Stein for input and patience with me and this,	my
       first CPAN contribution.

Copyright Information
       The Polyline.pm module is copyright 2002, Daniel	J. Harasty.  It	is
       distributed under the same terms	as Perl	itself.	 See the "Artistic
       License"	in the Perl source code	distribution for licensing terms.

       The latest version of Polyline.pm is available at your favorite CPAN
       repository and/or along with GD.pm by Lincoln D.	Stein at
       http://stein.cshl.org/WWW/software/GD.

perl v5.32.1			  2019-01-10		       GD::Polyline(3)

NAME | SYNOPSIS | DESCRIPTION | The Polyline Object | Updated Polygon Methods | New Polygon Methods | New GD::Image Methods | Examples | See Also | Future Features | Author | Copyright Information

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=GD::Polyline&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help