Class S2FractalBuilder


  • @GwtCompatible
    public class S2FractalBuilder
    extends java.lang.Object
    A simple class that generates "Koch snowflake" fractals (see Wikipedia for an introduction). There is an option to control the fractal dimension (between 1.0 and 2.0); values between 1.02 and 1.50 are reasonable simulations of various coastlines. The default dimension (about 1.26) corresponds to the standard Koch snowflake. (The west coast of Britain has a fractal dimension of approximately 1.25)

    The fractal is obtained by starting with an equilateral triangle and recursively subdividing each edge into four segments of equal length. Therefore the shape at level 'n' consists of 3 * (4^n) edges. Multi-level fractals are also supported: if you set minLevel() to a non-negative value, then the recursive subdivision has an equal probability of stopping at any of the levels between the given min and max (inclusive). This yields a fractal where the perimeter of the original triangle is approximately equally divided between fractals at the various possible levels. If there are k distinct levels {min, ..., max}, the expected number of edges at each level 'i' is approximately 3 * (4 ^ i) / k.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private double dimension
      Standard Koch curve
      private double edgeFraction
      The ratio of the sub-edge length to the original edge length at each subdivision step.
      private int maxLevel  
      private int minLevel
      Actual min level (depends on maxLevel.)
      private int minLevelArg
      Value set by user.
      private double offsetFraction
      The distance from the original edge to the middle vertex at each subdivision step, as a fraction of the original edge length.
      private java.util.Random rand  
    • Constructor Summary

      Constructors 
      Constructor Description
      S2FractalBuilder​(java.util.Random rand)
      You must call setMaxLevel() or setLevelForApproxMaxMedges() before calling makeLoop().
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void computeMinLevel()  
      private void computeOffsets()  
      private void getR2Vertices​(java.util.List<R2Vector> vertices)  
      private void getR2VerticesHelper​(R2Vector v0, R2Vector v4, int level, java.util.List<R2Vector> vertices)
      Given the two endpoints (v0, v4) of an edge, recursively subdivide the edge to the desired level, and insert all vertices of the resulting curve up to but not including the endpoint "v4".
      private static int levelFromEdges​(int edges)
      Returns level from values in the range [1.5 * (4 ^ n), 6 * (4 ^ n)].
      S2Loop makeLoop​(Matrix3x3 frame, S1Angle nominalRadius)
      Returns a fractal loop centered around the a-axis of the given coordinate frame, with the first vertex in the direction of the positive x-axis, and the given nominal radius.
      java.util.List<S2Point> makeVertices​(Matrix3x3 frame, S1Angle nominalRadius)
      As makeLoop(Matrix3x3, S1Angle) except it returns the vertices instead of loop.
      double maxRadiusFactor()
      Returns the ratio (Rmax / R), where 'R' is the radius passed to makeLoop() and 'Rmax' is the maximum distance from the fractal boundary to its center.
      double minRadiusFactor()
      Returns a lower bound on the ratio (Rmin / R), where 'R' is the radius passed to makeLoop() and 'Rmin' is the minimum distance from the fractal boundary to its center.
      void setFractalDimension​(double dimension)
      Sets the fractal dimension.
      void setLevelForApproxMaxEdges​(int maxEdges)  
      void setLevelForApproxMinEdges​(int minEdges)
      The following two functions set the min and/or max level to produce approximately the given number of edges.
      void setMaxLevel​(int maxLevel)
      Sets the maximum subdivision level for the fractal (see above).
      void setMinLevel​(int minLevelArg)
      Sets the minimum subdivision level for the fractal (see above).
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • maxLevel

        private int maxLevel
      • minLevelArg

        private int minLevelArg
        Value set by user.
      • minLevel

        private int minLevel
        Actual min level (depends on maxLevel.)
      • dimension

        private double dimension
        Standard Koch curve
      • edgeFraction

        private double edgeFraction
        The ratio of the sub-edge length to the original edge length at each subdivision step.
      • offsetFraction

        private double offsetFraction
        The distance from the original edge to the middle vertex at each subdivision step, as a fraction of the original edge length.
      • rand

        private java.util.Random rand
    • Constructor Detail

      • S2FractalBuilder

        public S2FractalBuilder​(java.util.Random rand)
        You must call setMaxLevel() or setLevelForApproxMaxMedges() before calling makeLoop().
    • Method Detail

      • setMaxLevel

        public void setMaxLevel​(int maxLevel)
        Sets the maximum subdivision level for the fractal (see above).
      • setMinLevel

        public void setMinLevel​(int minLevelArg)
        Sets the minimum subdivision level for the fractal (see above). The default value of -1 causes the min and max levels to be the same. A minLevel of 0 should be avoided since this creates a significant chance that none of the three original edges will be subdivided at all.
      • computeMinLevel

        private void computeMinLevel()
      • setFractalDimension

        public void setFractalDimension​(double dimension)
        Sets the fractal dimension. The default value of approximately 1.26 corresponds to the standard Koch curve. The value must lie in the range [1.0, 2.0).
      • computeOffsets

        private void computeOffsets()
      • setLevelForApproxMinEdges

        public void setLevelForApproxMinEdges​(int minEdges)
        The following two functions set the min and/or max level to produce approximately the given number of edges. (The values are rounded to a nearby value of 3 * (4 ^ n).)
      • setLevelForApproxMaxEdges

        public void setLevelForApproxMaxEdges​(int maxEdges)
      • levelFromEdges

        private static int levelFromEdges​(int edges)
        Returns level from values in the range [1.5 * (4 ^ n), 6 * (4 ^ n)].
      • minRadiusFactor

        public double minRadiusFactor()
        Returns a lower bound on the ratio (Rmin / R), where 'R' is the radius passed to makeLoop() and 'Rmin' is the minimum distance from the fractal boundary to its center. This can be used to inscribe another geometric figure within the fractal without intersection.
      • maxRadiusFactor

        public double maxRadiusFactor()
        Returns the ratio (Rmax / R), where 'R' is the radius passed to makeLoop() and 'Rmax' is the maximum distance from the fractal boundary to its center. This can be used to inscribe the fractal within some other geometric figure without intersection.
      • getR2Vertices

        private void getR2Vertices​(java.util.List<R2Vector> vertices)
      • getR2VerticesHelper

        private void getR2VerticesHelper​(R2Vector v0,
                                         R2Vector v4,
                                         int level,
                                         java.util.List<R2Vector> vertices)
        Given the two endpoints (v0, v4) of an edge, recursively subdivide the edge to the desired level, and insert all vertices of the resulting curve up to but not including the endpoint "v4".
      • makeLoop

        public S2Loop makeLoop​(Matrix3x3 frame,
                               S1Angle nominalRadius)
        Returns a fractal loop centered around the a-axis of the given coordinate frame, with the first vertex in the direction of the positive x-axis, and the given nominal radius.