NAME

SVGPDF::Contrib::Bogen - Circular and elliptic curves

SYNOPSIS

$context->bogen( $x1,$y1, $x2,$y2, $r, @opts);
$context->bogen_ellip( $x1,$y1, $x2,$y2, $rx,$ry, @opts);

DESCRIPTION

This package contains functions to draw circular and elliptic curves.

This code is developed by Phil Perry, based on old PDF::API2 code and friendly contributed to the SVGPDF project.

$context->bogen_ellip($x1,$y1, $x2,$y2, $rx,$ry, @opts)

This is a variant of the original bogen() call from PDF::Builder, which drew a segment (arc) of a circle, which was adapted here by Phil Perry to draw an elliptical arc.

(German for bow, as in a segment (arc) of an ellipse), this is a segment of an ellipse defined by the intersection of two ellipses of given x and y radii, with the two intersection points as inputs. There are four possible resulting arcs, which can be selected with opts large and dir.

This extends the path along an arc of an ellipse of the specified x and y radii between [$x1,$y1] to [$x2,$y2]. The current position is then set to the endpoint of the arc ([$x2,$y2]).

Options (@opts)

'move' => move_flag

Set move to a true value if this arc is the beginning of a new path instead of the continuation of an existing path. Note that the default (move => false) is not a straight line to P1 and then the arc, but a blending into the curve from the current point. It will often not pass through P1! Set to true, there will be a jump (move) from the current point to P1, to where the arc will start.

'large' => larger_arc_flag

Set large to a true value to draw the larger ("outer") arc between the two points, instead of the smaller one. Both arcs are drawn clockwise from P1 to P2. The default value of false draws the smaller arc.

'dir' => draw_direction

Set dir to a true value to draw the mirror image of the specified arc (flip it over, so that its center point is on the other side of the line connecting the two points). Both arcs (small or large) are drawn counter-clockwise from P1 to P2. The default (false) draws clockwise arcs.

'rotate' => axis_rotation

A non-zero value is the degrees to rotate the axes of the ellipse (in a counter-clockwise manner). For example, 'rotate'=>45 will have the ellipse's +X axis pointing "northeast" and the +Y axis pointing "northwest". The default value is 0 (no rotation).

'full' => color_spec

If given (no default), draw the full ellipse (not just the arc) in this color, with a dot at its center. This may be useful for diagnostic and development purposes, to show the ellipse from which the arc is obtained.

Note:

If the given radii $rx and $ry are too small for the points P1 and P2 to fit on the specified ellipse, they will be proportionately scaled up untilthe points fit on the ellipse. This is a silent error, as due to rounding, given points (even if correct) may not exactly fit on the ellipse. Further note that the algorithm only enlarges the radii until a sweep of 180 degrees is obtained, so it is possible that the ellipse will be smaller than your intended one!

$content->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger, $reverse)

$content->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger)

$content->bogen($x1,$y1, $x2,$y2, $radius, $move)

$content->bogen($x1,$y1, $x2,$y2, $radius)

(bogen is German for bow, as in a segment (arc) of a circle. This is a segment of a circle defined by the intersection of two circles of a given radius, with the two intersection points as inputs. There are four possible resulting arcs, which can be selected with $larger and $reverse.)

This extends the path along an arc of a circle of the specified radius between [$x1,$y1] to [$x2,$y2]. The current position is then set to the endpoint of the arc ([$x2,$y2]).

Set $move to a true value if this arc is the beginning of a new path instead of the continuation of an existing path. Note that the default ($move = false) is not a straight line to P1 and then the arc, but a blending into the curve from the current point. It will often not pass through P1!

Set $larger to a true value to draw the larger ("outer") arc between the two points, instead of the smaller one. Both arcs are drawn clockwise from P1 to P2. The default value of false draws the smaller arc. Note that the "other" circle's larger arc is used (the center point is "flipped" across the line between P1 and P2), rather than using the "remainder" of the smaller arc's circle (which would necessitate reversing the direction of travel along the arc -- see $reverse).

Set $reverse to a true value to draw the mirror image of the specified arc (flip it over, so that its center point is on the other side of the line connecting the two points). Both arcs are drawn counter-clockwise from P1 to P2. The default (false) draws clockwise arcs. An arc is always drawn from P1 to P2; the direction (clockwise or counter-clockwise) may be chosen.

The $radius value cannot be smaller than half the distance from [$x1,$y1] to [$x2,$y2]. If it is too small, the radius will be set to half the distance between the points (resulting in an arc that is a semicircle). This is a silent error.