com.graphhopper.storage.index

Class LocationIndexTree

java.lang.Object

com.graphhopper.storage.index.LocationIndexTree

All Implemented Interfaces:

LocationIndex, Storable<LocationIndex>, Closeable, AutoCloseable

public class LocationIndexTree
extends Object
implements LocationIndex

This class implements a Quadtree to get the closest node or edge from GPS coordinates. The following properties are different to an ordinary implementation:

1. To reduce overall size it can use 16 instead of just 4 cell if required
2. Still all leafs are at the same depth, otherwise it is too complicated to calculate the Bresenham line for different resolutions, especially if a leaf node could be split into a tree-node and resolution changes.
3. To further reduce size this Quadtree avoids storing the bounding box of every cell and calculates this per request instead.
4. To simplify this querying and avoid a slow down for the most frequent queries ala "lat,lon" it encodes the point into a reverse spatial key SpatialKeyAlgo and can the use the resulting raw bits as cell index to recurse into the subtrees. E.g. if there are 3 layers with 16, 4 and 4 cells each, then the reverse spatial key has three parts: 4 bits for the cellIndex into the 16 cells, 2 bits for the next layer and 2 bits for the last layer. It is the reverse spatial key and not the forward spatial key as we need the start of the index for the current layer at index 0
5. An array structure (DataAccess) is internally used and stores the offset to the next cell. E.g. in case of 4 cells, the offset is 0,1,2 or 3. Except when the leaf-depth is reached, then the value is the number of node IDs stored in the cell or, if negative, just a single node ID.

Author:

Peter Karich

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	LocationIndexTree.XFirstSearchCheck Make it possible to collect nearby location also for other purposes.

Nested classes/interfaces inherited from interface com.graphhopper.storage.index.LocationIndex

LocationIndex.EdgeVisitor, LocationIndex.Visitor

Field Summary

Fields

Modifier and Type	Field and Description
protected DistanceCalc	distCalc
protected Graph	graph
protected SpatialKeyAlgo	keyAlgo

Constructor Summary

Constructors

Constructor and Description
LocationIndexTree(Graph g, Directory dir)

Method Summary

Modifier and Type	Method and Description
void	close() This method makes sure that the underlying used resources are released.
LocationIndexTree	create(long size) Creates the underlying storage.
QueryResult	findClosest(double queryLat, double queryLon, EdgeFilter edgeFilter) This method returns the closest QueryResult for the specified location (lat, lon) and only if the filter accepts the edge as valid candidate (e.g.
List<QueryResult>	findNClosest(double queryLat, double queryLon, EdgeFilter edgeFilter, double radius) Returns all edges that are within the specified radius around the queried position.
void	flush() This method makes sure that the underlying data is written to the storage.
long	getCapacity()
double	getDeltaLat() Provide info about tilesize for testing / visualization
double	getDeltaLon()
int	getMinResolutionInMeter()
boolean	isClosed()
boolean	loadExisting()
LocationIndex	prepareIndex() Creates this index - to be called once before findID.
void	query(BBox queryShape, LocationIndex.Visitor function) This method explores the nodes in this LocationIndex with the specified Visitor.
LocationIndex	setApproximation(boolean approx)
LocationIndexTree	setMaxRegionSearch(int numTiles) Searches also neighbouring tiles until the maximum distance from the query point is reached (minResolutionInMeter*regionAround).
LocationIndexTree	setMinResolutionInMeter(int minResolutionInMeter) Minimum width in meter of one tile.
LocationIndex	setResolution(int minResolutionInMeter) Integer value to specify the resolution of this location index.
void	setSegmentSize(int bytes)

Methods inherited from class java.lang.Object

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

Field Detail

graph

protected final Graph graph

distCalc

protected DistanceCalc distCalc

keyAlgo

protected SpatialKeyAlgo keyAlgo

Constructor Detail

LocationIndexTree

public LocationIndexTree(Graph g,
                         Directory dir)

Parameters:

g - the graph for which this index should do the lookup based on latitude,longitude.

Method Detail

getMinResolutionInMeter

public int getMinResolutionInMeter()

setMinResolutionInMeter

public LocationIndexTree setMinResolutionInMeter(int minResolutionInMeter)

Minimum width in meter of one tile. Decrease this if you need faster queries, but keep in mind that then queries with different coordinates are more likely to fail.

setMaxRegionSearch

public LocationIndexTree setMaxRegionSearch(int numTiles)

Searches also neighbouring tiles until the maximum distance from the query point is reached (minResolutionInMeter*regionAround). Set to 1 for to force avoiding a fall back, good if you have strict performance and lookup-quality requirements. Default is 4.

setResolution

public LocationIndex setResolution(int minResolutionInMeter)

Description copied from interface: LocationIndex

Integer value to specify the resolution of this location index. The higher the better the resolution.

Specified by:

setResolution in interface LocationIndex

setApproximation

public LocationIndex setApproximation(boolean approx)

Specified by:

setApproximation in interface LocationIndex

Parameters:

approx - false if initialization and querying should be faster but less precise.

create

public LocationIndexTree create(long size)

Description copied from interface: Storable

Creates the underlying storage. First operation if it cannot be loaded.

Specified by:

create in interface Storable<LocationIndex>

loadExisting

public boolean loadExisting()

Specified by:

loadExisting in interface Storable<LocationIndex>

Returns:

true if successfully loaded from persistent storage.

flush

public void flush()

Description copied from interface: Storable

This method makes sure that the underlying data is written to the storage. Keep in mind that a disc normally has an IO cache so that flush() is (less) probably not save against power loses.

Specified by:

flush in interface Storable<LocationIndex>

prepareIndex

public LocationIndex prepareIndex()

Description copied from interface: LocationIndex

Creates this index - to be called once before findID.

Specified by:

prepareIndex in interface LocationIndex

close

public void close()

Description copied from interface: Storable

This method makes sure that the underlying used resources are released. WARNING: it does NOT flush on close!

Specified by:

close in interface Storable<LocationIndex>

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

isClosed

public boolean isClosed()

Specified by:

isClosed in interface Storable<LocationIndex>

getCapacity

public long getCapacity()

Specified by:

getCapacity in interface Storable<LocationIndex>

Returns:

the allocated storage size in bytes

setSegmentSize

public void setSegmentSize(int bytes)

Specified by:

setSegmentSize in interface LocationIndex

getDeltaLat

public double getDeltaLat()

Provide info about tilesize for testing / visualization

getDeltaLon

public double getDeltaLon()

query

public void query(BBox queryShape,
                  LocationIndex.Visitor function)

Description copied from interface: LocationIndex

This method explores the nodes in this LocationIndex with the specified Visitor. It guarantees to visit all unique nodes included in the queryBBox but it could visit more.

Specified by:

query in interface LocationIndex

findClosest

public QueryResult findClosest(double queryLat,
                               double queryLon,
                               EdgeFilter edgeFilter)

Description copied from interface: LocationIndex

This method returns the closest QueryResult for the specified location (lat, lon) and only if the filter accepts the edge as valid candidate (e.g. filtering away car-only results for bike search)

Specified by:

findClosest in interface LocationIndex

edgeFilter - if a graph supports multiple vehicles we have to make sure that the entry node into the graph is accessible from a selected vehicle. E.g. if you have a FOOT-query do:

DefaultEdgeFilter.allEdges(footFlagEncoder);

Returns:

An object containing the closest node and edge for the specified location. The node id has at least one edge which is accepted from the specified edgeFilter. If nothing is found the method QueryResult.isValid will return false.

findNClosest

public List<QueryResult> findNClosest(double queryLat,
                                      double queryLon,
                                      EdgeFilter edgeFilter,
                                      double radius)

Returns all edges that are within the specified radius around the queried position. Searches at most 9 cells to avoid performance problems. Hence, if the radius is larger than the cell width then not all edges might be returned.

TODO: either clarify the method name and description (to only search e.g. 9 tiles) or refactor so it can handle a radius larger than 9 tiles. Also remove reference to 'NClosest', which is misleading, and don't always return at least one value. See map-matching #65. TODO: tidy up logic - see comments in graphhopper #994.

Parameters:

radius - in meters