sim.field.grid
Class SparseGrid3D

java.lang.Object
  extended by sim.field.SparseField
      extended by sim.field.grid.SparseGrid3D
All Implemented Interfaces:
java.io.Serializable

public class SparseGrid3D
extends SparseField

A storage facility for sparse objects in discrete 3D space, using HashMaps. SparseGrid3D differs from ObjectGrid3D in several respects:

Generally speaking, if you have a grid of objects, one per location, you should use an ObjectGrid3D. If you have a large grid occupied by a few objects, or those objects can pile up on the same grid location, you should use a SparseGrid3D.

In either case, you might consider storing the location of an object IN THE OBJECT ITSELF if you need to query for the object location often -- it's faster than the hashtable lookup in SparseGrid3D, and certainly faster than searching the entire array of an ObjectGrid3D.

Boundaries. SparseGrid3D has no boundaries at all. width and height and length exist only to allow you to define pseudo-boundaries for toroidal computation; and to provide typical bounds for visualization. But you can attach any coordinate as a location for an object with no restrictions. Setting and getting an object and its Location. The method setObjectLocation(...) methods set the location of the object (to an Int3D or an location). The method getObjectsAtLocation(Object location), inherited from SparseField, returns a Bag (which you MUST NOT modify) containing all objects at a given location (which must be provided in the form of an Int3D or MutableInt3D). The numObjectsAtLocation(location) method returns the number of such objects. The getObjectsAtLocations(Bag locations, Bag putInHere) gathers objects at a variety of locations and puts them in the bag you provide. The getAllObjects() method returns all objects in a bag you must NOT modiify. The removeObjectsAtLocation(Object location) method removes and returns all objects at a given location (defined as an Int3D or MutableDouble3D). The exists method tells you if the object exists in the field.

Neighborhood Lookups. The method getObjectsAtLocationOfObject returns all Objects at the same location as the provided object (in a Bag, which must NOT modify). The various getNeighbors...Distance(...) methods return all locations defined by certain distance bounds, or all the objects stored at those locations. They are expensive to compute and it may be wiser to compute them by hand if there aren't many.

See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class sim.field.SparseField
SparseField.LocationAndIndex
 
Field Summary
protected  int height
           
protected  int length
           
protected  int width
           
 
Fields inherited from class sim.field.SparseField
allObjects, INITIAL_BAG_SIZE, LARGE_BAG_RATIO, locationAndIndexHash, MIN_BAG_SIZE, objectHash, removeEmptyBags, replaceLargeBags, REPLACEMENT_BAG_RATIO
 
Constructor Summary
SparseGrid3D(int width, int height, int length)
           
 
Method Summary
 int getHeight()
          Returns the height of the grid
 int getLength()
          Returns the length of the grid
 Bag getNeighborsHamiltonianDistance(int x, int y, int z, int dist, boolean toroidal, Bag result, IntBag xPos, IntBag yPos, IntBag zPos)
          Gets all neighbors of a location that satisfy abs(x-X) + abs(y-Y) + abs(z-Z) <= dist.
 void getNeighborsHamiltonianDistance(int x, int y, int z, int dist, boolean toroidal, IntBag xPos, IntBag yPos, IntBag zPos)
           
 Bag getNeighborsMaxDistance(int x, int y, int z, int dist, boolean toroidal, Bag result, IntBag xPos, IntBag yPos, IntBag zPos)
          Gets all neighbors of a location that satisfy max( abs(x-X) , abs(y-Y), abs(z-Z) ) <= dist.
 void getNeighborsMaxDistance(int x, int y, int z, int dist, boolean toroidal, IntBag xPos, IntBag yPos, IntBag zPos)
           
 Int3D getObjectLocation(java.lang.Object obj)
          Returns the object location, or null if there is no such object.
 Double3D getObjectLocationAsDouble3D(java.lang.Object obj)
          Returns the object location as a Double3D, or as null if there is no such object.
 Bag getObjectsAtLocation(int x, int y, int z)
          Returns a bag containing all the objects at a given location -- which MIGHT be empty or MIGHT be null (which should also be interpreted as "empty") when there are no objects at the location.
 Bag getObjectsAtLocations(IntBag xPos, IntBag yPos, IntBag zPos, Bag result)
          For each location, puts all such objects into the result bag.
 int getWidth()
          Returns the width of the grid
 int numObjectsAtLocation(int x, int y, int z)
          Returns the number of objects stored in the grid at the given location.
 Bag removeObjectsAtLocation(int x, int y, int z)
          Removes all the objects stored at the given location and returns them as a Bag (which you are free to modify).
 boolean setObjectLocation(java.lang.Object obj, Int3D location)
          Changes the location of an object, or adds if it doesn't exist yet.
 boolean setObjectLocation(java.lang.Object obj, int x, int y, int z)
          Changes the location of an object, or adds if it doesn't exist yet.
 int stx(int x)
           
 int sty(int y)
           
 int stz(int z)
           
 int stz(int z, int length)
           
 int tx(int x)
           
 int ty(int y)
           
 int tz(int z)
           
 
Methods inherited from class sim.field.SparseField
clear, exists, getAllObjects, getObjectIndex, getObjectsAtLocation, getObjectsAtLocationOfObject, getObjectsAtLocations, getRawObjectLocation, iterator, locationBagIterator, numObjectsAtLocation, numObjectsAtLocationOfObject, remove, removeObjectsAtLocation, setObjectLocation
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

width

protected int width

height

protected int height

length

protected int length
Constructor Detail

SparseGrid3D

public SparseGrid3D(int width,
                    int height,
                    int length)
Method Detail

getWidth

public int getWidth()
Returns the width of the grid


getHeight

public int getHeight()
Returns the height of the grid


getLength

public int getLength()
Returns the length of the grid


tx

public final int tx(int x)

ty

public final int ty(int y)

tz

public final int tz(int z)

stx

public int stx(int x)

sty

public int sty(int y)

stz

public int stz(int z)

stz

public final int stz(int z,
                     int length)

numObjectsAtLocation

public int numObjectsAtLocation(int x,
                                int y,
                                int z)
Returns the number of objects stored in the grid at the given location.


getObjectsAtLocation

public Bag getObjectsAtLocation(int x,
                                int y,
                                int z)
Returns a bag containing all the objects at a given location -- which MIGHT be empty or MIGHT be null (which should also be interpreted as "empty") when there are no objects at the location. You should NOT MODIFY THIS BAG. This is the actual container bag, and modifying it will almost certainly break the Sparse Field object. If you want to modify the bag, make a copy and modify the copy instead, using something along the lines of new Bag(foo.getObjectsAtLocation(location)) . Furthermore, changing values in the Sparse Field may result in a different bag being used -- so you should not rely on this bag staying valid.


getObjectLocationAsDouble3D

public Double3D getObjectLocationAsDouble3D(java.lang.Object obj)
Returns the object location as a Double3D, or as null if there is no such object.


getObjectLocation

public Int3D getObjectLocation(java.lang.Object obj)
Returns the object location, or null if there is no such object.


removeObjectsAtLocation

public Bag removeObjectsAtLocation(int x,
                                   int y,
                                   int z)
Removes all the objects stored at the given location and returns them as a Bag (which you are free to modify).


setObjectLocation

public boolean setObjectLocation(java.lang.Object obj,
                                 int x,
                                 int y,
                                 int z)
Changes the location of an object, or adds if it doesn't exist yet. Returns false if the object is null (null objects cannot be put into the grid).


setObjectLocation

public boolean setObjectLocation(java.lang.Object obj,
                                 Int3D location)
Changes the location of an object, or adds if it doesn't exist yet. Returns false if the object is null (null objects cannot be put into the grid) or if the location is null.


getNeighborsMaxDistance

public void getNeighborsMaxDistance(int x,
                                    int y,
                                    int z,
                                    int dist,
                                    boolean toroidal,
                                    IntBag xPos,
                                    IntBag yPos,
                                    IntBag zPos)

getNeighborsHamiltonianDistance

public void getNeighborsHamiltonianDistance(int x,
                                            int y,
                                            int z,
                                            int dist,
                                            boolean toroidal,
                                            IntBag xPos,
                                            IntBag yPos,
                                            IntBag zPos)

getNeighborsMaxDistance

public Bag getNeighborsMaxDistance(int x,
                                   int y,
                                   int z,
                                   int dist,
                                   boolean toroidal,
                                   Bag result,
                                   IntBag xPos,
                                   IntBag yPos,
                                   IntBag zPos)
Gets all neighbors of a location that satisfy max( abs(x-X) , abs(y-Y), abs(z-Z) ) <= dist. This region forms a cube 2*dist+1 cells across, centered at (X,Y,Z). If dist==1, this is equivalent to the twenty-six neighbors surrounding (X,Y,Z), plus (X,Y) itself. Places each x, y, and z value of these locations in the provided IntBags xPos, yPos, and zPos, clearing the bags first. Then places into the result Bag the objects at each of those locations clearning it first. Returns the result Bag (constructing one if null had been passed in). null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.


getNeighborsHamiltonianDistance

public Bag getNeighborsHamiltonianDistance(int x,
                                           int y,
                                           int z,
                                           int dist,
                                           boolean toroidal,
                                           Bag result,
                                           IntBag xPos,
                                           IntBag yPos,
                                           IntBag zPos)
Gets all neighbors of a location that satisfy abs(x-X) + abs(y-Y) + abs(z-Z) <= dist. This region forms an octohedron 2*dist+1 cells from point to opposite point inclusive, centered at (X,Y,Y). If dist==1 this is equivalent to the six neighbors above, below, left, and right, front, and behind (X,Y,Z)), plus (X,Y,Z) itself. Places each x, y, and z value of these locations in the provided IntBags xPos, yPos, and zPos, clearing the bags first. Then places into the result Bag the objects at each of those locations clearning it first. Returns the result Bag (constructing one if null had been passed in). null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.


getObjectsAtLocations

public Bag getObjectsAtLocations(IntBag xPos,
                                 IntBag yPos,
                                 IntBag zPos,
                                 Bag result)
For each location, puts all such objects into the result bag. Returns the result bag. If the provided result bag is null, one will be created and returned.