Class S2RegionCoverer.Builder

java.lang.Object
com.google.common.geometry.S2RegionCoverer.Builder
Enclosing class:
S2RegionCoverer

public static final class S2RegionCoverer.Builder extends Object
A Build to construct a S2RegionCoverer with options.
  • Field Details

    • DEFAULT_MAX_CELLS

      private static final int DEFAULT_MAX_CELLS
      By default, the covering uses at most 8 cells at any level. This gives a reasonable tradeoff between the number of cells used and the accuracy of the approximation (see table below).
      See Also:
    • minLevel

      private int minLevel
    • maxLevel

      private int maxLevel
    • levelMod

      private int levelMod
    • maxCells

      private int maxCells
  • Constructor Details

    • Builder

      private Builder()
      Users should create a Builder via the S2RegionCoverer.builder() method.
  • Method Details

    • setMinLevel

      public S2RegionCoverer.Builder setMinLevel(int minLevel)
      Sets the minimum level to be used.

      Default: 0

    • getMinLevel

      public int getMinLevel()
      Returns the minimum cell level to be used.
    • setMaxLevel

      public S2RegionCoverer.Builder setMaxLevel(int maxLevel)
      Sets the maximum level to be used.

      Default: S2CellId.MAX_LEVEL

    • getMaxLevel

      public int getMaxLevel()
      Returns the maximum cell level to be used.
    • setLevelMod

      public S2RegionCoverer.Builder setLevelMod(int levelMod)
      Only cells where (level - minLevel) is a multiple of "levelMod" will be used (default 1). This effectively allows the branching factor of the S2CellId hierarchy to be increased. Currently the only parameter values allowed are 1, 2, or 3, corresponding to branching factors of 4, 16, and 64 respectively.

      Default: 1

    • getLevelMod

      public int getLevelMod()
      Returns the level mod.
    • setMaxCells

      public S2RegionCoverer.Builder setMaxCells(int maxCells)
      Sets the maximum desired number of cells in the approximation (defaults to DEFAULT_MAX_CELLS). Note the following:
      • For any setting of maxCells(), up to 6 cells may be returned if that is the minimum number of cells required (e.g. if the region intersects all six face cells). Up to 3 cells may be returned even for very tiny convex regions if they happen to be located at the intersection of three cube faces.
      • For any setting of maxCells(), an arbitrary number of cells may be returned if minLevel() is too high for the region being approximated.
      • If maxCells() is less than 4, the area of the covering may be arbitrarily large compared to the area of the original region even if the region is convex (e.g. an S2Cap or S2LatLngRect).

      Accuracy is measured by dividing the area of the covering by the area of the original region. The following table shows the median and worst case values for this area ratio on a test case consisting of 100,000 spherical caps of random size (generated using s2regioncoverer_unittest):

       max_cells: 3 4 5 6 8 12 20 100 1000
       median ratio: 5.33 3.32 2.73 2.34 1.98 1.66 1.42 1.11 1.01
       worst case: 215518 14.41 9.72 5.26 3.91 2.75 1.92 1.20 1.02
       

      Default: 8

    • getMaxCells

      public int getMaxCells()
      Returns the maximum desired number of cells to be used.
    • build

      public S2RegionCoverer build()
      Constructs a S2RegionCoverer with this Builders options.