Class QuasiRandomTools

java.lang.Object
com.github.yellowstonegames.grid.QuasiRandomTools
public final class QuasiRandomTools extends Object
Static methods to produce numbers and points from quasi-random sequences (which seem like random sequences, but have lower "discrepancy" between results). In practice, this means that the points this produces from a sequence tend to be distant from other points from nearby in the sequence.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final float[][]
    GOLDEN_FLOATS
    This is...
    static final long[][]
    GOLDEN_LONGS
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static Coord
    halton2D(int width, int height, int index)
    Gets a 2D point from the Halton sequence with the bases 3 (for x) and 5 (for y).
    static Coord
    halton2D(int baseX, int baseY, int width, int height, int offsetX, int offsetY, int index)
    Gets a 2D point from the Halton sequence with the specified bases, which must be different primes.
    static Coord
    roberts2D(int width, int height, int offsetX, int offsetY, int index)
    Martin Roberts' "unreasonably effective" quasi-random point sequence based on a 2D analogue to the golden ratio.
    static float[]
    robertsND(float[] buffer, int position, int dimensions, int index)
    Fills a buffer (or creates one) with quasi-random floats between 0 (inclusive) and 1 (exclusive).
    static float
    vanDerCorput(int base, int index)
    Gets the index-th element from the base-base van der Corput sequence.
    static double
    vanDerCorputD(long base, long index)
    Gets the index-th element from the base-base van der Corput sequence.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • GOLDEN_FLOATS

      public static final float[][] GOLDEN_FLOATS
      This is... complex, and based closely on Martin Roberts' blog posts about harmonious numbers and generalizing the golden ratio. See here for background. This is a 2D jagged array, starting with a one-element array containing the golden ratio 1.6180339887498949 raised to the -1 power. The golden ratio is the first harmonious number (see link). The second sub-array in this contains the second harmonious number 1.324717957244746 raised to the -1 power and then raised to the -2 power. For all 50 sub-arrays in this, the pattern is the same (using 1-indexing: the sub-array at [n - 1] has the nth harmonious number raised to successive negative powers from -1 down to and including -n. This is useful for higher-dimensional versions of the R2 sequence.

    • GOLDEN_LONGS

      public static final long[][] GOLDEN_LONGS

  • Method Details

    • vanDerCorput

      public static float vanDerCorput(int base, int index)
      Gets the index-th element from the base-base van der Corput sequence. The base should usually be a prime number. The index must be greater than 0 and should be less than 16777216. The number this returns is a float between 0 (inclusive) and 1 (exclusive).
      Parameters:
      base - a prime number to use as the base/radix of the van der Corput sequence
      index - the position in the sequence of the requested base, as a positive int
      Returns:
      a quasi-random float between 0.0 (inclusive) and 1.0 (exclusive).

    • vanDerCorputD

      public static double vanDerCorputD(long base, long index)
      Gets the index-th element from the base-base van der Corput sequence. The base should usually be a prime number. The index must be greater than 0 and should be less than 16777216. The number this returns is a float between 0 (inclusive) and 1 (exclusive).
      Parameters:
      base - a prime number to use as the base/radix of the van der Corput sequence
      index - the position in the sequence of the requested base, as a positive int
      Returns:
      a quasi-random float between 0.0 (inclusive) and 1.0 (exclusive).

    • halton2D

      public static Coord halton2D(int width, int height, int index)
      Gets a 2D point from the Halton sequence with the bases 3 (for x) and 5 (for y).
      Parameters:
      width - the exclusive upper bound on the possible values for x
      height - the exclusive upper bound on the possible values for y
      index - the index in the Halton sequence with the given bases, as a positive int
      Returns:
      a Coord with x between 0 (inclusive) and width (exclusive), and y between 0 (inclusive) and height (exclusive)

    • halton2D

      public static Coord halton2D(int baseX, int baseY, int width, int height, int offsetX, int offsetY, int index)
      Gets a 2D point from the Halton sequence with the specified bases, which must be different primes.
      Parameters:
      baseX - should be prime and different from baseY
      baseY - should be prime and different from baseX
      width - the x-size of the space this can place a Coord
      height - the y-size of the space this can place a Coord
      offsetX - the minimum x-position of a Coord
      offsetY - the minimum y-position of a Coord
      index - the index in the Halton sequence with the given bases, as a positive int
      Returns:
      a Coord with x between offsetX (inclusive) and offsetX + width (exclusive), and y between offsetY (inclusive) and offsetY + height (exclusive)

    • roberts2D

      public static Coord roberts2D(int width, int height, int offsetX, int offsetY, int index)
      Martin Roberts' "unreasonably effective" quasi-random point sequence based on a 2D analogue to the golden ratio. See his blog for more detailed info, but this can be summarized as being excellent at separating points at the expense of seeming less random. Produces a Coord with x between offsetX (inclusive) and offsetX + width (exclusive), and y between offsetY (inclusive) and offsetY + height (exclusive), with the Coord at each index likely to be different for at least width * height / 4 indices (very low sizes may offer less of a guarantee).
      This is also called the R2 sequence.
      Parameters:
      width - the x-size of the space this can place a Coord
      height - the y-size of the space this can place a Coord
      offsetX - the minimum x-position of a Coord
      offsetY - the minimum y-position of a Coord
      index - the index of the Coord in the 2D Roberts sequence; should be greater than 0, but not required to be
      Returns:
      a Coord with x,y between offsetX,offsetY inclusive and offsetX+width,offsetY+height exclusive

    • robertsND

      public static float[] robertsND(float[] buffer, int position, int dimensions, int index)
      Fills a buffer (or creates one) with quasi-random floats between 0 (inclusive) and 1 (exclusive). Indices in the buffer from position (inclusive) to position + dimensions (exclusive) will be assigned what should almost always be distinct values from a quasi-random sequence described by Martin Roberts. The index parameter is the index in that sequence, and should be greater than 0; typically as you need more points, you raise the index. If buffer is null or cannot hold dimensions items, a new float array is created and returned. See Roberts' blog for more detailed info. This uses the constants in GOLDEN_LONGS.
      Parameters:
      buffer - a float array to assign into; if null or too-small, an appropriately-sized array will be created
      position - the position in buffer to start assigning values into
      dimensions - how many dimensions a point should have, clamped between 1 and 50 inclusive
      index - the index of the Coord in a Roberts sequence; should be greater than 0, but not required to be
      Returns:
      buffer, after modifications, or a newly-created float array if buffer was null or too-small