SpatialPrefixTree (Lucene 10.5.0 spatial-extras API)
Description: declaration: package: org.apache.lucene.spatial.prefix.tree, class: SpatialPrefixTree

Package org.apache.lucene.spatial.prefix.tree

# Class SpatialPrefixTree

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

Direct Known Subclasses:
  `GeohashPrefixTree`, `NumberRangePrefixTree`, `QuadPrefixTree`, `S2PrefixTree`

public abstract class SpatialPrefixTree extends Object
A spatial Prefix Tree, or Trie, which decomposes shapes into prefixed strings at variable lengths corresponding to variable precision. Each string corresponds to a rectangular spatial region. This approach is also referred to "Grids", "Tiles", and "Spatial Tiers".

Implementations of this class should be thread-safe and immutable once initialized.

WARNING: This API is experimental and might change in incompatible ways in the next release.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final org.locationtech.spatial4j.context.SpatialContext`
  `ctx`
  `protected final int`
  `maxLevels`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SpatialPrefixTree(org.locationtech.spatial4j.context.SpatialContext ctx, int maxLevels)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract double`
  `getDistanceForLevel(int level)`
  Given a cell having the specified level, returns the distance from opposite corners.
  `abstract 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).
  `int`
  `getMaxLevels()`
  `org.locationtech.spatial4j.context.SpatialContext`
  `getSpatialContext()`
  `CellIterator`
  `getTreeCellIterator(org.locationtech.spatial4j.shape.Shape shape, int detailLevel)`
  Gets the intersecting cells for the specified shape, without exceeding detail level.
  `abstract Cell`
  `getWorldCell()`
  Returns the level 0 cell which encompasses all spatial data.
  `abstract 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.
  `String`
  `toString()`

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

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

- ## Field Details

  - ### maxLevels

    protected final int maxLevels

  - ### ctx

    protected final org.locationtech.spatial4j.context.SpatialContext ctx

- ## Constructor Details

  - ### SpatialPrefixTree

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

- ## Method Details

  - ### getSpatialContext

    public org.locationtech.spatial4j.context.SpatialContext getSpatialContext()

  - ### getMaxLevels

    public int getMaxLevels()

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### getLevelForDistance

    public abstract 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). 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.
    Parameters:
      `dist` - `>= 0`
    Returns:
      level [1 to maxLevels]

  - ### getDistanceForLevel

    public abstract double getDistanceForLevel(int level)
    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.
    Parameters:
      `level` - [1 to maxLevels]
    Returns:
      `> 0`

  - ### getWorldCell

    public abstract Cell getWorldCell()
    Returns the level 0 cell which encompasses all spatial data. Equivalent to `readCell(BytesRef,Cell)` with no bytes.

  - ### readCell

    public abstract 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. Warning: An implementation may refer to the same byte array (no copy). If `Cell.setLeaf()` is subsequently called, it would then modify these bytes.

  - ### getTreeCellIterator

    public CellIterator getTreeCellIterator(org.locationtech.spatial4j.shape.Shape shape, int detailLevel)
    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.

    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