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

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