public interface Grid2D
extends java.io.Serializable
If you're using the Grid to define a toroidal (wraparound) world, you can use the tx and ty methods to simplify the math for you. For example, to increment in the x direction, including wraparound, you can do: x = tx(x+1).
If you're sure that the values you'd pass into the toroidal functions would not wander off more than a grid dimension in either direction (height, width), you can use the slightly faster toroidal functions stx and sty instead. For example, to increment in the x direction, including wraparound, you can do: x = stx(x+1). See the documentation on these functions for when they're appropriate to use. Under most common situations, they're okay.
In HotSpot 1.4.1, stx, and sty are inlined. In Hotspot 1.3.1, they are not (they contain ifstatements).
(0,0) (2,0) (4,0) (6,0) ... (1,0) (3,0) (5,0) (7,0) ... (0,1) (2,1) (4,1) (6,1) ... (1,1) (3,1) (5,1) (7,1) ... (0,2) (2,2) (4,2) (6,2) ... (1,2) (3,2) (5,2) (7,2) ... ... ... ... ... ... ... ... ... ... ...
The rules moving from a hex location (at CENTER) to another one are as follows:
UP x UPLEFT y  1 UPRIGHT x  1 x + 1 ((x % 2) == 0) ? y  1 : y CENTER ((x % 2) == 0) ? y  1 : y x DOWNLEFT y DOWNRIGHT x  1 x + 1 ((x % 2) == 0) ? y : y + 1 DOWN ((x % 2) == 0) ? y : y + 1 x y + 1NOTE: (x % 2 == 0), that is, "x is even", may be written instead in this faster way: ((x & 1) == 0)
Because the math is a little hairy, we've provided the math for the UPLEFT, UPRIGHT, DOWNLEFT, and DOWNRIGHT directions for you. For example, the UPLEFT location from [x,y] is at [ulx(x,y) , uly(x,y)]. Additionally, the toroidal methods can be used in conjunction with the hex methods to implement a toroidal hex grid. Be sure to To use a toroidal hex grid properly, you must ensure that height of the grid is an even number. For example, the toroidal UPLEFT X location is at tx(ulx(x,y)) and the UPLEFT Y location is at ty(uly(x,y)). Similarly, you can use stx and sty.
While this interface defines various methods common to many grids, you should endeavor not to call these grids casted into this interface: it's slow. If you call the grids' methods directly by their class, their methods are almost certain to be inlined into your code, which is very fast.
 \(0,0)/ \(2,0)/ \(4,0)/ \ \ / \ / \ / \ ... \ /(1,0)\ /(3,0)\ /(5,0)\  / \(1,1)/ \(3,1)/ \(5,1)/ / \ / \ / \ / ... /(0,1)\ /(2,1)\ /(4,1)\ /  \(0,2)/ \(2,2)/ \(4,2)/ \ \ / \ / \ / \ ... \ /(1,2)\ /(3,2)\ /(5,2)\  / \(1,3)/ \(3,3)/ \(5,3)/ / \ / \ / \ / ... /(0,3)\ /(2,3)\ /(4,3)\ /  . . .
How do you get around such a beast? Piece of cake! Well, to go to your right or left neighbor, you just add or subtract the X value. To go to your up or down neighbor, all you do is add or subtract the Y value. All you need to know is if your triangle has an edge on the top (so you can go up) or an edge on the bottom (so you can go down). The functions TRB (triangle with horizontal edge on 'bottom') and TRT (triangle with horizontal edge on 'top') will tell you this.
Like the others, the triangular grid can also be used in toroidal fashion, and the toroidal functions should work properly with it. To use a toroidal triangular grid, you should ensure that your grid's length and width are both even numbers.
We'll provide a distancemeasure function for triangular grids just as soon as we figure out what the heck one looks like. :)
Modifier and Type  Field and Description 

static int 
ALL
"All" measurement rule for raidal neighborhood lookup.

static int 
ANY
"Any" measurement rule for raidal neighborhood lookup.

static int 
ANY_SIZE
Pass this into buildMap to indicate that it should make a map of any size it likes.

static int 
BOUNDED
Bounded Mode for neighborhood lookup.

static int 
CENTER
Center measurement rule for raidal neighborhood lookup.

static int 
TOROIDAL
Bounded Mode for toroidal lookup.

static int 
UNBOUNDED
Bounded Mode for neighborhood lookup.

Modifier and Type  Method and Description 

java.util.Map 
buildMap(int size)
Creates a map of the provided size (or any size it likes if ANY_SIZE is passed in).

java.util.Map 
buildMap(java.util.Map other)
Creates a Map which is a copy of another.

int 
dlx(int x,
int y)
Hex downleft x.

int 
dly(int x,
int y)
Hex downleft y.

int 
downx(int x,
int y)
Hex down x.

int 
downy(int x,
int y)
Hex down y.

int 
drx(int x,
int y)
Hex downright x.

int 
dry(int x,
int y)
Hex downright y.

int 
getHeight()
Returns the width of the field.

void 
getHexagonalLocations(int x,
int y,
int dist,
int mode,
boolean includeOrigin,
IntBag xPos,
IntBag yPos)
Gets all neighbors located within the hexagon centered at (X,Y) and 2*dist+1 cells from point to opposite point
inclusive.

void 
getMooreLocations(int x,
int y,
int dist,
int mode,
boolean includeOrigin,
IntBag xPos,
IntBag yPos)
Gets all neighbors of a location that satisfy max( abs(xX) , abs(yY) ) <= dist.

void 
getNeighborsHamiltonianDistance(int x,
int y,
int dist,
boolean toroidal,
IntBag xPos,
IntBag yPos)
Deprecated.

void 
getNeighborsHexagonalDistance(int x,
int y,
int dist,
boolean toroidal,
IntBag xPos,
IntBag yPos)
Deprecated.

void 
getNeighborsMaxDistance(int x,
int y,
int dist,
boolean toroidal,
IntBag xPos,
IntBag yPos)
Deprecated.

void 
getRadialLocations(int x,
int y,
double dist,
int mode,
boolean includeOrigin,
IntBag xPos,
IntBag yPos)
Gets all neighbors overlapping with a circular region centered at (X,Y) and with a radius of dist.

void 
getRadialLocations(int x,
int y,
double dist,
int mode,
boolean includeOrigin,
int measurementRule,
boolean closed,
IntBag xPos,
IntBag yPos)
Gets all neighbors overlapping with a circular region centered at (X,Y) and with a radius of dist.

void 
getVonNeumannLocations(int x,
int y,
int dist,
int mode,
boolean includeOrigin,
IntBag xPos,
IntBag yPos)
Gets all neighbors of a location that satisfy abs(xX) + abs(yY) <= dist.

int 
getWidth()
Returns the width of the field.

int 
stx(int x)
Simple [and fast] toroidal x.

int 
sty(int y)
Simple [and fast] toroidal y.

boolean 
trb(int x,
int y)
Horizontal edge is on the bottom for triangle.

boolean 
trt(int x,
int y)
Horizontal edge is on the top for triangle.

int 
tx(int x)
Toroidal x.

int 
ty(int y)
Toroidal y.

int 
ulx(int x,
int y)
Hex upleft x.

int 
uly(int x,
int y)
Hex upleft y.

int 
upx(int x,
int y)
Hex up x.

int 
upy(int x,
int y)
Hex up y.

int 
urx(int x,
int y)
Hex upright x.

int 
ury(int x,
int y)
Hex upright y.

static final int BOUNDED
static final int UNBOUNDED
static final int TOROIDAL
static final int CENTER
static final int ALL
static final int ANY
static final int ANY_SIZE
int getWidth()
int getHeight()
int tx(int x)
int ty(int y)
int stx(int x)
int sty(int y)
int ulx(int x, int y)
int uly(int x, int y)
int urx(int x, int y)
int ury(int x, int y)
int dlx(int x, int y)
int dly(int x, int y)
int drx(int x, int y)
int dry(int x, int y)
int upx(int x, int y)
int upy(int x, int y)
int downx(int x, int y)
int downy(int x, int y)
boolean trb(int x, int y)
boolean trt(int x, int y)
void getNeighborsMaxDistance(int x, int y, int dist, boolean toroidal, IntBag xPos, IntBag yPos)
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) to (width, height), that is, the width and height of the grid. if "toroidal", then the environment is assumed to be toroidal, that is, wraparound, 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) point at the center of the neighborhood  is always included in the results.
This function is equivalent to: getNeighborsMaxDistance(x,y,dist,toroidal ? Grid2D.TOROIDAL : Grid2D.BOUNDED, true, xPos, yPos);
void getMooreLocations(int x, int y, int dist, int mode, boolean includeOrigin, IntBag xPos, IntBag yPos)
This function may be run in one of three modes: Grid2D.BOUNDED, Grid2D.UNBOUNDED, and Grid2D.TOROIDAL. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (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, SparseGrid2D permits this but ObjectGrid2D and DoubleGrid2D and IntGrid2D and DenseGrid2D do not. Finally if "toroidal", then the environment is assumed to be toroidal, that is, wraparound, 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.
void getNeighborsHamiltonianDistance(int x, int y, int dist, boolean toroidal, IntBag xPos, IntBag yPos)
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) to (width, height), that is, the width and height of the grid. if "toroidal", then the environment is assumed to be toroidal, that is, wraparound, 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) point at the center of the neighborhood  is always included in the results.
This function is equivalent to: getNeighborsHamiltonianDistance(x,y,dist,toroidal ? Grid2D.TOROIDAL : Grid2D.BOUNDED, true, xPos, yPos);
void getVonNeumannLocations(int x, int y, int dist, int mode, boolean includeOrigin, IntBag xPos, IntBag yPos)
This function may be run in one of three modes: Grid2D.BOUNDED, Grid2D.UNBOUNDED, and Grid2D.TOROIDAL. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (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, SparseGrid2D permits this but ObjectGrid2D and DoubleGrid2D and IntGrid2D and DenseGrid2D do not. Finally if "toroidal", then the environment is assumed to be toroidal, that is, wraparound, 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.
void getNeighborsHexagonalDistance(int x, int y, int dist, boolean toroidal, IntBag xPos, IntBag yPos)
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) to (width, height), that is, the width and height of the grid. if "toroidal", then the environment is assumed to be toroidal, that is, wraparound, 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) point at the center of the neighborhood  is always included in the results.
This function is equivalent to: getNeighborsHexagonalDistance(x,y,dist,toroidal ? Grid2D.TOROIDAL : Grid2D.BOUNDED, true, xPos, yPos);
void getHexagonalLocations(int x, int y, int dist, int mode, boolean includeOrigin, IntBag xPos, IntBag yPos)
This function may be run in one of three modes: Grid2D.BOUNDED, Grid2D.UNBOUNDED, and Grid2D.TOROIDAL. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (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, SparseGrid2D permits this but ObjectGrid2D and DoubleGrid2D and IntGrid2D and DenseGrid2D do not. Finally if "toroidal", then the environment is assumed to be toroidal, that is, wraparound, 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.
void getRadialLocations(int x, int y, double dist, int mode, boolean includeOrigin, IntBag xPos, IntBag yPos)
Places each x and y value of these locations in the provided IntBags xPos and yPos, clearing the bags first.
This function may be run in one of three modes: Grid2D.BOUNDED, Grid2D.UNBOUNDED, and Grid2D.TOROIDAL. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (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, SparseGrid2D permits this but ObjectGrid2D and DoubleGrid2D and IntGrid2D and DenseGrid2D do not. Finally if "toroidal", then the environment is assumed to be toroidal, that is, wraparound, 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.
void getRadialLocations(int x, int y, double dist, int mode, boolean includeOrigin, int measurementRule, boolean closed, IntBag xPos, IntBag yPos)
Places each x and y value of these locations in the provided IntBags xPos and yPos, clearing the bags first.
This function may be run in one of three modes: Grid2D.BOUNDED, Grid2D.UNBOUNDED, and Grid2D.TOROIDAL. If "bounded", then the neighbors are restricted to be only those which lie within the box ranging from (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, SparseGrid2D permits this but ObjectGrid2D and DoubleGrid2D and IntGrid2D and DenseGrid2D do not. Finally if "toroidal", then the environment is assumed to be toroidal, that is, wraparound, 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.
java.util.Map buildMap(java.util.Map other)
java.util.Map buildMap(int size)