org.apache.lucene.spatial.prefix.tree

Class SpatialPrefixTree

java.lang.Object

org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree

Direct Known Subclasses:

GeohashPrefixTree, QuadPrefixTree

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 spatial region. 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 and Description
protected com.spatial4j.core.context.SpatialContext	ctx
protected int	maxLevels
protected static Charset	UTF8

Constructor Summary

Constructors

Constructor and Description
SpatialPrefixTree(com.spatial4j.core.context.SpatialContext ctx, int maxLevels)

Method Summary

Methods

Modifier and Type	Method and Description
abstract int	getLevelForDistance(double dist) Returns the level of the smallest grid size with a side length that is greater or equal to the provided distance.
int	getMaxLevelForPrecision(com.spatial4j.core.shape.Shape shape, double precision) See SpatialArgs.getDistPrecision().
int	getMaxLevels()
abstract Node	getNode(byte[] bytes, int offset, int len)
Node	getNode(byte[] bytes, int offset, int len, Node target)
protected Node	getNode(com.spatial4j.core.shape.Point p, int level)
abstract Node	getNode(String token) The cell for the specified token.
List<Node>	getNodes(com.spatial4j.core.shape.Shape shape, int detailLevel, boolean inclParents) Gets the intersecting & including cells for the specified shape, without exceeding detail level.
protected List<Node>	getNodesAltPoint(com.spatial4j.core.shape.Point p, int detailLevel, boolean inclParents) Subclasses might override getNodes(com.spatial4j.core.shape.Shape, int, boolean) and check if the argument is a shape and if so, delegate to this implementation, which calls getNode(com.spatial4j.core.shape.Point, int) and then calls getNode(String) repeatedly if inclParents is true.
com.spatial4j.core.context.SpatialContext	getSpatialContext()
Node	getWorldNode() Returns the level 0 cell which encompasses all spatial data.
static List<String>	nodesToTokenStrings(Collection<Node> nodes) Will add the trailing leaf byte for leaves.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

UTF8

protected static final Charset UTF8

maxLevels

protected final int maxLevels

ctx

protected final com.spatial4j.core.context.SpatialContext ctx

Constructor Detail

SpatialPrefixTree

public SpatialPrefixTree(com.spatial4j.core.context.SpatialContext ctx,
                 int maxLevels)

Method Detail

getSpatialContext

public com.spatial4j.core.context.SpatialContext getSpatialContext()

getMaxLevels

public int getMaxLevels()

toString

public String toString()

Overrides:

toString in class Object

getMaxLevelForPrecision

public int getMaxLevelForPrecision(com.spatial4j.core.shape.Shape shape,
                          double precision)

See SpatialArgs.getDistPrecision(). A grid level looked up via getLevelForDistance(double) is returned.

Parameters:

precision - 0-0.5

Returns:

1-maxLevels

getLevelForDistance

public abstract int getLevelForDistance(double dist)

Returns the level of the smallest grid size with a side length that is greater or equal to the provided distance.

Parameters:

dist - >= 0

Returns:

level [1-maxLevels]

getWorldNode

public Node getWorldNode()

Returns the level 0 cell which encompasses all spatial data. Equivalent to getNode(String) with "". This cell is threadsafe, just like a spatial prefix grid is, although cells aren't generally threadsafe. TODO rename to getTopCell or is this fine?

getNode

public abstract Node getNode(String token)

The cell for the specified token. The empty string should be equal to getWorldNode(). Precondition: Never called when token length > maxLevel.

getNode

public abstract Node getNode(byte[] bytes,
           int offset,
           int len)

getNode

public final Node getNode(byte[] bytes,
           int offset,
           int len,
           Node target)

getNode

protected Node getNode(com.spatial4j.core.shape.Point p,
           int level)

getNodes

public List<Node> getNodes(com.spatial4j.core.shape.Shape shape,
                  int detailLevel,
                  boolean inclParents)

Gets the intersecting & including cells for the specified shape, without exceeding detail level. The result is a set of cells (no dups), sorted. Unmodifiable.

This implementation checks if shape is a Point and if so uses an implementation that recursively calls Node.getSubCell(com.spatial4j.core.shape.Point). Cell subclasses ideally implement that method with a quick implementation, otherwise, subclasses should override this method to invoke getNodesAltPoint(com.spatial4j.core.shape.Point, int, boolean). TODO consider another approach returning an iterator -- won't build up all cells in memory.

getNodesAltPoint

protected final List<Node> getNodesAltPoint(com.spatial4j.core.shape.Point p,
                          int detailLevel,
                          boolean inclParents)

Subclasses might override getNodes(com.spatial4j.core.shape.Shape, int, boolean) and check if the argument is a shape and if so, delegate to this implementation, which calls getNode(com.spatial4j.core.shape.Point, int) and then calls getNode(String) repeatedly if inclParents is true.

nodesToTokenStrings

public static List<String> nodesToTokenStrings(Collection<Node> nodes)

Will add the trailing leaf byte for leaves. This isn't particularly efficient.