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.continuous
Class Continuous2D

    java.lang.Object
      sim.field.SparseField
          sim.field.continuous.Continuous2D

All Implemented Interfaces:
  java.io.Serializable, SparseField2D

    public class Continuous2D

extends SparseField
implements SparseField2D

A storage facility for objects located in a continuous 2D environment. This facility relates objects with 2D double tuples (in the form of Double2D). The facility extends SparseField, and like other objects which extend SparseField (such as SparseGrid2D), the facility can only relate any given object with a single location at a time -- that is, an object cannot hold two locations at once in the Continuous2D field.

Because hashtable lookups are more expensive than just storing the object, we suggest that you ALSO store the location of an object in the object itself, so you can read from the object rather than having to call getObjectLocation(object).

The Continuous2D has been arranged to make neighborhood lookup information reasonably efficient. It discretizes the space into grid buckets. The discretization size of the buckets is provided in the constructor and cannot be changed thereafter. If the discretization was 0.7, for example, then one bucket would be (0,0) to (under 0.7, under 0.7), another bucket would be (0,0,0.7) to (under 0.7, under 1.4), etc.

You can use Continuous2D to look up objects in a given region by asking for objects within the enclosing buckets, then rummaging through the buckets to find the individuals actually in the desired region. The trick here is to come up with a good bucket size. If the bucket size is much larger than the typical size of a neighborhood lookup, then a typical lookup will include large numbers of objects you don't care about; in the worst case, this is an O(n) lookup for something that could have been much smaller. On the other hand, if the bucket size is much smaller than the typical size of a neighborhood lookup, then you have to do lots of bucket lookups to cover your range; many if not most of these buckets could be empty. This can also be highly inefficient.

Stored objects are best thought of as one of two types: point objects and non-point objects. A point object is represented in space by a single point. It has no area or volume. A non-point object has area or volume. You specify whether or not your objects are point or non-point objects when calling getNeighborsWithinDistance(). The distinction matters when you care about this function returning either all the objects whose point location is within the distance range, or returning all the (non-point) the objects which could possibly overlap with the range.

This distinction also is important when determining the discretization size of your grid. If your objects are point objects, you have no minimum bound on the discretization size. But if the object are non-point location objects (that is, they have dimensions of width, height, etc.), and you care about this overlap when you do distance lookups, then you have a minimum bound on your discretization. In this case, you want to make certain that your discretization is at LEAST larger than the LARGEST dimension of any object you plan on putting in the Continuous2D. The idea here is that if an any part of an object fell within the bounding box for your distance lookup task (see getNeighborsWithinDistance(...)), you're guaranteed that the stored location of the object must be within a bounding box 1 discretization larger in each direction.

Okay, so that gives you the minimum discretization you should use. What about the maximum discretization? It depends largely on the number of objects expected to occupy a given discretized bucket region, and on what kind of lookups you need to do for objects within a given distance. Searching through one bucket is a hash table lookup. A smaller discretization returns a more accurate sample of objects within the requested bounding box, but requires more hash table lookups. If you have point location objects, and your field is very dense (LOTS of objects in a bucket on average), then we recommend a discretization equal to the maximum range distance you are likely to look up; but if your field is very sparse, then we recommend a discretization equal to twice the maximum range distance. You have to tune it. If you have non-point-location objects, then you have two choices. One approach is to assume a discretization equal to the maximum range distance, but when doing lookups with getNeighborsWithinDistance(...), you need to state that you're using non-point-location objects. If you're fairly sparse and your objects aren't big, you can set the discretization to twice the maximum range distance, and you should be safe calling getNeighborsWithinDistance() pretending that your objects are point-location; this saves you a lot of hash table lookups.

At any rate, do NOT go below the minimum discretization rules.

But wait, you say, I have objects of widely varying sizes. Or I have many different neighborhood lookup range needs. Never fear. Just use multiple Continuous2Ds of different discretizations. Depending on your needs, you can put all the objects in all of the Continuous2Ds (making different range lookups efficient) or various-sized classes of objects in their own Continuous2Ds perhaps. You have to think this through based on your needs. If all the objects were in all of the Continuous2Ds, you'd think that'd be inefficient in moving objects around. Not really: if the discretizations doubled (or more) each time, you're looking at typically an O(ln n) number of Continuous2Ds, and a corresponding number of lookups.

Continuous2D objects have a width and a height, but this is used for two functions: first, to determine the bounds for toroidal functions. Second, to determine the bounds for drawing on the screen in a portrayal. Otherwise, width and height are not used. If your space is bounded, you should set the width and height to those bounds. If it's unbounded, then you should set the width and height to the bounds you would like displayed on-screen.

See Also:
  Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class sim.field.SparseField
`SparseField.LocationAndIndex`

Field Summary
`double` | `discretization`
`java.util.Map` | `doubleLocationHash` Where we store the Double2D values hashed by object
`double` | `height`
`double` | `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`

Constructor Summary
`Continuous2D(Continuous2D other)`
`Continuous2D(double discretization, double width, double height)` Provide expected bounds on the SparseContinuous2D

Method Summary
`Bag` | `clear()` Deletes everything, returning all the objects as a Bag (which you can freely use and modify).
`Int2D` | `discretize(Double2D location)` Discretizes the location according to the internal discretization of the Continuous2D.
`Int2D` | `discretize(Double2D location, int discretization)` Discretizes the location according to the provided discretization, which may or may not be the discretization used internally by the Continuous2D.
`Double2D` | `getDimensions()` Returns the width and height of the sparse field as a Double2D
`double` | `getHeight()` Get the height
`Bag` | `getNearestNeighbors(Double2D position, int atLeastThisMany, boolean toroidal, boolean nonPointObjects, boolean radial, Bag result)` Finds and returns at LEAST the 'atleastThisMany' items closest to a given 'position', plus potentially other items.
`Bag` | `getNeighborsExactlyWithinDistance(Double2D position, double distance)` Returns a Bag containing EXACTLY those objects within a certain distance of a given position, or equal to that distance, measuring using a circle of radius 'distance' around the given position.
`Bag` | `getNeighborsExactlyWithinDistance(Double2D position, double distance, boolean toroidal)` Returns a Bag containing EXACTLY those objects within a certain distance of a given position, or equal to that distance, measuring using a circle of radius 'distance' around the given position.
`Bag` | `getNeighborsExactlyWithinDistance(Double2D position, double distance, boolean toroidal, boolean radial, boolean inclusive, Bag result)` Returns a Bag containing EXACTLY those objects within a certain distance of a given position.
`Bag` | `getNeighborsWithinDistance(Double2D position, double distance)` Returns a bag containing AT LEAST those objects within the bounding box surrounding the specified distance of the specified position.
`Bag` | `getNeighborsWithinDistance(Double2D position, double distance, boolean toroidal)` Returns a bag containing AT LEAST those objects within the bounding box surrounding the specified distance of the specified position.
`Bag` | `getNeighborsWithinDistance(Double2D position, double distance, boolean toroidal, boolean nonPointObjects)` Returns a bag containing AT LEAST those objects within the bounding box surrounding the specified distance of the specified position.
`Bag` | `getNeighborsWithinDistance(Double2D position, double distance, boolean toroidal, boolean nonPointObjects, Bag result)` Puts into the result Bag (and returns it) AT LEAST those objects within the bounding box surrounding the specified distance of the specified position.
`Double2D` | `getObjectLocation(java.lang.Object obj)`
`Double2D` | `getObjectLocationAsDouble2D(java.lang.Object obj)` Synonymous with getObjectLocation, which you should generally use instead.
`Bag` | `getObjectsAtDiscretizedLocation(Int2D location)` Returns a bag containing all the objects at a given discretized location, or null when there are no objects at the location.
`Bag` | `getObjectsAtLocation(Double2D location)` Returns a bag containing all the objects at a given location, or null if there are no such objects or if location is null.
`Bag` | `getObjectsAtLocationOfObject(java.lang.Object obj)` Returns a bag containing all the objects at the exact same location as a given object, including the object itself, or null if the object is not in the Field.
`Bag` | `getObjectsExactlyWithinDistance(Double2D position, double distance)` Deprecated.
`Bag` | `getObjectsExactlyWithinDistance(Double2D position, double distance, boolean toroidal)` Deprecated.
`Bag` | `getObjectsExactlyWithinDistance(Double2D position, double distance, boolean toroidal, boolean radial, boolean inclusive, Bag result)` Deprecated.
`Bag` | `getObjectsWithinDistance(Double2D position, double distance)` Deprecated.
`Bag` | `getObjectsWithinDistance(Double2D position, double distance, boolean toroidal)` Deprecated.
`Bag` | `getObjectsWithinDistance(Double2D position, double distance, boolean toroidal, boolean nonPointObjects)` Deprecated.
`Bag` | `getObjectsWithinDistance(Double2D position, double distance, boolean toroidal, boolean nonPointObjects, Bag result)` Deprecated.
`double` | `getWidth()` Get the width
`int` | `numObjectsAtLocation(Double2D location)` Returns the number of the objects at a given location, or 0 if there are no such objects or if location is null.
`int` | `numObjectsAtLocationOfObject(java.lang.Object obj)` Returns the number of objects at the exact same location as a given object, including the object itself, or 0 if the object is not in the Field.
`java.lang.Object` | `remove(java.lang.Object obj)` Removes an object if it exists.
`Bag` | `removeObjectsAtLocation(Double2D location)` Removes objects at exactly the given location, and returns a bag of them, or null of no objects are at that location.
`boolean` | `setObjectLocation(java.lang.Object obj, Double2D location)`
`double` | `stx(double x)` Simple [and fast] toroidal x.
`double` | `sty(double y)` Simple [and fast] toroidal y.
`double` | `tds(Double2D d1, Double2D d2)` Minimum Toroidal Distance Squared between two points.
`double` | `tdx(double x1, double x2)` Minimum toroidal difference between two values in the X dimension.
`double` | `tdy(double y1, double y2)` Minimum toroidal difference between two values in the Y dimension.
`Double2D` | `tv(Double2D d1, Double2D d2)` Minimum Toroidal difference vector between two points.
`double` | `tx(double x)` Toroidal x
`double` | `ty(double y)` Toroidal y

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

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

Field Detail

### doubleLocationHash

    public java.util.Map doubleLocationHash

  Where we store the Double2D values hashed by object

### width

    public double width

### height

    public double height

### discretization

    public final double discretization

Constructor Detail

### Continuous2D

    public Continuous2D(double discretization,
                        double width,
                        double height)

  Provide expected bounds on the SparseContinuous2D

### Continuous2D

    public Continuous2D(Continuous2D other)

Method Detail

### getObjectLocation

    public final Double2D getObjectLocation(java.lang.Object obj)

### getObjectLocationAsDouble2D

    public final Double2D getObjectLocationAsDouble2D(java.lang.Object obj)

  Synonymous with getObjectLocation, which you should generally use instead.

  Specified by:
    `getObjectLocationAsDouble2D` in interface `SparseField2D`

### getDimensions

    public final Double2D getDimensions()

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

  Specified by:
    `getDimensions` in interface `SparseField2D`

### discretize

    public final Int2D discretize(Double2D location)

  Discretizes the location according to the internal discretization of the Continuous2D. You can use this to determine what internal grid slot the continuous point would fall in.

### discretize

    public final Int2D discretize(Double2D location,
                                  int discretization)

  Discretizes the location according to the provided discretization, which may or may not be the discretization used internally by the Continuous2D. If you're trying to determine what grid slot a continuous point would fall in, you probably want discretize(location) instead.

### setObjectLocation

    public final boolean setObjectLocation(java.lang.Object obj,
                                           Double2D location)

### clear

    public final Bag clear()

  Description copied from class: `SparseField`
  Deletes everything, returning all the objects as a Bag (which you can freely use and modify). If you need the Bag, then this is a useful method -- otherwise it might in fact be faster to just make a brand new Sparse Field and let the garbage collector do its magic.

  Overrides:
    `clear` in class `SparseField`

### remove

    public final java.lang.Object remove(java.lang.Object obj)

  Description copied from class: `SparseField`
  Removes an object if it exists. Returns its location, or null if the object didn't exist.

  Overrides:
    `remove` in class `SparseField`

### getWidth

    public double getWidth()

  Get the width

### getHeight

    public double getHeight()

  Get the height

### tx

    public final double tx(double x)

  Toroidal x

### ty

    public final double ty(double y)

  Toroidal y

### stx

    public double stx(double x)

  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:
  { double 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 removing the double width = this.width; is likely to be a little faster if most objects are within the toroidal region.

### sty

    public double sty(double y)

  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:
  { double 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 removing the double height = this.height; is likely to be a little faster if most objects are within the toroidal region.

### tdx

    public double tdx(double x1,
                      double x2)

  Minimum toroidal difference between two values in the X dimension.

### tdy

    public double tdy(double y1,
                      double y2)

  Minimum toroidal difference between two values in the Y dimension.

### tds

    public double tds(Double2D d1,
                      Double2D d2)

  Minimum Toroidal Distance Squared between two points. This computes the "shortest" (squared) distance between two points, considering wrap-around possibilities as well.

### tv

    public Double2D tv(Double2D d1,
                       Double2D d2)

  Minimum Toroidal difference vector between two points. This subtracts the second point from the first and produces the minimum-length such subtractive vector, considering wrap-around possibilities as well

### getNearestNeighbors

    public Bag getNearestNeighbors(Double2D position,
                                   int atLeastThisMany,
                                   boolean toroidal,
                                   boolean nonPointObjects,
                                   boolean radial,
                                   Bag result)

  Finds and returns at LEAST the 'atleastThisMany' items closest to a given 'position', plus potentially other items. toroidal must be false -- presently it's not supported. If objects are non-point and may overlap into another discretization cell, set 'nonPointObjects' to true. If you want the distance to be radial -- that is, the region searched will be a circle centered at the position, set 'radial' to true (almost always you want this). If you want the region searched to be a rectangle centered at the position, set 'radial' to be false. Returns a bag of items. If 'result' is provided, clears that Bag and reuses it.

### getObjectsExactlyWithinDistance

    public Bag getObjectsExactlyWithinDistance(Double2D position,
                                               double distance)

  Deprecated.

  Returns a Bag containing EXACTLY those objects within a certain distance of a given position, or equal to that distance, measuring using a circle of radius 'distance' around the given position. Assumes non-toroidal point objects.

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getObjectsExactlyWithinDistance

    public Bag getObjectsExactlyWithinDistance(Double2D position,
                                               double distance,
                                               boolean toroidal)

  Deprecated.

  Returns a Bag containing EXACTLY those objects within a certain distance of a given position, or equal to that distance, measuring using a circle of radius 'distance' around the given position. If 'toroidal' is true, then the distance is measured assuming the environment is toroidal. Assumes point objects.

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getObjectsExactlyWithinDistance

    public Bag getObjectsExactlyWithinDistance(Double2D position,
                                               double distance,
                                               boolean toroidal,
                                               boolean radial,
                                               boolean inclusive,
                                               Bag result)

  Deprecated.

  Returns a Bag containing EXACTLY those objects within a certain distance of a given position. If 'radial' is true, then the distance is measured using a circle around the position, else the distance is meaured using a square around the position (that is, it's the maximum of the x and y distances). If 'inclusive' is true, then objects that are exactly the given distance away are included as well, else they are discarded. If 'toroidal' is true, then the distance is measured assuming the environment is toroidal. If the Bag 'result' is provided, it will be cleared and objects placed in it and it will be returned, else if it is null, then this method will create a new Bag and use that instead. Assumes point objects.

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getNeighborsExactlyWithinDistance

    public Bag getNeighborsExactlyWithinDistance(Double2D position,
                                                 double distance)

  Returns a Bag containing EXACTLY those objects within a certain distance of a given position, or equal to that distance, measuring using a circle of radius 'distance' around the given position. Assumes non-toroidal point objects.

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getNeighborsExactlyWithinDistance

    public Bag getNeighborsExactlyWithinDistance(Double2D position,
                                                 double distance,
                                                 boolean toroidal)

  Returns a Bag containing EXACTLY those objects within a certain distance of a given position, or equal to that distance, measuring using a circle of radius 'distance' around the given position. If 'toroidal' is true, then the distance is measured assuming the environment is toroidal. Assumes point objects.

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getNeighborsExactlyWithinDistance

    public Bag getNeighborsExactlyWithinDistance(Double2D position,
                                                 double distance,
                                                 boolean toroidal,
                                                 boolean radial,
                                                 boolean inclusive,
                                                 Bag result)

  Returns a Bag containing EXACTLY those objects within a certain distance of a given position. If 'radial' is true, then the distance is measured using a circle around the position, else the distance is meaured using a square around the position (that is, it's the maximum of the x and y distances). If 'inclusive' is true, then objects that are exactly the given distance away are included as well, else they are discarded. If 'toroidal' is true, then the distance is measured assuming the environment is toroidal. If the Bag 'result' is provided, it will be cleared and objects placed in it and it will be returned, else if it is null, then this method will create a new Bag and use that instead. Assumes point objects.

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getObjectsWithinDistance

    public Bag getObjectsWithinDistance(Double2D position,
                                        double distance)

  Deprecated.

  Returns a bag containing AT LEAST those objects within the bounding box surrounding the specified distance of the specified position. The bag could include other objects than this. In this case we include the object if any part of the bounding box could overlap into the desired region. To do this, if nonPointObjects is true, we extend the search space by one extra discretization in all directions. For small distances within a single bucket, this returns nine bucket's worth rather than 1, so if you know you only care about the actual x/y points stored, rather than possible object overlap into the distance sphere you specified, you'd want to set nonPointObjects to FALSE. [assumes non-toroidal, point objects]

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getObjectsWithinDistance

    public Bag getObjectsWithinDistance(Double2D position,
                                        double distance,
                                        boolean toroidal)

  Deprecated.

  Returns a bag containing AT LEAST those objects within the bounding box surrounding the specified distance of the specified position. The bag could include other objects than this. If toroidal, then wrap-around possibilities are also considered. In this case we include the object if any part of the bounding box could overlap into the desired region. To do this, if nonPointObjects is true, we extend the search space by one extra discretization in all directions. For small distances within a single bucket, this returns nine bucket's worth rather than 1, so if you know you only care about the actual x/y points stored, rather than possible object overlap into the distance sphere you specified, you'd want to set nonPointObjects to FALSE. [assumes point objects]

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getObjectsWithinDistance

    public Bag getObjectsWithinDistance(Double2D position,
                                        double distance,
                                        boolean toroidal,
                                        boolean nonPointObjects)

  Deprecated.

  Returns a bag containing AT LEAST those objects within the bounding box surrounding the specified distance of the specified position. The bag could include other objects than this. If toroidal, then wrap-around possibilities are also considered. If nonPointObjects, then it is presumed that the object isn't just a point in space, but in fact fills an area in space where the x/y point location could be at the extreme corner of a bounding box of the object. In this case we include the object if any part of the bounding box could overlap into the desired region. To do this, if nonPointObjects is true, we extend the search space by one extra discretization in all directions. For small distances within a single bucket, this returns nine bucket's worth rather than 1, so if you know you only care about the actual x/y points stored, rather than possible object overlap into the distance sphere you specified, you'd want to set nonPointObjects to FALSE.

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getObjectsWithinDistance

    public Bag getObjectsWithinDistance(Double2D position,
                                        double distance,
                                        boolean toroidal,
                                        boolean nonPointObjects,
                                        Bag result)

  Deprecated.

  Puts into the result Bag (and returns it) AT LEAST those objects within the bounding box surrounding the specified distance of the specified position. If the result Bag is null, then a Bag is created.

  The bag could include other objects than this. If toroidal, then wrap-around possibilities are also considered. If nonPointObjects, then it is presumed that the object isn't just a point in space, but in fact fills an area in space where the x/y point location could be at the extreme corner of a bounding box of the object. In this case we include the object if any part of the bounding box could overlap into the desired region. To do this, if nonPointObjects is true, we extend the search space by one extra discretization in all directions. For small distances within a single bucket, this returns nine bucket's worth rather than 1, so if you know you only care about the actual x/y points stored, rather than possible object overlap into the distance sphere you specified, you'd want to set nonPointObjects to FALSE.

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getNeighborsWithinDistance

    public Bag getNeighborsWithinDistance(Double2D position,
                                          double distance)

  Returns a bag containing AT LEAST those objects within the bounding box surrounding the specified distance of the specified position. The bag could include other objects than this. In this case we include the object if any part of the bounding box could overlap into the desired region. To do this, if nonPointObjects is true, we extend the search space by one extra discretization in all directions. For small distances within a single bucket, this returns nine bucket's worth rather than 1, so if you know you only care about the actual x/y points stored, rather than possible object overlap into the distance sphere you specified, you'd want to set nonPointObjects to FALSE. [assumes non-toroidal, point objects]

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getNeighborsWithinDistance

    public Bag getNeighborsWithinDistance(Double2D position,
                                          double distance,
                                          boolean toroidal)

  Returns a bag containing AT LEAST those objects within the bounding box surrounding the specified distance of the specified position. The bag could include other objects than this. If toroidal, then wrap-around possibilities are also considered. In this case we include the object if any part of the bounding box could overlap into the desired region. To do this, if nonPointObjects is true, we extend the search space by one extra discretization in all directions. For small distances within a single bucket, this returns nine bucket's worth rather than 1, so if you know you only care about the actual x/y points stored, rather than possible object overlap into the distance sphere you specified, you'd want to set nonPointObjects to FALSE. [assumes point objects]

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getNeighborsWithinDistance

    public Bag getNeighborsWithinDistance(Double2D position,
                                          double distance,
                                          boolean toroidal,
                                          boolean nonPointObjects)

  Returns a bag containing AT LEAST those objects within the bounding box surrounding the specified distance of the specified position. The bag could include other objects than this. If toroidal, then wrap-around possibilities are also considered. If nonPointObjects, then it is presumed that the object isn't just a point in space, but in fact fills an area in space where the x/y point location could be at the extreme corner of a bounding box of the object. In this case we include the object if any part of the bounding box could overlap into the desired region. To do this, if nonPointObjects is true, we extend the search space by one extra discretization in all directions. For small distances within a single bucket, this returns nine bucket's worth rather than 1, so if you know you only care about the actual x/y points stored, rather than possible object overlap into the distance sphere you specified, you'd want to set nonPointObjects to FALSE.

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getNeighborsWithinDistance

    public Bag getNeighborsWithinDistance(Double2D position,
                                          double distance,
                                          boolean toroidal,
                                          boolean nonPointObjects,
                                          Bag result)

  Puts into the result Bag (and returns it) AT LEAST those objects within the bounding box surrounding the specified distance of the specified position. If the result Bag is null, then a Bag is created.

  The bag could include other objects than this. If toroidal, then wrap-around possibilities are also considered. If nonPointObjects, then it is presumed that the object isn't just a point in space, but in fact fills an area in space where the x/y point location could be at the extreme corner of a bounding box of the object. In this case we include the object if any part of the bounding box could overlap into the desired region. To do this, if nonPointObjects is true, we extend the search space by one extra discretization in all directions. For small distances within a single bucket, this returns nine bucket's worth rather than 1, so if you know you only care about the actual x/y points stored, rather than possible object overlap into the distance sphere you specified, you'd want to set nonPointObjects to FALSE.

  Note: if the field is toroidal, and position is outside the boundaries, it will be wrapped to within the boundaries before computation.

### getObjectsAtDiscretizedLocation

    public Bag getObjectsAtDiscretizedLocation(Int2D location)

  Returns a bag containing all the objects at a given discretized location, or null 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. The default implementation of this method simply calls getRawObjectsAtLocation(), but you may need to override it for more custom functionality (which is rare).

### getObjectsAtLocation

    public Bag getObjectsAtLocation(Double2D location)

  Returns a bag containing all the objects at a given location, or null if there are no such objects or if location is null. Unlike other SparseField versions, you may modify this bag.

### numObjectsAtLocation

    public int numObjectsAtLocation(Double2D location)

  Returns the number of the objects at a given location, or 0 if there are no such objects or if location is null.

### getObjectsAtLocationOfObject

    public Bag getObjectsAtLocationOfObject(java.lang.Object obj)

  Returns a bag containing all the objects at the exact same location as a given object, including the object itself, or null if the object is not in the Field. Unlike other SparseField versions, you may modify this bag.

  Overrides:
    `getObjectsAtLocationOfObject` in class `SparseField`

### numObjectsAtLocationOfObject

    public int numObjectsAtLocationOfObject(java.lang.Object obj)

  Returns the number of objects at the exact same location as a given object, including the object itself, or 0 if the object is not in the Field.

  Overrides:
    `numObjectsAtLocationOfObject` in class `SparseField`

### removeObjectsAtLocation

    public Bag removeObjectsAtLocation(Double2D location)

  Removes objects at exactly the given location, and returns a bag of them, or null of no objects are at that location. The Bag may be empty, or null, if there were no objects at that location. You can freely modify this bag.

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