NAME

       Math::NumSeq::PlanePathTurn -- turn sequence from PlanePath module

SYNOPSIS

        use Math::NumSeq::PlanePathTurn;
        my $seq = Math::NumSeq::PlanePathTurn->new (planepath => 'DragonCurve',
                                                    turn_type => 'Left');
        my ($i, $value) = $seq->next;

DESCRIPTION

       This is a tie-in to present turns from a "Math::PlanePath" module in the form of a NumSeq
       sequence.

       The "turn_type" choices are

           "Left"     1=left  0=right or straight
           "Right"    1=right 0=left or straight
           "LSR"      1=left  0=straight -1=right
           "SLR"      0=straight 1=left  2=right
           "SRL"      0=straight 1=right 2=left

       In each case the value at i is the turn which occurs at N=i,

                   i+1
                    ^
                    |
                    |
           i-1 ---> i     turn at i
                          first turn at i = n_start + 1

       For multiple "arms" the turn follows that particular arm so it's i-arms, i, i+arms.  i
       values start "n_start()+arms_count()" so i-arms is "n_start()", the first N on the path.
       A single arm path beginning N=0 has its first turn at i=1.

       For "LSR", "SLR" and "SRL", straight means either straight ahead or 180-degree reversal,
       ie. the direction N to N+1 is along the same line as N-1 to N was.

       "Left" means to the left side of the N-1 to N line, not straight or right.  Similarly
       "Right" means to the right side of the N-1 to N line, not straight or left.

FUNCTIONS

       See "FUNCTIONS" in Math::NumSeq for behaviour common to all sequence classes.

       "$seq = Math::NumSeq::PlanePathTurn->new (key=>value,...)"
           Create and return a new sequence object.  The options are

               planepath          string, name of a PlanePath module
               planepath_object   PlanePath object
               turn_type          string, as described above

           "planepath" can be either the module part such as "SquareSpiral" or a full class name
           "Math::PlanePath::SquareSpiral".

       "$value = $seq->ith($i)"
           Return the turn at N=$i in the PlanePath.

       "$bool = $seq->pred($value)"
           Return true if $value occurs as a turn.  Often this is merely the possible turn values
           1,0,-1, etc, but some spiral paths for example only go left or straight in which case
           only 1 and 0 occur and "pred()" reflects that.

       "$i = $seq->i_start()"
           Return the first index $i in the sequence.  This is the position "rewind()" returns
           to.

           This is "$path->n_start() - $path->arms_count()" from the PlanePath object.

FORMULAS

   Turn Left or Right
       A turn left or right is identified by considering the dX,dY at N-1 and at N.

           N+1      *
                    |   dx2,dy2
                    |
                    |
                    |
           N        *
                   /   dx1,dy1
                  /
                 /
           N-1  *

       With the two vectors dx1,dy1 and dx2,dy2 at a common origin, if the dx2,dy2 is above the
       dx1,dy1 line then it's a turn to the left, or below is a turn to the right

           dx2,dy2
              *
              |   * dx1,dy1
              |  /
              | /
              |/
              o

       At dx2 the Y value of the dx1,dy1 vector is

           cmpY = dx2 * dy1/dx1           if dx1 != 0

           left if dy2 > cmpY
                   dy2 > dx2 * dy1/dx1
              so   dy2 * dx1 > dx2 * dy1

       This comparison dy2*dx1 > dx2*dy1 works when dx1=0 too, ie. when dx1,dy1 is vertical

           left if dy2 * 0 > dx2 * dy1
                         0 > dx2*dy1
           good, left if dx2 and dy1 opposite signs

       So

           dy2*dx1 > dx2*dy1      left
           dy2*dx1 < dx2*dy1      right
           dy2*dx1 = dx2*dy1      straight, including 180 degree reverse

SEE ALSO

       Math::NumSeq, Math::NumSeq::PlanePathCoord, Math::NumSeq::PlanePathDelta,
       Math::NumSeq::PlanePathN

       Math::NumberCruncher has a "Clockwise()" turn calculator

HOME PAGE

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

LICENSE

       Copyright 2011, 2012, 2013 Kevin Ryde

       This file is part of Math-PlanePath.

       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/>.