Math::...athTurn(3pm)

💖 Math::NumSeq::PlanePathTurn — the manual, but make it make sense 💖

okay so bestie, welcome to Math::NumSeq::PlanePathTurn(3pm), straight outta the User Contributed Perl Documentation shelf. this is the lil tie-in that turns the turns of a Math::PlanePath into a NumSeq sequence. yes we're going there. 🌀

---

✨ SYNOPSIS ✨

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

---

🌸 DESCRIPTION 🌸

so basically 💅 this module is a tie-in that presents turns from a Math::PlanePath module in the form of a NumSeq sequence. that's the whole vibe.

the turn_type choices are — pick your fighter:

"Left"         1=left,  0=right or straight
"Right"        1=right, 0=left or straight
"Straight"     1=straight, 0=left or right
"NotStraight"  0=straight, 1=left or right
"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 sequence index i is the turn at N=i, and the diagram is giving what it's giving:

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

for multiple arms in the path, the turn follows that particular arm, so it's looking at locations of N = i-arms to i to i+arms. the i values start at n_start()+arms_count() so that i-arms is n_start(), which is the first N on the path. a single arm path beginning N=0 has its first turn at i=1. slay. 🎀

for Straight, 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. iconic behaviour ngl.

Left means to the left side of the N-1 to N line, so not straight or right. similarly Right means to the right side of the N-1 to N line, so not straight or left. no cap.

---

🦋 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. look at this lil guy:

    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 cross-product 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, final answer bestie:

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, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 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. (fr fr, read the license, it's not a vibe check you can skip 🙈)

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

---

💌 okay that's the whole page bestie, you ate that. this was perl v5.32.0, dated 2021-01-23, and it's giving Math::...athTurn(3pm) energy — go build something gorgeous with your turns 💅✨🦋