Class to allow the division of a set of 2d spatial objects into a coarser grid for
efficient spatial indexing. The collection is a set, so will contain a unique set of
objects. Efficient retrieval is achieved by using the get() method that
will return only those items that are within a fixed distance of a given location. That
fixed distance is determined by the radius of the hash grid. The radius should be
set to the maximum search distance that an application is likely to need when performing
a spatial query. Generally, the smaller the radius the quicker the retrieval.

Methods inherited from interface java.util.Collection

Methods inherited from interface java.lang.Iterable

Constructor Detail

HashGrid

Creates a hash grid capable of storing items located within a rectangle between (0,0) and
(maxX,maxY) with a grid resolution determined by the radius.

Parameters:

maxX - Largest x coordinate of locatable objects.

maxY - Largest y coordinate of locatable objects.

radius - Size of 1 grid cell in the same units as the preceding min and max parameters. If 0 or negative
the HashGrid defaults to a radius of one tenth of the width of the grid. For optimum performance,
the radius should be set to the maximum search distance of any spatial object detection. If it
is set to be less than this, some adjacent neighbours may be missed when searching. If greater
than this, searching will return more neighbours than necessary and impede performance for
dense collections of locatable objects.

HashGrid

Creates a hash grid capable of storing items located within a rectangle between (minX,minY)
and (maxX,maxY) with a grid resolution determined by the radius.

Parameters:

minX - Smallest x coordinate of locatable objects.

minY - Smallest y coordinate of locatable objects.

maxX - Largest x coordinate of locatable objects.

maxY - Largest y coordinate of locatable objects.

radius - Size of 1 grid cell in the same units as the preceding min and max parameters. If 0 or negative
the HashGrid defaults to a radius of one tenth of the width of the grid. For optimum performance,
the radius should be set to the maximum search distance of any spatial object detection. If it
is set to be less than this, some adjacent neighbours may be missed when searching. If greater
than this, searching will return more neighbours than necessary and impede performance for
dense collections of locatable objects.

getAll

Returns a set of all objects stored in the hash grid. There is no guarantee of the order of
items returned within this set.

Returns:

Set of unique objects stored by the hash grid.

updateAll

public void updateAll()

Updates the positions of all items in the hash grid so that their gridded location
reflects the location stored inside the Locatable objects. This method
is useful if all or many of the objects have changed location since being added to
the hash grid. If only one object has changed consider calling update(E obj).

updateAll

public void updateAll(float newRadius)

Updates the positions of all items in the hash grid so that their gridded location
reflects the location stored inside the Locatable objects. This version
also sets a new grid resolution implied by the newRadius value. This should
represent the maximum search distance used when calling get(PVector).

Parameters:

newRadius - New grid cell radius corresponding to maximum search distance. No change
to the radius is made if the value is 0 or negative.

update

Updates the positions of the given item in the hash grid so that its gridded location
reflects its new location. This method is useful if a Locatable object has
changed its position, but most of the other objects in the hash grid have not.

add

Adds a locatable object to the grid. Unlike add(E) this allows a locatable
object to be added at a location other than it's 'natural' one. Note that the object being
added must implement the Locatable interface, otherwise a ClassCastException
will be thrown.

Parameters:

obj - Locatable object to add to the hash grid.

loc - Location of the object to add to the grid.

Returns:

True if the collection has changed as a result of the object being added.

clear

contains

public boolean contains(java.lang.Object obj)

Reports whether the hash grid contains the given object. While this will return results as expected,
for more efficient query consider using contains(obj,location) instead to limit search to
within the search radius.

containsAll

public boolean containsAll(java.util.Collection<?> collection)

Reports whether the hash grid contains all of the objects contained in the given collection. Note
that this operation ignores the grid cells of the objects. To limit a search to a particular spatial
region call get(location) and search the returned collection.

True if the hash grid contains all of the items in the given collection.

equals

public boolean equals(java.lang.Object obj)

Reports whether this collection is equal to the given object. If the given object is another HashGrid
the comparison is performed on the Sets contained in the hash grids. In other words, it is independent
of the spatial locations of the objects stored in the hash grid. The only other type of object that could possibly
return true would be a Set.

iterator

Provides an iterator to iterate through all the items stored in this hash grid. Note that this will not
guarantee iterating in any spatial order. To perform a spatial iteration, make calls to get(location)
in some spatial order and then iterate though the resulting collections.

retainAll

public boolean retainAll(java.util.Collection<?> collection)

Would strip all items from the hash grid apart from those contained in the given collection but
is currently not supported by the hash grid. To limit the operation to certain grid
cells, call get(location) and perform the retainsAll() on the returned collection.

toArray

public <T> T[] toArray(T[] a)

Provides an array representation of the items in this hash grid. Note that this does not double count
any items that may have been repeated in more than one grid cell and does not guarantee any form of
spatial ordering of items. The runtime type of the returned array is that of the given array. If the
collection fits in the given array, it is returned therein. Otherwise, a new array is allocated with
the runtime type of the given array and the size of this collection. If this collection fits in the
given array with room to spare (i.e. the array has more elements than this collection), the element
in the array immediately following the end of the collection is set to null. (This is useful in
determining the length of this collection only if the caller knows that this collection does not
contain any null elements.)