Class PoissonDisk

java.lang.Object
com.github.yellowstonegames.grid.PoissonDisk
public final class PoissonDisk extends Object
An implementation of the Poisson Disk sampling algorithm on a discrete grid. The sampleCircle() and sampleRectangle() methods here all return CoordObjectOrderedMap results with ObjectList-of-Coord values, where the key represents a sampled (and chosen) point and the value represents "children" of the key point. The value is often an empty list; if it isn't, it holds some amount of Coord nodes (always other keys in the result) that radiate away from the center. You may want just the sampled points; get the ObjectObjectOrderedMap.order() ObjectList for a convenient source of those. The sampleMap() methods work a little differently, and return a CoordOrderedSet holding sampled points as items (without anything holding children). Lastly, the separatedPoisson() method is very different; it is mostly used internally by Region, and takes a Region that it modifies in-place so "on" cells in that Region must satisfy a minimum distance from other "on" cells, otherwise they are set to "off."

  • Method Summary

    Modifier and Type
    Method
    Description
    static CoordObjectOrderedMap<com.github.tommyettinger.ds.ObjectList<Coord>>
    sampleCircle(Coord center, float radius, float minimumDistance, int maxX, int maxY)
    Get a group of Coords, each randomly positioned around the given center out to the given radius (measured with Euclidean distance, so a true circle), but with the given minimum distance from any other Coord in the group.
    static CoordObjectOrderedMap<com.github.tommyettinger.ds.ObjectList<Coord>>
    sampleCircle(Coord center, float radius, float minimumDistance, int maxX, int maxY, int pointsPerIteration, com.github.tommyettinger.random.EnhancedRandom rng)
    Get a group of Coords, each randomly positioned around the given center out to the given radius (measured with Euclidean distance, so a true circle), but with the given minimum distance from any other Coord in the group.
    static CoordOrderedSet
    sampleMap(char[][] map, float minimumDistance, com.github.tommyettinger.random.EnhancedRandom rng, char... blocking)
    Calls sampleMap(Region, float, EnhancedRandom) by constructing a Region from map and blocking (using Region(char[][], char[]) and calling Region.not() on it).
    static CoordOrderedSet
    sampleMap(Coord minPosition, Coord maxPosition, char[][] map, float minimumDistance, com.github.tommyettinger.random.EnhancedRandom rng, char... blocking)
    Calls sampleMap(Coord, Coord, Region, float, EnhancedRandom) by constructing a Region from map and blocking (using Region(char[][], char[]) and calling Region.not() on it).
    static CoordOrderedSet
    sampleMap(Coord minPosition, Coord maxPosition, Region map, float minimumDistance, com.github.tommyettinger.random.EnhancedRandom rng)
    Sub-randomly samples a Region's "on" cells, returning a CoordOrderedSet where each Coord corresponds to an "on" cell in map and has at least minimumDistance between itself and any other Coord in the Set.
    static CoordOrderedSet
    sampleMap(Region map, float minimumDistance, com.github.tommyettinger.random.EnhancedRandom rng)
    Sub-randomly samples a Region's "on" cells, returning a CoordOrderedSet where each Coord corresponds to an "on" cell in map and has at least minimumDistance between itself and any other Coord in the Set.
    static CoordObjectOrderedMap<com.github.tommyettinger.ds.ObjectList<Coord>>
    sampleRectangle(Coord minPosition, Coord maxPosition, float minimumDistance)
    Get a group of Coords, each randomly positioned within the rectangle between the given minPosition and maxPosition, but with the given minimum distance from any other Coord in the group.
    static CoordObjectOrderedMap<com.github.tommyettinger.ds.ObjectList<Coord>>
    sampleRectangle(Coord minPosition, Coord maxPosition, float minimumDistance, int maxX, int maxY, int pointsPerIteration, com.github.tommyettinger.random.EnhancedRandom rng)
    Get a group of Coords, each randomly positioned within the rectangle between the given minPosition and maxPosition, but with the given minimum distance from any other Coord in the group.
    static CoordObjectOrderedMap<com.github.tommyettinger.ds.ObjectList<Coord>>
    sampleRectangle(Coord minPosition, Coord maxPosition, float minimumDistance, int pointsPerIteration, com.github.tommyettinger.random.EnhancedRandom rng)
    Get a group of Coords, each randomly positioned within the rectangle between the given minPosition and maxPosition, but with the given minimum distance from any other Coord in the group.
    static Region
    separatedPoisson(Region map, float minimumDistance, com.github.tommyettinger.random.EnhancedRandom rng, int limit)
    Sub-randomly samples a Region (map)'s "on" cells, returning that Region modified in-place so it stores only Coords corresponding to an "on" cell in the original map and has at least minimumDistance between itself and any other Coord in the returned map.

    Methods inherited from class Object

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

  • Method Details

    • sampleCircle

      public static CoordObjectOrderedMap<com.github.tommyettinger.ds.ObjectList<Coord>> sampleCircle(Coord center, float radius, float minimumDistance, int maxX, int maxY)
      Get a group of Coords, each randomly positioned around the given center out to the given radius (measured with Euclidean distance, so a true circle), but with the given minimum distance from any other Coord in the group. The parameters maxX and maxY should typically correspond to the width and height of the map; no points will have positions with x equal to or greater than maxX and the same for y and maxY; similarly, no points will have negative x or y.
      Parameters:
      center - the center of the circle to spray Coords into
      radius - the radius of the circle to spray Coords into
      minimumDistance - the minimum distance between Coords, in Euclidean distance as a float.
      maxX - one more than the highest x that can be assigned; typically an array length
      maxY - one more than the highest y that can be assigned; typically an array length
      Returns:
      a CoordObjectOrderedMap with ObjectList of Coord values (representing points the key connects to); keys will satisfy the minimum distance to other keys

    • sampleCircle

      public static CoordObjectOrderedMap<com.github.tommyettinger.ds.ObjectList<Coord>> sampleCircle(Coord center, float radius, float minimumDistance, int maxX, int maxY, int pointsPerIteration, com.github.tommyettinger.random.EnhancedRandom rng)
      Get a group of Coords, each randomly positioned around the given center out to the given radius (measured with Euclidean distance, so a true circle), but with the given minimum distance from any other Coord in the group. The parameters maxX and maxY should typically correspond to the width and height of the map; no points will have positions with x equal to or greater than maxX and the same for y and maxY; similarly, no points will have negative x or y.
      Parameters:
      center - the center of the circle to spray Coords into
      radius - the radius of the circle to spray Coords into
      minimumDistance - the minimum distance between Coords, in Euclidean distance as a float.
      maxX - one more than the highest x that can be assigned; typically an array length
      maxY - one more than the highest y that can be assigned; typically an array length
      pointsPerIteration - with small radii, this can be around 5; with larger ones, 30 is reasonable
      rng - an IRNG to use for all random sampling.
      Returns:
      a CoordObjectOrderedMap with ObjectList of Coord values (representing points the key connects to); keys will satisfy the minimum distance to other keys

    • sampleRectangle

      public static CoordObjectOrderedMap<com.github.tommyettinger.ds.ObjectList<Coord>> sampleRectangle(Coord minPosition, Coord maxPosition, float minimumDistance)
      Get a group of Coords, each randomly positioned within the rectangle between the given minPosition and maxPosition, but with the given minimum distance from any other Coord in the group. The parameters maxX and maxY should typically correspond to the width and height of the map; no points will have positions with x equal to or greater than maxX and the same for y and maxY; similarly, no points will have negative x or y.
      Parameters:
      minPosition - the Coord with the lowest x and lowest y to be used as a corner for the bounding box
      maxPosition - the Coord with the highest x and highest y to be used as a corner for the bounding box
      minimumDistance - the minimum distance between Coords, in Euclidean distance as a float.
      Returns:
      a CoordObjectOrderedMap with ObjectList of Coord values (representing points the key connects to); keys will satisfy the minimum distance to other keys

    • sampleRectangle

      public static CoordObjectOrderedMap<com.github.tommyettinger.ds.ObjectList<Coord>> sampleRectangle(Coord minPosition, Coord maxPosition, float minimumDistance, int pointsPerIteration, com.github.tommyettinger.random.EnhancedRandom rng)
      Get a group of Coords, each randomly positioned within the rectangle between the given minPosition and maxPosition, but with the given minimum distance from any other Coord in the group. The parameters maxX and maxY should typically correspond to the width and height of the map; no points will have positions with x equal to or greater than maxX and the same for y and maxY; similarly, no points will have negative x or y.
      Parameters:
      minPosition - the Coord with the lowest x and lowest y to be used as a corner for the bounding box
      maxPosition - the Coord with the highest x and highest y to be used as a corner for the bounding box
      minimumDistance - the minimum distance between Coords, in Euclidean distance as a float.
      pointsPerIteration - with small areas, this can be around 5; with larger ones, 30 is reasonable
      rng - an IRNG to use for all random sampling.
      Returns:
      a CoordObjectOrderedMap with ObjectList of Coord values (representing points the key connects to); keys will satisfy the minimum distance to other keys

    • sampleRectangle

      public static CoordObjectOrderedMap<com.github.tommyettinger.ds.ObjectList<Coord>> sampleRectangle(Coord minPosition, Coord maxPosition, float minimumDistance, int maxX, int maxY, int pointsPerIteration, com.github.tommyettinger.random.EnhancedRandom rng)
      Get a group of Coords, each randomly positioned within the rectangle between the given minPosition and maxPosition, but with the given minimum distance from any other Coord in the group. The parameters maxX and maxY should typically correspond to the width and height of the map; no points will have positions with x equal to or greater than maxX and the same for y and maxY; similarly, no points will have negative x or y.
      Parameters:
      minPosition - the Coord with the lowest x and lowest y to be used as a corner for the bounding box
      maxPosition - the Coord with the highest x and highest y to be used as a corner for the bounding box
      minimumDistance - the minimum distance between Coords, in Euclidean distance as a float.
      maxX - one more than the highest x that can be assigned; typically an array length
      maxY - one more than the highest y that can be assigned; typically an array length
      pointsPerIteration - with small areas, this can be around 5; with larger ones, 30 is reasonable
      rng - an IRNG to use for all random sampling.
      Returns:
      a CoordObjectOrderedMap with ObjectList of Coord values (representing points the key connects to); keys will satisfy the minimum distance to other keys

    • sampleMap

      public static CoordOrderedSet sampleMap(char[][] map, float minimumDistance, com.github.tommyettinger.random.EnhancedRandom rng, char... blocking)
      Calls sampleMap(Region, float, EnhancedRandom) by constructing a Region from map and blocking (using Region(char[][], char[]) and calling Region.not() on it).
      Parameters:
      map - a 2D char array to use as a local map
      minimumDistance - the minimum distance to permit between Coords this chooses
      rng - an EnhancedRandom
      blocking - an array or varargs of char values that this cannot sample in map.
      Returns:
      a CoordOrderedSet where items will satisfy the minimum distance to other items
      See Also:

    • sampleMap

      public static CoordOrderedSet sampleMap(Coord minPosition, Coord maxPosition, char[][] map, float minimumDistance, com.github.tommyettinger.random.EnhancedRandom rng, char... blocking)
      Calls sampleMap(Coord, Coord, Region, float, EnhancedRandom) by constructing a Region from map and blocking (using Region(char[][], char[]) and calling Region.not() on it).
      Parameters:
      minPosition - the inclusive minimum-x, minimum-y cell bounding the area this will sample
      maxPosition - the inclusive maximum-x, maximum-y cell bounding the area this will sample
      map - a 2D char array to use as a local map
      minimumDistance - the minimum distance to permit between Coords this chooses
      rng - an EnhancedRandom
      blocking - an array or varargs of char values that this cannot sample in map.
      Returns:
      a CoordOrderedSet where items will satisfy the minimum distance to other items
      See Also:

    • sampleMap

      public static CoordOrderedSet sampleMap(Region map, float minimumDistance, com.github.tommyettinger.random.EnhancedRandom rng)
      Sub-randomly samples a Region's "on" cells, returning a CoordOrderedSet where each Coord corresponds to an "on" cell in map and has at least minimumDistance between itself and any other Coord in the Set. This overload won't sample from the perimeter of map, but can sample from any other "on" cell.
      Parameters:
      map - a Region that must have at least one "on" cell
      minimumDistance - the minimum distance to permit between Coords this chooses
      rng - an EnhancedRandom
      Returns:
      a CoordOrderedSet where items will satisfy the minimum distance to other items

    • sampleMap

      public static CoordOrderedSet sampleMap(Coord minPosition, Coord maxPosition, Region map, float minimumDistance, com.github.tommyettinger.random.EnhancedRandom rng)
      Sub-randomly samples a Region's "on" cells, returning a CoordOrderedSet where each Coord corresponds to an "on" cell in map and has at least minimumDistance between itself and any other Coord in the Set. This overload allows specifying a smaller rectangle to sample (smaller than the whole Region) with minPosition and maxPosition.
      Parameters:
      minPosition - the inclusive minimum-x, minimum-y cell bounding the area this will sample
      maxPosition - the inclusive maximum-x, maximum-y cell bounding the area this will sample
      map - a Region that must have at least one "on" cell
      minimumDistance - the minimum distance to permit between Coords this chooses
      rng - an EnhancedRandom
      Returns:
      a CoordOrderedSet where items will satisfy the minimum distance to other items

    • separatedPoisson

      public static Region separatedPoisson(Region map, float minimumDistance, com.github.tommyettinger.random.EnhancedRandom rng, int limit)
      Sub-randomly samples a Region (map)'s "on" cells, returning that Region modified in-place so it stores only Coords corresponding to an "on" cell in the original map and has at least minimumDistance between itself and any other Coord in the returned map.
      Parameters:
      map - a Region that must have at least one "on" cell
      minimumDistance - the minimum distance to permit between Coords this chooses
      rng - an EnhancedRandom
      limit - the max number of "on" cells that can be in the Region this returns; if negative, there is no max
      Returns:
      map, modified in-place so each Coord corresponds to an "on" cell in map and has at least minimumDistance to any other Coord