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

NAME

       Math::NumSeq::PlanePathCoord -- sequence of coordinate values from a PlanePath module

SYNOPSIS

        use Math::NumSeq::PlanePathCoord;
        my $seq = Math::NumSeq::PlanePathCoord->new
                    (planepath => 'SquareSpiral',
                     coordinate_type => 'X');
        my ($i, $value) = $seq->next;

DESCRIPTION

       This is a tie-in to make a "NumSeq" sequence giving coordinate values from a
       "Math::PlanePath".  The NumSeq "i" index is the PlanePath "N" value.

       The "coordinate_type" choices are as follows.  Generally they have some sort of geometric
       interpretation or are related to fractions X/Y.

           "X"            X coordinate
           "Y"            Y coordinate
           "Min"          min(X,Y)
           "Max"          max(X,Y)
           "MinAbs"       min(abs(X),abs(Y))
           "MaxAbs"       max(abs(X),abs(Y))
           "Sum"          X+Y sum
           "SumAbs"       abs(X)+abs(Y) sum
           "Product"      X*Y product
           "DiffXY"       X-Y difference
           "DiffYX"       Y-X difference (negative of DiffXY)
           "AbsDiff"      abs(X-Y) difference
           "Radius"       sqrt(X^2+Y^2) radial distance
           "RSquared"     X^2+Y^2 radius squared (norm)
           "TRadius"      sqrt(X^2+3*Y^2) triangular radius
           "TRSquared"    X^2+3*Y^2 triangular radius squared (norm)
           "IntXY"        int(X/Y) division rounded towards zero
           "FracXY"       frac(X/Y) division rounded towards zero
           "BitAnd"       X bitand Y
           "BitOr"        X bitor Y
           "BitXor"       X bitxor Y
           "GCD"          greatest common divisor X,Y
           "Depth"        tree_n_to_depth()
           "SubHeight"    tree_n_to_subheight()
           "NumChildren"  tree_n_num_children()
           "NumSiblings"  not including self
           "RootN"        the N which is the tree root
           "IsLeaf"       0 or 1 whether a leaf node (no children)
           "IsNonLeaf"    0 or 1 whether a non-leaf node (has children)
                            also called an "internal" node

   Min and Max
       "Min" and "Max" are the minimum or maximum of X and Y.  The geometric interpretation of
       "Min" is to select X at any point above the X=Y diagonal or Y for any point below.
       Conversely "Max" is Y above and X below.  On the X=Y diagonal itself X=Y=Min=Max.

           Max=Y      / X=Y diagonal
           Min=X   | /
                   |/
                ---o----
                  /|
                 / |     Max=X
                /        Min=Y

       Min and Max can also be interpreted as counting which gnomon shaped line the X,Y falls on.

           | | | |     Min=gnomon           2 ------------.  Max=gnomon
           | | | |                          1 ----------. |
           | | | |      ...                 0 --------o | |
           | | |  ------ 1                 -1 ------. | | |
           | | o-------- 0                 ...      | | | |
           |  ---------- -1                         | | | |
            ------------ -2                         | | | |

   MinAbs
       MinAbs = min(abs(X),abs(Y)) can be interpreted geometrically as counting gnomons
       successively away from the origin.  This is like Min above, but within the quadrant
       containing X,Y.

                | | | | |          MinAbs=gnomon counted away from the origin
                | | | | |
           2 ---  | | |  ---- 2
           1 -----  |  ------ 1
           0 -------o-------- 0
           1 -----  |  ------ 1
           2 ---  | | |  ---- 2
                | | | | |
                | | | | |

   MaxAbs
       MaxAbs = max(abs(X),abs(Y)) can be interpreted geometrically as counting successive
       squares around the origin.

           +-----------+       MaxAbs=which square
           | +-------+ |
           | | +---+ | |
           | | | o | | |
           | | +---+ | |
           | +-------+ |
           +-----------+

       For example Math::PlanePath::SquareSpiral loops around in squares and so its MaxAbs is
       unchanged until it steps out to the next bigger square.

   Sum and Diff
       "Sum"=X+Y and "DiffXY"=X-Y can be interpreted geometrically as coordinates on 45-degree
       diagonals.  Sum is a measure up along the leading diagonal and DiffXY down an anti-
       diagonal,

           \           /
            \   s=X+Y /
             \       ^\
              \     /  \
               \ | /    v
                \|/      * d=X-Y
              ---o----
                /|\
               / | \
              /  |  \
             /       \
            /         \
           /           \

       Or "Sum" can be thought of as a count of which anti-diagonal stripe contains X,Y, or a
       projection onto the X=Y leading diagonal.

                  Sum
           \     = anti-diag
            2      numbering          / / / /   DiffXY
           \ \       X+Y            -1 0 1 2   = diagonal
            1 2                     / / / /      numbering
           \ \ \                  -1 0 1 2         X-Y
            0 1 2                   / / /
             \ \ \                 0 1 2

   DiffYX
       "DiffYX" = Y-X is simply the negative of DiffXY.  It's included to give positive values on
       paths which are above the X=Y leading diagonal.  For example DiffXY is positive in
       "CoprimeColumns" which is below X=Y, whereas DiffYX is positive in "CellularRule" which is
       above X=Y.

   SumAbs
       "SumAbs" = abs(X)+abs(Y) is similar to the projection described above for Sum or Diff, but
       SumAbs projects onto the central diagonal of whichever quadrant contains the X,Y.  Or
       equivalently it's a numbering of anti-diagonals within that quadrant, so numbering which
       diamond shape the X,Y falls on.

                |
               /|\       SumAbs = which diamond X,Y falls on
              / | \
             /  |  \
           -----o-----
             \  |  /
              \ | /
               \|/
                |

       As an example, the "DiamondSpiral" path loops around on such diamonds, so its SumAbs is
       unchanged until completing a loop and stepping out to the next bigger.

       SumAbs is also a "taxi-cab" or "Manhattan" distance, being how far to travel through a
       square-grid city to get to X,Y.

           SumAbs = taxi-cab distance, by any square-grid travel

           +-----o       +--o          o
           |             |             |
           |          +--+       +-----+
           |          |          |
           *          *          *

       If a path is entirely X>=0,Y>=0 in the first quadrant then Sum and SumAbs are identical.

   AbsDiff
       "AbsDiff" = abs(X-Y) can be interpreted geometrically as the distance away from the X=Y
       diagonal, measured at right-angles to that line.

            d=abs(X-Y)
                  ^    / X=Y line
                   \  /
                    \/
                    /\
                   /  \
                 |/    \
               --o--    \
                /|       v
               /           d=abs(X-Y)

       If a path is entirely below the X=Y line, so X>=Y, then AbsDiff is the same as DiffXY.  Or
       if a path is entirely above the X=Y line, so Y>=X, then AbsDiff is the same as DiffYX.

   Radius and RSquared
       Radius and RSquared are per "$path->n_to_radius()" and "$path->n_to_rsquared()"
       respectively (see "Coordinate Methods" in Math::PlanePath).

   TRadius and TRSquared
       "TRadius" and "TRSquared" are designed for use with points on a triangular lattice as per
       "Triangular Lattice" in Math::PlanePath.  For points on the X axis TRSquared is the same
       as RSquared but off the axis Y is scaled up by factor sqrt(3).

       Most triangular paths use "even" points X==Y mod 2 and for them TRSquared is always even.
       Some triangular paths such as "KochPeaks" have an offset from the origin and use "odd"
       points X!=Y mod 2 and for them TRSquared is odd.

   IntXY and FracXY
       "IntXY" = int(X/Y) is the quotient from X divide Y rounded to an integer towards zero.
       This is like the integer part of a fraction, for example X=9,Y=4 is 9/4 = 2+1/4 so
       IntXY=2.  Negatives are reckoned with the fraction part negated too, so -2 1/4 is -2-1/4
       and thus IntXY=-2.

       Geometrically IntXY gives which wedge of slope 1, 2, 3, etc the point X,Y falls in.  For
       example IntXY is 3 for all points in the wedge 3Y<=X<4Y.

                                      X=Y    X=2Y   X=3Y   X=4Y
           *  -2  *  -1  *   0  |  0   *  1   *  2   *   3  *
              *     *     *     |     *     *     *     *
                 *    *    *    |    *    *    *    *
                    *   *   *   |   *   *   *   *
                       *  *  *  |  *  *  *  *
                          * * * | * * * *
                             ***|****
           ---------------------+----------------------------
                              **|**
                            * * | * *
                          *  *  |  *  *
                        *   *   |   *   *
                      *    *    |    *    *
                2   *  1  *  0  |  0  * -1  *  -2

       "FracXY" is the fraction part which goes with IntXY.  In all cases

           X/Y = IntXY + FracXY

       IntXY rounds towards zero so the remaining FracXY has the same sign as IntXY.

   BitAnd, BitOr, BitXor
       "BitAnd", "BitOr" and "BitXor" treat negative X or negative Y as infinite twos-complement
       1-bits, which means for example X=-1,Y=-2 has X bitand Y = -2.

           ...11111111    X=-1
           ...11111110    Y=-2
           -----------
           ...11111110    X bitand Y = -2

       This twos-complement is per "Math::BigInt" (which has bitwise operations in Perl 5.6 and
       up).  The code here arranges the same on ordinary scalars.

       If X or Y are not integers then the fractional parts are treated bitwise too, but
       currently only to limited precision.

FUNCTIONS

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

       "$seq = Math::NumSeq::PlanePathCoord->new (planepath => $name, coordinate_type => $str)"
           Create and return a new sequence object.  The options are

               planepath          string, name of a PlanePath module
               planepath_object   PlanePath object
               coordinate_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 coordinate at N=$i in the PlanePath.

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

           This is "$path->n_start()" from the PlanePath, since the i numbering is the N
           numbering of the underlying path.  For some of the "Math::NumSeq::OEIS" generated
           sequences there may be a higher "i_start()" corresponding to a higher starting point
           in the OEIS, though this is slightly experimental.

       "$str = $seq->oeis_anum()"
           Return the A-number (a string) for $seq in Sloane's Online Encyclopedia of Integer
           Sequences, or return "undef" if not in the OEIS or not known.

           Known A-numbers are also presented through "Math::NumSeq::OEIS::Catalogue".  This
           means PlanePath related OEIS sequences can be created with "Math::NumSeq::OEIS" by
           giving their A-number in the usual way for that module.

SEE ALSO

       Math::NumSeq, Math::NumSeq::PlanePathDelta, Math::NumSeq::PlanePathTurn,
       Math::NumSeq::PlanePathN, Math::NumSeq::OEIS

       Math::PlanePath

HOME PAGE

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

LICENSE

       Copyright 2011, 2012, 2013, 2014 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/>.