Provided by: libmath-planepath-perl_113-1_all bug

NAME

       Math::PlanePath::KochPeaks -- Koch curve peaks

SYNOPSIS

        use Math::PlanePath::KochPeaks;
        my $path = Math::PlanePath::KochPeaks->new;
        my ($x, $y) = $path->n_to_xy (123);

DESCRIPTION

       This path traces out concentric peaks made from integer versions of the self-similar
       "KochCurve" at successively greater replication levels.

                                      29                                 9
                                     /  \
                             27----28    30----31                        8
                               \              /
                    23          26          32          35               7
                   /  \        /              \        /  \
           21----22    24----25                33----34    36----37      6
             \                                                  /
              20                                              38         5
             /                                                  \
           19----18                                        40----39      4
                   \                                      /
                    17                 8                41               3
                   /                 /  \                 \
           15----16           6---- 7     9----10          42----43      2
             \                 \              /                 /
              14                 5     2    11                44         1
             /                 /     /  \     \                 \
           13                 4     1    3     12                45  <- Y=0

                                       ^
           -9 -8 -7 -6 -5 -4 -3 -2 -1 X=0 1  2  3  4  5  6  7  8  9 ...

       The initial figure is the peak N=1,2,3 then for the next level each straight side expands
       to 3x longer with a notch in the middle like N=4 through N=8,

                                         *
                                        / \
             *---*     becomes     *---*   *---*

       The angle is maintained in each replacement so

                                         *
                                        /
                                   *---*
                                    \
               *                     *
              /        becomes      /
             *                     *

       For example the segment N=1 to N=2 becomes N=4 to N=8, or in the next level N=5 to N=6
       becomes N=17 to N=21.

       The X,Y coordinates are arranged as integers on a square grid.  The result is flattened
       triangular segments with diagonals at a 45 degree angle.

       Unlike other triangular grid paths "KochPeaks" uses the "odd" squares, with one of X,Y odd
       and the other even.  This means the rotation formulas etc described in "Triangular
       Lattice" in Math::PlanePath don't apply directly.

   Level Ranges
       Counting the innermost N=1 to N=3 peak as level 0, each peak is

           Nstart = level + (2*4^level + 1)/3
           Nend   = level + (8*4^level + 1)/3
           length = 2*4^level + 1       including endpoints

       For example the outer peak shown above is level 2 starting at Nstart=2+(2*4^2+1)/3=13
       through to Nend=2+(8*4^2+1)/3=45 with length=2*4^2+1=33 inclusive (45-13+1=33).  The X
       width at a given level is the endpoints at

           Xlo = -(3^level)
           Xhi = +(3^level)

       For example the level 2 above runs from Xlo=-9 to Xhi=+9.  The highest Y is the centre
       peak half-way through the level at

           Ypeak = 3^level
           Npeak = level + (5*4^level + 1)/3

       For example the level 2 outer peak above is Ypeak=3^2=9 at N=2+(5*4^2+1)/3=29.  For each
       level the Xlo,Xhi and Ypeak extents grow by a factor of 3.

       The triangular notches in each segment are not big enough to go past the Xlo and Xhi end
       points.  The new triangular part can equal the ends, such as N=6 or N=19, but not go
       beyond.

       In general a segment like N=5 to N=6 which is at the Xlo end will expand to give two such
       segments and two points at the limit in the next level, as for example N=5 to N=6 expands
       to N=19,20 and N=20,21.  So the count of points at Xlo doubles each time,

           CountLo = 2^level
           CountHi = 2^level      same at Xhi

FUNCTIONS

       See "FUNCTIONS" in Math::PlanePath for behaviour common to all path classes.

       "$path = Math::PlanePath::KochPeaks->new ()"
           Create and return a new path object.

       "($x,$y) = $path->n_to_xy ($n)"
           Return the X,Y coordinates of point number $n on the path.  Points begin at 0 and if
           "$n < 0" then the return is an empty list.

           Fractional $n gives an X,Y position along a straight line between the integer
           positions.

FORMULAS

   Rectangle to N Range
       The baseline for a given level is along a diagonal X+Y=3^level or -X+Y=3^level.  The
       containing level can thus be found as

           level = floor(log3( Xmax + Ymax ))
           with Xmax as maximum absolute value, max(abs(X))

       The endpoint in a level is simply 1 before the start of the next, so

            Nlast = Nstart(level+1) - 1
                  = (level+1) + (2*4^(level+1) + 1)/3 - 1
                  = level + (8*4^level + 1)/3

       Using this Nlast is an over-estimate of the N range needed, but an easy calculation.

       It's not too difficult to work down for an exact range, by considering which parts of the
       curve might intersect a rectangle.  But some backtracking and level descending is
       necessary because a rectangle might extend into the empty part of a notch and so be past
       its baseline but not intersect any.  There's plenty of room for a rectangle to intersect
       nothing at all too.

SEE ALSO

       Math::PlanePath, Math::PlanePath::KochCurve, Math::PlanePath::KochSnowflakes,
       Math::PlanePath::PeanoCurve, Math::PlanePath::HilbertCurve

HOME PAGE

       <http://user42.tuxfamily.org/math-planepath/index.html>

LICENSE

       Copyright 2011, 2012, 2013 Kevin Ryde

       Math-PlanePath is free software; you can redistribute it and/or modify it under the terms
       of the GNU General Public License as published by the Free Software Foundation; either
       version 3, or (at your option) any later version.

       Math-PlanePath is distributed in the hope that it will be useful, but WITHOUT ANY
       WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.  See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with Math-
       PlanePath.  If not, see <http://www.gnu.org/licenses/>.