Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## sim.field.grid
Class SparseGrid3D

    java.lang.Object
      sim.field.SparseField
          sim.field.grid.SparseGrid3D

All Implemented Interfaces:
  java.io.Serializable, Grid3D, SparseField3D

    public class SparseGrid3D

extends SparseField
implements Grid3D, SparseField3D

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

- SparseGrid3D can store more than one object at a location. ObjectGrid3D cannot.
- ObjectGrid3D can store an object at more than one location (though it's bad form!).
- SparseGrid3D can efficiently (O(1)) tell you the location of an object.
- SparseGrid3D can efficiently (O(#objs)) scan through all objects. The best you can do with ObjectGrid3D is search its array (which might have many empty slots).
- Storing an object, finding its location, or changing its location, in a SparseGrid3D is O(1) but requires several Map lookups and/or removes, which has a significant constant overhead.
- SparseGrid3D can associate objects with any 3D integer location. ObjectGrid3D's locations are restricted to be within its array.

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, ANY_SIZE, INITIAL_BAG_SIZE, LARGE_BAG_RATIO, locationAndIndexHash, MIN_BAG_SIZE, objectHash, removeEmptyBags, replaceLargeBags, REPLACEMENT_BAG_RATIO`

Fields inherited from interface sim.field.grid.Grid3D
`ALL, ANY, ANY_SIZE, BOUNDED, CENTER, TOROIDAL, UNBOUNDED`

Constructor Summary
`SparseGrid3D(int width, int height, int length)`
`SparseGrid3D(SparseGrid3D values)`

Method Summary
`Double3D` | `getDimensions()` Returns the width and height of the sparse field as a Double3D
`int` | `getHeight()` Returns the height of the grid
`int` | `getLength()` Returns the length of the grid
`void` | `getMooreLocations(int x, int y, int z, int dist, int mode, boolean includeOrigin, 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.
`Bag` | `getMooreNeighbors(int x, int y, int z, int dist, int mode, boolean includeOrigin, Bag result, IntBag xPos, IntBag yPos, IntBag zPos)`
`Bag` | `getMooreNeighborsAndLocations(int x, int y, int z, int dist, int mode, boolean includeOrigin, 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.
`Bag` | `getNeighborsHamiltonianDistance(int x, int y, int z, int dist, boolean toroidal, Bag result, IntBag xPos, IntBag yPos, IntBag zPos)` Deprecated.
`void` | `getNeighborsHamiltonianDistance(int x, int y, int z, int dist, boolean toroidal, IntBag xPos, IntBag yPos, IntBag zPos)` Deprecated.
`Bag` | `getNeighborsMaxDistance(int x, int y, int z, int dist, boolean toroidal, Bag result, IntBag xPos, IntBag yPos, IntBag zPos)`
`void` | `getNeighborsMaxDistance(int x, int y, int z, int dist, boolean toroidal, IntBag xPos, IntBag yPos, IntBag zPos)` Deprecated.
`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.
`void` | `getRadialLocations(int x, int y, int z, double dist, int mode, boolean includeOrigin, IntBag xPos, IntBag yPos, IntBag zPos)` Gets all neighbors overlapping with a spherical region centered at (X,Y,Z) and with a radius of dist.
`void` | `getRadialLocations(int x, int y, int z, double dist, int mode, boolean includeOrigin, int measurementRule, boolean closed, IntBag xPos, IntBag yPos, IntBag zPos)` Gets all neighbors overlapping with a spherical region centered at (X,Y,Z) and with a radius of dist.
`Bag` | `getRadialNeighbors(int x, int y, int z, int dist, int mode, boolean includeOrigin, Bag result, IntBag xPos, IntBag yPos, IntBag zPos)`
`Bag` | `getRadialNeighbors(int x, int y, int z, int dist, int mode, boolean includeOrigin, int measurementRule, boolean closed, Bag result, IntBag xPos, IntBag yPos, IntBag zPos)`
`Bag` | `getRadialNeighborsAndLocations(int x, int y, int z, int dist, int mode, boolean includeOrigin, Bag result, IntBag xPos, IntBag yPos, IntBag zPos)`
`Bag` | `getRadialNeighborsAndLocations(int x, int y, int z, int dist, int mode, boolean includeOrigin, int measurementRule, boolean closed, Bag result, IntBag xPos, IntBag yPos, IntBag zPos)`
`void` | `getVonNeumannLocations(int x, int y, int z, int dist, int mode, boolean includeOrigin, IntBag xPos, IntBag yPos, IntBag zPos)` Gets all neighbors of a location that satisfy abs(x-X) + abs(y-Y) + abs(z-Z) <= dist.
`Bag` | `getVonNeumannNeighbors(int x, int y, int z, int dist, int mode, boolean includeOrigin, 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.
`Bag` | `getVonNeumannNeighborsAndLocations(int x, int y, int z, int dist, int mode, boolean includeOrigin, 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.
`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).
`protected void` | `removeOrigin(int x, int y, int z, IntBag xPos, IntBag yPos, IntBag zPos)`
`protected void` | `removeOriginToroidal(int x, int y, int z, IntBag xPos, IntBag yPos, IntBag zPos)`
`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)` Simple [and fast] toroidal x.
`int` | `sty(int y)` Simple [and fast] toroidal y.
`int` | `stz(int z)` Simple [and fast] toroidal z.
`int` | `stz(int z, int length)`
`int` | `tx(int x)` Toroidal x.
`int` | `ty(int y)` Toroidal y.
`int` | `tz(int z)` Toroidal z.

Methods inherited from class sim.field.SparseField
`buildMap, buildMap, clear, exists, getAllObjects, getObjectIndex, getObjectsAtLocation, getObjectsAtLocationOfObject, getObjectsAtLocations, getRawObjectLocation, getRawObjectsAtLocation, iterator, locationBagIterator, numObjectsAtLocation, numObjectsAtLocationOfObject, remove, removeObjectsAtLocation, setObjectLocation, size`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface sim.field.grid.Grid3D
`buildMap, buildMap`

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)

### SparseGrid3D

    public SparseGrid3D(SparseGrid3D values)

Method Detail

### getWidth

    public int getWidth()

  Returns the width of the grid

  Specified by:
    `getWidth` in interface `Grid3D`

### getHeight

    public int getHeight()

  Returns the height of the grid

  Specified by:
    `getHeight` in interface `Grid3D`

### getLength

    public int getLength()

  Returns the length of the grid

  Specified by:
    `getLength` in interface `Grid3D`

### tx

    public final int tx(int x)

  Description copied from interface: `Grid3D`
  Toroidal x. The following definition:
  final int length = this.length;
  if (z >= 0) return (z % length);
  final int length2 = (z % length) + length;
  if (length2 < length) return length2;
  return 0;
  ... produces the correct code and is 27 bytes, so it's likely to be inlined in Hotspot for 1.4.1.

  Specified by:
    `tx` in interface `Grid3D`

### ty

    public final int ty(int y)

  Description copied from interface: `Grid3D`
  Toroidal y. The following definition:
  final int length = this.length;
  if (z >= 0) return (z % length);
  final int length2 = (z % length) + length;
  if (length2 < length) return length2;
  return 0;
  ... produces the correct code and is 27 bytes, so it's likely to be inlined in Hotspot for 1.4.1.

  Specified by:
    `ty` in interface `Grid3D`

### tz

    public final int tz(int z)

  Description copied from interface: `Grid3D`
  Toroidal z. The following definition:
  final int length = this.length;
  if (z >= 0) return (z % length);
  final int length2 = (z % length) + length;
  if (length2 < length) return length2;
  return 0;
  ... produces the correct code and is 27 bytes, so it's likely to be inlined in Hotspot for 1.4.1.

  Specified by:
    `tz` in interface `Grid3D`

### stx

    public int stx(int x)

  Description copied from interface: `Grid3D`
  Simple [and fast] toroidal x. Use this if the values you'd pass in never stray beyond (-width ... width * 2) not inclusive. It's a bit faster than the full toroidal computation as it uses if statements rather than two modulos. The following definition:
  { int width = this.width; if (x >= 0) { if (x < width) return x; return x - width; } return x + width; }
  ...produces the shortest code (24 bytes) and is inlined in Hotspot for 1.4.1. However in most cases removing the int width = this.width; is likely to be a little faster if most objects are usually within the toroidal region.

  Specified by:
    `stx` in interface `Grid3D`

### sty

    public int sty(int y)

  Description copied from interface: `Grid3D`
  Simple [and fast] toroidal y. Use this if the values you'd pass in never stray beyond (-height ... height * 2) not inclusive. It's a bit faster than the full toroidal computation as it uses if statements rather than two modulos. The following definition:
  { int height = this.height; if (y >= 0) { if (y < height) return y ; return y - height; } return y + height; }
  ...produces the shortest code (24 bytes) and is inlined in Hotspot for 1.4.1. However in most cases removing the int height = this.height; is likely to be a little faster if most objects are usually within the toroidal region.

  Specified by:
    `sty` in interface `Grid3D`

### stz

    public int stz(int z)

  Description copied from interface: `Grid3D`
  Simple [and fast] toroidal z. Use this if the values you'd pass in never stray beyond (-length ... length * 2) not inclusive. It's a bit faster than the full toroidal computation as it uses if statements rather than two modulos. The following definition:
  { int length = this.length; if (z >= 0) { if (z < length) return z ; return z - length; } return z + length; }
  ...produces the shortest code (24 bytes) and is inlined in Hotspot for 1.4.1. However in most cases removing the int length = this.length; is likely to be a little faster if most objects are usually within the toroidal region.

  Specified by:
    `stz` in interface `Grid3D`

### 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.

  Specified by:
    `getObjectLocationAsDouble3D` in interface `SparseField3D`

### 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.

### removeOrigin

    protected void removeOrigin(int x,
                                int y,
                                int z,
                                IntBag xPos,
                                IntBag yPos,
                                IntBag zPos)

### removeOriginToroidal

    protected void removeOriginToroidal(int x,
                                        int y,
                                        int z,
                                        IntBag xPos,
                                        IntBag yPos,
                                        IntBag zPos)

### getNeighborsMaxDistance

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

  Deprecated.

  Description copied from interface: `Grid3D`
  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. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

  This function may only run in two modes: toroidal or bounded. Unbounded lookup is not permitted, and so this function is deprecated: instead you should use the other version of this function which has more functionality. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (0,0,0) to (width, height,length), that is, the width and height of the grid. if "toroidal", then the environment is assumed to be toroidal, that is, wrap-around, and neighbors are computed in this fashion. Toroidal locations will not appear multiple times: specifically, if the neighborhood distance is so large that it wraps completely around the width or height of the box, neighbors will not be counted multiple times. Note that to ensure this, subclasses may need to resort to expensive duplicate removal, so it's not suggested you use so unreasonably large distances.

  The origin -- that is, the (x,y,z) point at the center of the neighborhood -- is always included in the results.

  This function is equivalent to: `getNeighborsMaxDistance(x,y,dist,toroidal ? Grid3D.TOROIDAL : Grid3D.BOUNDED, true, xPos, yPos, zPos);`

  Specified by:
    `getNeighborsMaxDistance` in interface `Grid3D`

### getMooreLocations

    public void getMooreLocations(int x,
                                  int y,
                                  int z,
                                  int dist,
                                  int mode,
                                  boolean includeOrigin,
                                  IntBag xPos,
                                  IntBag yPos,
                                  IntBag zPos)

  Description copied from interface: `Grid3D`
  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. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

  This function may be run in one of three modes: Grid3D.BOUNDED, Grid3D.UNBOUNDED, and GrideD.TOROIDAL. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (0,0,0) to (width, height,length), that is, the width and height of the grid. If "unbounded", then the neighbors are not so restricted. Note that unbounded neighborhood lookup only makes sense if your grid allows locations to actually be outside this box. For example, SparseGrid3D permits this but ObjectGrid3D and DoubleGrid3D and IntGrid3D and DenseGrid3D do not. Finally if "toroidal", then the environment is assumed to be toroidal, that is, wrap-around, and neighbors are computed in this fashion. Toroidal locations will not appear multiple times: specifically, if the neighborhood distance is so large that it wraps completely around the width or height of the box, neighbors will not be counted multiple times. Note that to ensure this, subclasses may need to resort to expensive duplicate removal, so it's not suggested you use so unreasonably large distances.

  You can also opt to include the origin -- that is, the (x,y,z) point at the center of the neighborhood -- in the neighborhood results.

  Specified by:
    `getMooreLocations` in interface `Grid3D`

### getNeighborsHamiltonianDistance

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

  Deprecated.

  Description copied from interface: `Grid3D`
  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. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

  This function may only run in two modes: toroidal or bounded. Unbounded lookup is not permitted, and so this function is deprecated: instead you should use the other version of this function which has more functionality. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (0,0,0) to (width, height,length), that is, the width and height of the grid. if "toroidal", then the environment is assumed to be toroidal, that is, wrap-around, and neighbors are computed in this fashion. Toroidal locations will not appear multiple times: specifically, if the neighborhood distance is so large that it wraps completely around the width or height of the box, neighbors will not be counted multiple times. Note that to ensure this, subclasses may need to resort to expensive duplicate removal, so it's not suggested you use so unreasonably large distances.

  The origin -- that is, the (x,y,z) point at the center of the neighborhood -- is always included in the results.

  This function is equivalent to: `getNeighborsHamiltonianDistance(x,y,dist,toroidal ? Grid3D.TOROIDAL : Grid3D.BOUNDED, true, xPos, yPos, zPos);`

  Specified by:
    `getNeighborsHamiltonianDistance` in interface `Grid3D`

### getVonNeumannLocations

    public void getVonNeumannLocations(int x,
                                       int y,
                                       int z,
                                       int dist,
                                       int mode,
                                       boolean includeOrigin,
                                       IntBag xPos,
                                       IntBag yPos,
                                       IntBag zPos)

  Description copied from interface: `Grid3D`
  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. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

  This function may be run in one of three modes: Grid3D.BOUNDED, Grid3D.UNBOUNDED, and GrideD.TOROIDAL. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (0,0,0) to (width, height,length), that is, the width and height of the grid. If "unbounded", then the neighbors are not so restricted. Note that unbounded neighborhood lookup only makes sense if your grid allows locations to actually be outside this box. For example, SparseGrid3D permits this but ObjectGrid3D and DoubleGrid3D and IntGrid3D and DenseGrid3D do not. Finally if "toroidal", then the environment is assumed to be toroidal, that is, wrap-around, and neighbors are computed in this fashion. Toroidal locations will not appear multiple times: specifically, if the neighborhood distance is so large that it wraps completely around the width or height of the box, neighbors will not be counted multiple times. Note that to ensure this, subclasses may need to resort to expensive duplicate removal, so it's not suggested you use so unreasonably large distances.

  You can also opt to include the origin -- that is, the (x,y,z) point at the center of the neighborhood -- in the neighborhood results.

  Specified by:
    `getVonNeumannLocations` in interface `Grid3D`

### getNeighborsMaxDistance

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

### getMooreNeighbors

    public Bag getMooreNeighbors(int x,
                                 int y,
                                 int z,
                                 int dist,
                                 int mode,
                                 boolean includeOrigin,
                                 Bag result,
                                 IntBag xPos,
                                 IntBag yPos,
                                 IntBag zPos)

### getMooreNeighborsAndLocations

    public Bag getMooreNeighborsAndLocations(int x,
                                             int y,
                                             int z,
                                             int dist,
                                             int mode,
                                             boolean includeOrigin,
                                             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. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

  For each Object which falls within this distance, adds the X position, Y position, Z position, and Object into the xPos, yPos, zPos, and result Bag, clearing them first. Some positions may not appear and that others may appear multiply if multiple objects share that positions. Compare this function with getNeighborsMaxDistance(...). Returns the result Bag. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

  This function may be run in one of three modes: Grid3D.BOUNDED, Grid3D.UNBOUNDED, and Grid3D.TOROIDAL. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (0,0,0) to (width, height, length), that is, the width and height of the grid. If "unbounded", then the neighbors are not so restricted. Note that unbounded neighborhood lookup only makes sense if your grid allows locations to actually be outside this box. For example, SparseGrid3D permits this but ObjectGrid3D and DoubleGrid3D and IntGrid3D and DenseGrid3D do not. Finally if "toroidal", then the environment is assumed to be toroidal, that is, wrap-around, and neighbors are computed in this fashion. Toroidal locations will not appear multiple times: specifically, if the neighborhood distance is so large that it wraps completely around the width or height of the box, neighbors will not be counted multiple times. Note that to ensure this, subclasses may need to resort to expensive duplicate removal, so it's not suggested you use so unreasonably large distances.

  You can also opt to include the origin -- that is, the (x,y) point at the center of the neighborhood -- in the neighborhood results.

### getNeighborsHamiltonianDistance

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

  Deprecated.

  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. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

  Then places into the result Bag any Objects which fall on one of these locations, clearning it first. Note that the order and size of the result Bag may not correspond to the X and Y and Z bags. If you want all three bags to correspond (x, y, z, object) then use getNeighborsAndCorrespondingPositionsHamiltonianDistance(...) Returns the result Bag. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

  This function may only run in two modes: toroidal or bounded. Unbounded lookup is not permitted, and so this function is deprecated: instead you should use the other version of this function which has more functionality. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (0,0,0) to (width, height, length), that is, the width and height and length of the grid. if "toroidal", then the environment is assumed to be toroidal, that is, wrap-around, and neighbors are computed in this fashion. Toroidal locations will not appear multiple times: specifically, if the neighborhood distance is so large that it wraps completely around the width or height of the box, neighbors will not be counted multiple times. Note that to ensure this, subclasses may need to resort to expensive duplicate removal, so it's not suggested you use so unreasonably large distances.

  The origin -- that is, the (x,y,z) point at the center of the neighborhood -- is always included in the results.

  This function is equivalent to: `getNeighborsHamiltonianDistance(x,y,z,dist,toroidal ? Grid3D.TOROIDAL : Grid3D.BOUNDED, true, result, xPos, yPos,zPos);`

### getVonNeumannNeighbors

    public Bag getVonNeumannNeighbors(int x,
                                      int y,
                                      int z,
                                      int dist,
                                      int mode,
                                      boolean includeOrigin,
                                      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. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

  Then places into the result Bag any Objects which fall on one of these locations, clearning it first. Note that the order and size of the result Bag may not correspond to the X and Y and Z bags. If you want all three bags to correspond (x, y, z, object) then use getNeighborsAndCorrespondingPositionsMaxDistance(...) Returns the result Bag. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

  This function may be run in one of three modes: Grid3D.BOUNDED, Grid3D.UNBOUNDED, and Grid3D.TOROIDAL. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (0,0,0) to (width, height), that is, the width and height of the grid. If "unbounded", then the neighbors are not so restricted. Note that unbounded neighborhood lookup only makes sense if your grid allows locations to actually be outside this box. For example, SparseGrid3D permits this but ObjectGrid3D and DoubleGrid3D and IntGrid3D and DenseGrid3D do not. Finally if "toroidal", then the environment is assumed to be toroidal, that is, wrap-around, and neighbors are computed in this fashion. Toroidal locations will not appear multiple times: specifically, if the neighborhood distance is so large that it wraps completely around the width or height of the box, neighbors will not be counted multiple times. Note that to ensure this, subclasses may need to resort to expensive duplicate removal, so it's not suggested you use so unreasonably large distances.

  You can also opt to include the origin -- that is, the (x,y,z) point at the center of the neighborhood -- in the neighborhood results.

### getVonNeumannNeighborsAndLocations

    public Bag getVonNeumannNeighborsAndLocations(int x,
                                                  int y,
                                                  int z,
                                                  int dist,
                                                  int mode,
                                                  boolean includeOrigin,
                                                  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. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

  For each Object which falls within this distance, adds the X position, Y position, Z position, and Object into the xPos, yPos, zPos, and result Bag, clearing them first. Some positions may not appear and that others may appear multiply if multiple objects share that positions. Compare this function with getNeighborsMaxDistance(...). Returns the result Bag. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

  This function may be run in one of three modes: Grid3D.BOUNDED, Grid3D.UNBOUNDED, and Grid3D.TOROIDAL. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (0,0,0) to (width, height, length), that is, the width and height of the grid. If "unbounded", then the neighbors are not so restricted. Note that unbounded neighborhood lookup only makes sense if your grid allows locations to actually be outside this box. For example, SparseGrid3D permits this but ObjectGrid3D and DoubleGrid3D and IntGrid3D and DenseGrid3D do not. Finally if "toroidal", then the environment is assumed to be toroidal, that is, wrap-around, and neighbors are computed in this fashion. Toroidal locations will not appear multiple times: specifically, if the neighborhood distance is so large that it wraps completely around the width or height of the box, neighbors will not be counted multiple times. Note that to ensure this, subclasses may need to resort to expensive duplicate removal, so it's not suggested you use so unreasonably large distances.

  You can also opt to include the origin -- that is, the (x,y) point at the center of the neighborhood -- in the neighborhood results.

### getRadialNeighbors

    public Bag getRadialNeighbors(int x,
                                  int y,
                                  int z,
                                  int dist,
                                  int mode,
                                  boolean includeOrigin,
                                  int measurementRule,
                                  boolean closed,
                                  Bag result,
                                  IntBag xPos,
                                  IntBag yPos,
                                  IntBag zPos)

### getRadialNeighborsAndLocations

    public Bag getRadialNeighborsAndLocations(int x,
                                              int y,
                                              int z,
                                              int dist,
                                              int mode,
                                              boolean includeOrigin,
                                              int measurementRule,
                                              boolean closed,
                                              Bag result,
                                              IntBag xPos,
                                              IntBag yPos,
                                              IntBag zPos)

### 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.

### getRadialLocations

    public void getRadialLocations(int x,
                                   int y,
                                   int z,
                                   double dist,
                                   int mode,
                                   boolean includeOrigin,
                                   IntBag xPos,
                                   IntBag yPos,
                                   IntBag zPos)

  Description copied from interface: `Grid3D`
  Gets all neighbors overlapping with a spherical region centered at (X,Y,Z) and with a radius of dist. The measurement rule is Grid2D.ANY, meaning those cells which overlap at all with the region. The region is closed, meaning that that points which touch on the outer surface of the sphere will be considered members of the region.

  Places each x, y, and z value of these locations in the provided IntBags xPos, yPos, and zPos, clearing the bags first.

  This function may be run in one of three modes: Grid3D.BOUNDED, Grid3D.UNBOUNDED, and GrideD.TOROIDAL. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (0,0,0) to (width, height,length), that is, the width and height of the grid. If "unbounded", then the neighbors are not so restricted. Note that unbounded neighborhood lookup only makes sense if your grid allows locations to actually be outside this box. For example, SparseGrid3D permits this but ObjectGrid3D and DoubleGrid3D and IntGrid3D and DenseGrid3D do not. Finally if "toroidal", then the environment is assumed to be toroidal, that is, wrap-around, and neighbors are computed in this fashion. Toroidal locations will not appear multiple times: specifically, if the neighborhood distance is so large that it wraps completely around the width or height of the box, neighbors will not be counted multiple times. Note that to ensure this, subclasses may need to resort to expensive duplicate removal, so it's not suggested you use so unreasonably large distances.

  You can also opt to include the origin -- that is, the (x,y,z) point at the center of the neighborhood -- in the neighborhood results.

  Specified by:
    `getRadialLocations` in interface `Grid3D`

### getRadialLocations

    public void getRadialLocations(int x,
                                   int y,
                                   int z,
                                   double dist,
                                   int mode,
                                   boolean includeOrigin,
                                   int measurementRule,
                                   boolean closed,
                                   IntBag xPos,
                                   IntBag yPos,
                                   IntBag zPos)

  Description copied from interface: `Grid3D`
  Gets all neighbors overlapping with a spherical region centered at (X,Y,Z) and with a radius of dist. If measurementRule is Grid3D.CENTER, then the measurement rule will be those cells whose centers overlap with the region. If measurementRule is Grid3D.ALL, then the measurement rule will be those cells which entirely overlap with the region. If measurementrule is Grid3D.ANY, then the measurement rule will be those cells which overlap at all with the region. If closed is true, then the region will be considered "closed", that is, that points which touch on the outer surface of the circle will be considered members of the region. If closed is open, then the region will be considered "open", that is, that points which touch on the outer surface of the circle will NOT be considered members of the region.

  Places each x, y, and z value of these locations in the provided IntBags xPos, yPos, and zPos, clearing the bags first.

  This function may be run in one of three modes: Grid3D.BOUNDED, Grid3D.UNBOUNDED, and GrideD.TOROIDAL. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (0,0,0) to (width, height,length), that is, the width and height of the grid. If "unbounded", then the neighbors are not so restricted. Note that unbounded neighborhood lookup only makes sense if your grid allows locations to actually be outside this box. For example, SparseGrid3D permits this but ObjectGrid3D and DoubleGrid3D and IntGrid3D and DenseGrid3D do not. Finally if "toroidal", then the environment is assumed to be toroidal, that is, wrap-around, and neighbors are computed in this fashion. Toroidal locations will not appear multiple times: specifically, if the neighborhood distance is so large that it wraps completely around the width or height of the box, neighbors will not be counted multiple times. Note that to ensure this, subclasses may need to resort to expensive duplicate removal, so it's not suggested you use so unreasonably large distances.

  You can also opt to include the origin -- that is, the (x,y,z) point at the center of the neighborhood -- in the neighborhood results.

  Specified by:
    `getRadialLocations` in interface `Grid3D`

### getRadialNeighbors

    public Bag getRadialNeighbors(int x,
                                  int y,
                                  int z,
                                  int dist,
                                  int mode,
                                  boolean includeOrigin,
                                  Bag result,
                                  IntBag xPos,
                                  IntBag yPos,
                                  IntBag zPos)

### getRadialNeighborsAndLocations

    public Bag getRadialNeighborsAndLocations(int x,
                                              int y,
                                              int z,
                                              int dist,
                                              int mode,
                                              boolean includeOrigin,
                                              Bag result,
                                              IntBag xPos,
                                              IntBag yPos,
                                              IntBag zPos)

### getDimensions

    public final Double3D getDimensions()

  Description copied from interface: `SparseField3D`
  Returns the width and height of the sparse field as a Double3D

  Specified by:
    `getDimensions` in interface `SparseField3D`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD