org.apache.lucene.spatial.prefix.tree

## Class S2PrefixTree

- java.lang.Object
- - org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree
  - - org.apache.lucene.spatial.prefix.tree.S2PrefixTree

-     public class S2PrefixTree
      extends SpatialPrefixTree

  Spatial prefix tree for S2 Geometry. Shape factories for the given `SpatialContext` must implement the interface `S2ShapeFactory`. The tree can be configured on how it divided itself by providing an arity. The default arity is 1 which divided every sub-cell in 4 (except the first level that is always divided by 6) . Arity 2 divides sub-cells in 16 and arity 3 in 64 sub-cells.
  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `S2PrefixTree.Factory` Factory for creating `S2PrefixTree` instances with useful defaults

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `arity`
    `protected S2ShapeFactory` | `s2ShapeFactory`

    - ### Fields inherited from class org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree

      `ctx, maxLevels`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `S2PrefixTree(org.locationtech.spatial4j.context.SpatialContext ctx, int maxLevels)` Creates a S2 spatial tree with arity 1.
    `S2PrefixTree(org.locationtech.spatial4j.context.SpatialContext ctx, int maxLevels, int arity)` Creates a S2 spatial tree with provided arity.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `double` | `getDistanceForLevel(int level)` Given a cell having the specified level, returns the distance from opposite corners.
    `int` | `getLevelForDistance(double dist)` Returns the level of the largest grid in which its longest side is less than or equal to the provided distance (in degrees).
    `static int` | `getMaxLevels(int arity)` Get max levels for this spatial tree.
    `CellIterator` | `getTreeCellIterator(org.locationtech.spatial4j.shape.Shape shape, int detailLevel)` Gets the intersecting cells for the specified shape, without exceeding detail level.
    `Cell` | `getWorldCell()` Returns the level 0 cell which encompasses all spatial data.
    `Cell` | `readCell(BytesRef term, Cell scratch)` This creates a new Cell (or re-using `scratch` if provided), initialized to the state as read by the bytes.

    - ### Methods inherited from class org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree

      `getMaxLevels, getSpatialContext, toString`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### s2ShapeFactory

          protected final S2ShapeFactory s2ShapeFactory

    - #### arity

          protected final int arity

  - ### Constructor Detail

    - #### S2PrefixTree

          public S2PrefixTree(org.locationtech.spatial4j.context.SpatialContext ctx,
                              int maxLevels)

      Creates a S2 spatial tree with arity 1.
      Parameters:
        `ctx` - The provided spatial context. The shape factor of the spatial context must implement `S2ShapeFactory`
        `maxLevels` - The provided maximum level for this tree.

    - #### S2PrefixTree

          public S2PrefixTree(org.locationtech.spatial4j.context.SpatialContext ctx,
                              int maxLevels,
                              int arity)

      Creates a S2 spatial tree with provided arity.
      Parameters:
        `ctx` - The provided spatial context. The shape factor of the spatial context must implement `S2ShapeFactory`
        `maxLevels` - The provided maximum level for this tree.
        `arity` - The arity of the tree.

  - ### Method Detail

    - #### getMaxLevels

          public static int getMaxLevels(int arity)

      Get max levels for this spatial tree.
      Parameters:
        `arity` - The arity of the tree.
      Returns:
        The maximum number of levels by the provided arity.

    - #### getLevelForDistance

          public int getLevelForDistance(double dist)

      Description copied from class: `SpatialPrefixTree`
      Returns the level of the largest grid in which its longest side is less than or equal to the provided distance (in degrees). Consequently `dist` acts as an error epsilon declaring the amount of detail needed in the grid, such that you can get a grid with just the right amount of precision.
      Specified by:
        `getLevelForDistance` in class `SpatialPrefixTree`
      Parameters:
        `dist` - `>= 0`
      Returns:
        level [1 to maxLevels]

    - #### getDistanceForLevel

          public double getDistanceForLevel(int level)

      Description copied from class: `SpatialPrefixTree`
      Given a cell having the specified level, returns the distance from opposite corners. Since this might vary depending on where the cell is, this method may over-estimate.
      Specified by:
        `getDistanceForLevel` in class `SpatialPrefixTree`
      Parameters:
        `level` - [1 to maxLevels]
      Returns:
        `> 0`

    - #### getWorldCell

          public Cell getWorldCell()

      Description copied from class: `SpatialPrefixTree`
      Returns the level 0 cell which encompasses all spatial data. Equivalent to `SpatialPrefixTree.readCell(BytesRef,Cell)` with no bytes.
      Specified by:
        `getWorldCell` in class `SpatialPrefixTree`

    - #### readCell

          public Cell readCell(BytesRef term,
                               Cell scratch)

      Description copied from class: `SpatialPrefixTree`
      This creates a new Cell (or re-using `scratch` if provided), initialized to the state as read by the bytes. Warning: An implementation may refer to the same byte array (no copy). If `Cell.setLeaf()` is subsequently called, it would then modify these bytes.
      Specified by:
        `readCell` in class `SpatialPrefixTree`

    - #### getTreeCellIterator

          public CellIterator getTreeCellIterator(org.locationtech.spatial4j.shape.Shape shape,
                                                  int detailLevel)

      Description copied from class: `SpatialPrefixTree`
      Gets the intersecting cells for the specified shape, without exceeding detail level. If a cell is within the query shape then it's marked as a leaf and none of its children are added. For cells at detailLevel, they are marked as leaves too, unless it's a point.

      IMPORTANT: Cells returned from the iterator can be re-used for cells at the same level. So you can't simply iterate to subsequent cells and still refer to the former cell nor the bytes returned from the former cell, unless you know the former cell is a parent.

      Overrides:
        `getTreeCellIterator` in class `SpatialPrefixTree`
      Parameters:
        `shape` - the shape; possibly null but the caller should liberally call `remove()` if so.
        `detailLevel` - the maximum detail level to get cells for
      Returns:
        the matching cells

Copyright © 2000-2024 Apache Software Foundation. All Rights Reserved.