Class S2RegionCoverer.Builder

  • Enclosing class:
    S2RegionCoverer

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

      • 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:
        Constant Field Values
      • minLevel

        private int minLevel
      • maxLevel

        private int maxLevel
      • levelMod

        private int levelMod
      • maxCells

        private int maxCells
    • Constructor Detail

      • Builder

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

      • 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.