Package org.tinspin.index.qthypercube2

Class QuadTreeKD2<T>

java.lang.Object

org.tinspin.index.qthypercube2.QuadTreeKD2<T>

Type Parameters:

T - Value type.

All Implemented Interfaces:

Index<T>, PointIndex<T>, PointIndexMM<T>

public class QuadTreeKD2<T>
extends Object
implements PointIndex<T>, PointIndexMM<T>

This is a MX-quadtree implementation with configurable maximum depth, maximum nodes size, and (if desired) automatic guessing of root rectangle. For navigation during insert/delete/update/queries, it uses hypercube navigation as described by T. Zaeschke and M. Norrie, "Efficient Z-Ordered Traversal of Hypercube Indexes, BTW proceedings, 2017. This version of the quadtree stores for each node only the center point and the distance (radius) to the edges. This reduces space requirements but increases problems with numerical precision. Overall it is more space efficient and slightly faster. This version 2 of the QuadtreeHC reduces memory consumption allowing directory nodes to contain data entries. With version 1, there were many nodes with just one data entry because the parent directory node could not hold date entries. With version two a directory node (which contains a hypercube array) will only create a subnode if a quadrant has to mhold more than one data entry.

Author:

ztilmann

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	QuadTreeKD2.QStats	Statistics container class.

Field Summary

Fields

Modifier and Type	Field	Description
static boolean	DEBUG
static boolean	ENABLE_HCI_1	Enable basic HCI navigation with Algo #1 isInI(), for example for window queries.
static boolean	ENABLE_HCI_2	Enable basic HCI navigation with Algo #2 inc(), for example for window queries.

Method Summary

Modifier and Type	Method	Description
void	clear()	Removes all elements from the tree.
boolean	contains(double[] key, T value)	Lookup an entry, using exact match.
boolean	containsExact(double[] key)	Check whether a given key exists.
static <T> QuadTreeKD2<T>	create(int dims)
static <T> QuadTreeKD2<T>	create(int dims, int maxNodeSize)
static <T> QuadTreeKD2<T>	create(int dims, int maxNodeSize, double[] center, double radius)
int	getDepth()
int	getDims()
int	getNodeCount()
protected QNode<T>	getRoot()
QuadTreeKD2.QStats	getStats()
void	insert(double[] key, T value)	Insert a key-value pair.
QueryIterator<PointEntry<T>>	iterator()
List<QEntryDist<T>>	knnQuery(double[] center, int k)	Deprecated.
List<QEntryDist<T>>	knnQuery(double[] center, int k, PointDistanceFunction distFn)	Deprecated.
QueryIterator<PointEntry<T>>	query(double[] point)	Lookup an entries at a given coordinate.
QueryIterator<PointEntry<T>>	query(double[] min, double[] max)	Query the tree, returning all points in the axis-aligned rectangle between 'min' and 'max'.
PointEntryDist<T>	query1NN(double[] center)	Finds the nearest neighbor.
T	queryExact(double[] key)	Get the value associates with the key.
QueryIteratorKNN<PointEntryDist<T>>	queryKNN(double[] center, int k)	Finds the nearest neighbor.
QueryIteratorKNN<PointEntryDist<T>>	queryKNN(double[] center, int k, PointDistanceFunction distFn)	Finds the nearest neighbor.
T	remove(double[] key)	Remove a key.
boolean	remove(double[] key, T value)	Remove *one* entry with the given value.
boolean	removeIf(double[] key, Predicate<PointEntry<T>> condition)	Remove *one* entry with the given condition.
int	size()	Get the number of key-value pairs in the tree.
String	toString()
String	toStringTree()	Returns a printable list of the tree.
T	update(double[] oldKey, double[] newKey)	Reinsert the key.
boolean	update(double[] oldKey, double[] newKey, T value)	Reinsert the key.
T	updateIf(double[] oldKey, double[] newKey, Predicate<PointEntry<T>> condition)	Reinsert the key.

Methods inherited from class java.lang.Object

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

Field Detail

ENABLE_HCI_1

public static boolean ENABLE_HCI_1

Enable basic HCI navigation with Algo #1 isInI(), for example for window queries.

ENABLE_HCI_2

public static boolean ENABLE_HCI_2

Enable basic HCI navigation with Algo #2 inc(), for example for window queries.

DEBUG

public static final boolean DEBUG

See Also:

Constant Field Values

Method Detail

create

public static <T> QuadTreeKD2<T> create(int dims)

create

public static <T> QuadTreeKD2<T> create(int dims,
                                        int maxNodeSize)

create

public static <T> QuadTreeKD2<T> create(int dims,
                                        int maxNodeSize,
                                        double[] center,
                                        double radius)

insert

public void insert(double[] key,
                   T value)

Insert a key-value pair.

Specified by:

insert in interface PointIndex<T>

Specified by:

insert in interface PointIndexMM<T>

Parameters:

key - the key

value - the value

containsExact

public boolean containsExact(double[] key)

Check whether a given key exists.

Parameters:

key - the key to check

Returns:

true iff the key exists

queryExact

public T queryExact(double[] key)

Get the value associates with the key.

Specified by:

queryExact in interface PointIndex<T>

Parameters:

key - the key to look up

Returns:

the value for the key or 'null' if the key was not found

contains

public boolean contains(double[] key,
                        T value)

Description copied from interface: PointIndexMM

Lookup an entry, using exact match.

Specified by:

contains in interface PointIndexMM<T>

Parameters:

key - the point

value - the value

Returns:

`true` if an entry was found, otherwise `false`.

remove

public T remove(double[] key)

Remove a key.

Specified by:

remove in interface PointIndex<T>

Parameters:

key - key to remove

Returns:

the value associated with the key or 'null' if the key was not found

remove

public boolean remove(double[] key,
                      T value)

Description copied from interface: PointIndexMM

Remove *one* entry with the given value.

Specified by:

remove in interface PointIndexMM<T>

Parameters:

key - the point

value - only entries with this value are removed

Returns:

the value of the entry or null if the entry was not found

removeIf

public boolean removeIf(double[] key,
                        Predicate<PointEntry<T>> condition)

Description copied from interface: PointIndexMM

Remove *one* entry with the given condition.

Specified by:

removeIf in interface PointIndexMM<T>

Parameters:

key - the point

condition - the condition required for removing an entry

Returns:

the value of the entry or null if the entry was not found

update

public T update(double[] oldKey,
                double[] newKey)

Reinsert the key.

Specified by:

update in interface PointIndex<T>

Parameters:

oldKey - old key

newKey - new key

Returns:

the value associated with the key or 'null' if the key was not found.

update

public boolean update(double[] oldKey,
                      double[] newKey,
                      T value)

Reinsert the key.

Specified by:

update in interface PointIndexMM<T>

Parameters:

oldKey - old key

newKey - new key

value - the value of the entry that should be updated.

Returns:

the value associated with the key or 'null' if the key was not found.

updateIf

public T updateIf(double[] oldKey,
                  double[] newKey,
                  Predicate<PointEntry<T>> condition)

Reinsert the key.

Parameters:

oldKey - old key

newKey - new key

condition - A predicate that must evaluate to 'true' for an entry to be updated.

Returns:

the value associated with the key or 'null' if the key was not found.

size

public int size()

Get the number of key-value pairs in the tree.

Specified by:

size in interface Index<T>

Returns:

the size

clear

public void clear()

Removes all elements from the tree.

Specified by:

clear in interface Index<T>

query

public QueryIterator<PointEntry<T>> query(double[] point)

Description copied from interface: PointIndexMM

Lookup an entries at a given coordinate.

Specified by:

query in interface PointIndexMM<T>

Parameters:

point - the point

Returns:

an iterator over all entries at the given coordinate.

See Also:

PointIndexMM.query(double[])

query

public QueryIterator<PointEntry<T>> query(double[] min,
                                          double[] max)

Query the tree, returning all points in the axis-aligned rectangle between 'min' and 'max'.

Specified by:

query in interface PointIndex<T>

Specified by:

query in interface PointIndexMM<T>

Parameters:

min - lower left corner of query

max - upper right corner of query

Returns:

all entries in the rectangle

query1NN

public PointEntryDist<T> query1NN(double[] center)

Description copied from interface: PointIndex

Finds the nearest neighbor. This uses euclidean distance. Other distance types can only be specified directly on the index implementations.

Specified by:

query1NN in interface PointIndex<T>

Specified by:

query1NN in interface PointIndexMM<T>

Parameters:

center - center point

Returns:

the nearest neighbor

queryKNN

public QueryIteratorKNN<PointEntryDist<T>> queryKNN(double[] center,
                                                    int k,
                                                    PointDistanceFunction distFn)

Description copied from interface: PointIndexMM

Finds the nearest neighbor. This uses Euclidean distance. Other distance types can only be specified directly on the index implementations.

Specified by:

queryKNN in interface PointIndexMM<T>

Parameters:

center - center point

k - number of neighbors

distFn - the point distance function to be used

Returns:

Iterator over query result

See Also:

PointIndexMM.queryKNN(double[], int, PointDistanceFunction)

knnQuery

@Deprecated
public List<QEntryDist<T>> knnQuery(double[] center,
                                    int k)

Deprecated.

knnQuery

@Deprecated
public List<QEntryDist<T>> knnQuery(double[] center,
                                    int k,
                                    PointDistanceFunction distFn)

Deprecated.

toStringTree

public String toStringTree()

Returns a printable list of the tree.

Specified by:

toStringTree in interface Index<T>

Returns:

the tree as String

toString

public String toString()

Overrides:

toString in class Object

getStats

public QuadTreeKD2.QStats getStats()

Specified by:

getStats in interface Index<T>

Returns:

Collect and return some index statistics. Note that indexes are not required to fill all fields. Also, individual indexes may use subclasses with additional fields.

getDims

public int getDims()

Specified by:

getDims in interface Index<T>

Returns:

the number of dimensions

iterator

public QueryIterator<PointEntry<T>> iterator()

Specified by:

iterator in interface PointIndex<T>

Specified by:

iterator in interface PointIndexMM<T>

Returns:

An iterator over all entries.

queryKNN

public QueryIteratorKNN<PointEntryDist<T>> queryKNN(double[] center,
                                                    int k)

Description copied from interface: PointIndex

Finds the nearest neighbor. This uses euclidean distance. Other distance types can only be specified directly on the index implementations.

Specified by:

queryKNN in interface PointIndex<T>

Specified by:

queryKNN in interface PointIndexMM<T>

Parameters:

center - center point

k - number of neighbors

Returns:

list of nearest neighbors

getNodeCount

public int getNodeCount()

Specified by:

getNodeCount in interface Index<T>

getDepth

public int getDepth()

Specified by:

getDepth in interface Index<T>

getRoot

protected QNode<T> getRoot()