Math::...Spiral(3pm)

💖 Math::PlanePath::HexSpiral 💖

okay so bestie, welcome to Math::PlanePath::HexSpiral — it's giving integer points around a hexagonal spiral and honestly? iconic. this is a Perl manpage from the User Contributed Perl Documentation collection and i'm about to make it make sense. 🐝✨

---

🌀 SYNOPSIS 🌀

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

like, that's it. that's the whole vibe. slay. 💅

---

🌸 DESCRIPTION 🌸

so this path makes a hexagonal spiral, right? but the points get spread out horizontally so they fit all nice and pretty on a square grid. look at her:

            28 -- 27 -- 26 -- 25                  3
           /                    \
         29    13 -- 12 -- 11    24               2
        /     /              \     \
      30    14     4 --- 3    10    23            1
     /     /     /         \     \    \
   31    15     5     1 --- 2     9    22    <- Y=0
     \     \     \              /     /
      32    16     6 --- 7 --- 8    21           -1
        \     \                    /
         33    17 -- 18 -- 19 -- 20              -2
           \
            34 -- 35 ...                         -3

    ^  ^  ^  ^  ^  ^  ^  ^  ^  ^  ^  ^  ^
   -6 -5 -4 -3 -2 -1 X=0 1  2  3  4  5  6

each horizontal gap is 2, so for instance n=1 is at X=0,Y=0 and then n=2 is at X=2,Y=0. the diagonals are just 1 across, so n=3 is at X=1,Y=1. every alternate row is offset from the one above or below it. the result? a triangular lattice, per "Triangular Lattice" in Math::PlanePath. periodt. 🔺

the octagonal numbers 8,21,40,65, etc — that's 3*k^2-2*k — fall on a horizontal straight line at Y=-1. in general straight lines are 3*k^2 + b*k + c. a plain 3*k^2 goes diagonally up to the left, then b is a 1/6 turn anti-clockwise, or clockwise if negative. so b=1 goes horizontally to the left, b=2 diagonally down to the left, b=3 diagonally down to the right, etc. math is so main character fr fr. 😌

---

🎀 Wider 🎀

there's an optional "wider" parameter that makes the path wider, stretched along the top and bottom horizontals. no cap. like:

$path = Math::PlanePath::HexSpiral->new (wider => 2);

gives you:

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

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

so the centre horizontal from N=1 gets extended by "wider" many extra places, and then the path loops around that shape. the starting point N=1 is shifted to the left by wider many places, to keep the spiral centred on the origin X=0,Y=0. each horizontal gap is still 2, don't worry. 🫶

each loop is still 6 longer than the previous one, since the widening is basically a constant amount added into each loop. consistent queen. 👑

---

🌈 N Start 🌈

the default is to number points starting N=1 as shown above. an optional "n_start" can give a different start with the same shape etc. for example to start at 0:

n_start => 0

         27    26    25    24                    3
      28    12    11    10    23                 2
   29    13     3     2     9    22              1
30    14     4     0     1     8    21      <- Y=0
   31    15     5     6     7    20   ...       -1
      32    16    17    18    19    38          -2
         33    34    35    36    37             -3
                   ^
-6 -5 -4 -3 -2 -1 X=0 1  2  3  4  5  6

in this numbering the X axis N=0,1,8,21, etc is the octagonal numbers 3*X*(X+1). cute. 🌸

---

✨ FUNCTIONS ✨

see "FUNCTIONS" in Math::PlanePath for behaviour common to all path classes. (the shared lore, iykyk.)

• $path = Math::PlanePath::HexSpiral->new ()
• $path = Math::PlanePath::HexSpiral->new (wider => $w) — create and return a new hex spiral object. there's an optional "wider" parameter that widens the path, and it defaults to 0, which is no widening at all.
• ($x,$y) = $path->n_to_xy ($n) — return the X,Y coordinates of point number $n on the path.

for "$n < 1" the return is an empty list, because it's considered that the path starts at 1. sorry bestie, no zero zone here. 🙈

• $n = $path->xy_to_n ($x,$y) — return the point number for coordinates "$x,$y". $x and $y are each rounded to the nearest integer, which has the effect of treating each $n in the path as a square of side 1.

only every second square in the plane has an N, being those where X,Y are both odd or both even. if "$x,$y" is a position without an N — i.e. one of X,Y odd and the other even — then the return is "undef". it's giving ✨ nothing ✨.

---

🔍 OEIS 🔍

entries in Sloane's Online Encyclopedia of Integer Sequences related to this path include:

<http://oeis.org/A056105> (etc)

A328818    X coordinate
A307012    Y coordinate
A307011    (X-Y)/2
A307013    (X+Y)/2

A056105    N on X axis
A056106    N on X=Y diagonal
A056107    N on North-West diagonal
A056108    N on negative X axis
A056109    N on South-West diagonal
A003215    N on South-East diagonal

A063178    total sum N previous row or diagonal
A135711    boundary length of N hexagons
A135708    grid sticks of N hexagons

n_start=0
  A001399    N positions of turns (extra initial 1)
  A000567    N on X axis, octagonal numbers
  A049451    N on X negative axis
  A049450    N on X=Y diagonal north-east
  A033428    N on north-west diagonal, 3*k^2
  A045944    N on south-west diagonal, octagonal numbers second kind
  A063436    N on WSW slope dX=-3,dY=-1
  A028896    N on south-east diagonal

not the whole catalogue, but honestly? a mood. 📚💜

---

👀 SEE ALSO 👀

Math::PlanePath, Math::PlanePath::HexSpiralSkewed, Math::PlanePath::HexArms, Math::PlanePath::TriangleSpiral, Math::PlanePath::TriangularHypot

(the friend group. go say hi. 🫂)

---

🏠 HOME PAGE 🏠

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

come hang out, it's cozy. 🏡

---

📜 LICENSE 📜

Copyright 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 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/>. ⚖️

fr fr read the license, bestie — it's the legal slay. 🩷

---

and that's the whole page, mwah. 💋 this beauty ships with perl v5.32.0, dated 2021-01-23 — vintage but still serving. 💅✨🦋