jabble
Class Grid

java.lang.Object
  jabble.Grid

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<Point>

public abstract class Grid
extends java.lang.Object
implements java.lang.Iterable<Point>, java.io.Serializable

Represents a Grid, that is a collection of points that have the topology of a Grid.

See Also:

Serialized Form

Constructor Summary

Grid()

Method Summary

abstract java.lang.Iterable<Point>	blackPoints() Returns an object usable to retrieve an iterator over all the black point of the Grid.
static Grid	createGrid(int... sizes) Creates a Grid of the specified size.
abstract int	getDimension() Returns the number of directions in the Grid, that is the dimension of the grid (2 for 2D, 3 for 3D, ...)
abstract int	getNPoints() Returns the total number of points on the Grid.
abstract int	getSize(int dirIndex) Returns the number of point along the given direction.
abstract boolean	isInGrid(Point point) Returns true if the Point was defined in this Grid.
abstract boolean	isPeriodicBoundary(int dirIndex) Returns true if the dirIndex direction has period boundary conditions set.
abstract java.util.Iterator<Point>	iterator() Returns an iterator over all points of the Grid.
abstract Point	origin() Returns the point at the corner of the grid where all coordinates are 0.
abstract Point	pointAt(int... location) Returns the Point on the Grid at the given location.
abstract void	setPeriodicBoundaries(boolean... periodicBoundaries) Specifies whether the boundary in each direction is periodic or not.
abstract void	setPeriodicBoundary(int dirIndex) Specifies that the boundary along the dirIndex direction is going to be periodic.
abstract java.lang.Iterable<Point>	subgrid(int... steps) Returns an object usable to retrieve an iterator over a subset of the points of the Grid.
abstract java.lang.Iterable<Point>	subgrid(Point firstPoint, Point lastPoint) Returns an object usable to retrieve an iterator over a subset of the points of the Grid.
abstract java.lang.Iterable<Point>	subgrid(Point firstPoint, Point lastPoint, int... steps) Returns an object usable to retrieve an iterator over a subset of the points of the Grid.
abstract java.lang.Iterable<Point>	whitePoints() Returns an object usable to retrieve an iterator over all the white point of the Grid.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Grid

public Grid()

Method Detail

createGrid

public static Grid createGrid(int... sizes)

Creates a Grid of the specified size. The total number of points (sizes[0]*...*size[n-1]) has to be less than Integer.MAX_VALUE.

Parameters:

sizes - The number of points in each direction.

setPeriodicBoundaries

public abstract void setPeriodicBoundaries(boolean... periodicBoundaries)

Specifies whether the boundary in each direction is periodic or not.

Parameters:

periodicBoundaries - a true/false argument for each boundary

Throws:

java.lang.IllegalArgumentException - if the number of arguments doesn't match the number of directions of the Grid

java.lang.IllegalStateException - if one attempts to modify the periodic boundary conditions after a Point has been requested from the Grid (it ensures that all calculation done on the Grid is consistent)

setPeriodicBoundary

public abstract void setPeriodicBoundary(int dirIndex)

Specifies that the boundary along the dirIndex direction is going to be periodic.

Parameters:

dirIndex - a direction on the Grid

Throws:

java.lang.IllegalStateException - if one attempts to modify the periodic boundary conditions after a Point has been requested from the Grid (it ensures that all calculation done on the Grid is consistent)

isPeriodicBoundary

public abstract boolean isPeriodicBoundary(int dirIndex)

Returns true if the dirIndex direction has period boundary conditions set.

Parameters:

dirIndex - a direciton on the Grid

Returns:

true if the boundary is periodic

origin

public abstract Point origin()

Returns the point at the corner of the grid where all coordinates are 0. This should be used as a starting point for Grid iterations.

Returns:

The origin point

pointAt

public abstract Point pointAt(int... location)

Returns the Point on the Grid at the given location. For example, pointAt(0, 0, 0) would return the origin of a 3D Grid.

Parameters:

location - the position of the Point along each coordinate

Returns:

The point at the given location.

Throws:

java.lang.IllegalArgumentException - if the number of components for the location doesn't match the number of directions of the grid

getSize

public abstract int getSize(int dirIndex)

Returns the number of point along the given direction.

Parameters:

dirIndex - A direction of the grid.

Returns:

The size of the Grid along dirIndex

getNPoints

public abstract int getNPoints()

Returns the total number of points on the Grid.

Returns:

The number of points on the grid, which is the product of the sizes along all directions.

isInGrid

public abstract boolean isInGrid(Point point)

Returns true if the Point was defined in this Grid.

Parameters:

point - A point

Returns:

true if the Point is in the Grid; false otherwise

getDimension

public abstract int getDimension()

Returns the number of directions in the Grid, that is the dimension of the grid (2 for 2D, 3 for 3D, ...)

Returns:

The number of directions (2 for 2D, 3 for 3D, ...)

iterator

public abstract java.util.Iterator<Point> iterator()

Returns an iterator over all points of the Grid. This is defined to support foreach syntax for the Grid.

This method allows the grid to be used within an enhanced for loop as in the following example:

 for (Point point : grid) {
     // doSomething(point);
 }
 

Specified by:

iterator in interface java.lang.Iterable<Point>

Returns:

an iterator over all points.

blackPoints

public abstract java.lang.Iterable<Point> blackPoints()

Returns an object usable to retrieve an iterator over all the black point of the Grid.

You can use this method within an enhanced for loop as in the following example:

 for (Point point : grid.blackPoints()) {
     // doSomething(point);
 }
 

Returns:

an object iterable over black points.

whitePoints

public abstract java.lang.Iterable<Point> whitePoints()

Returns an object usable to retrieve an iterator over all the white point of the Grid.

You can use this method within an enhanced for loop as in the following example:

 for (Point point : grid.whitePoints()) {
     // doSomething(point);
 }
 

Returns:

an object iterable over white points.

subgrid

public abstract java.lang.Iterable<Point> subgrid(Point firstPoint,
                                                  Point lastPoint)

Returns an object usable to retrieve an iterator over a subset of the points of the Grid. It returns a subgrid where all the steps are 1 (no points are skipped). See subgrid(Point, Point, int...) for futher details.

You can use this method within an enhanced for loop as in the following examples:

 for (Point point : grid.subgrid(grid.pointAt(1, 1),
                                 grid.pointAt(10, 10))) {
     // doSomething(point);
 }
 

Parameters:

firstPoint - the first point of the subgrid which establishes the low end of the range for all directions in the subgrid

lastPoint - the last point of the subgrid which establishes the high end of the range for all directions in the subgrid

Returns:

an object iterable over the subgrid.

subgrid

public abstract java.lang.Iterable<Point> subgrid(int... steps)

Returns an object usable to retrieve an iterator over a subset of the points of the Grid. It returns a subgrid where the first point and last point coincide with the origin and last point of the grid itself (the subgrid area is the whole grid). See subgrid(Point, Point, int...) for futher details.

You can use this method within an enhanced for loop as in the following examples:

 for (Point point : grid.subgrid(2, 2)) {
     // doSomething(point);
 }
 

Parameters:

steps - how far apart should one skip in each direction to find the next point along that direction

Returns:

an object iterable over the subgrid.

subgrid

public abstract java.lang.Iterable<Point> subgrid(Point firstPoint,
                                                  Point lastPoint,
                                                  int... steps)

Returns an object usable to retrieve an iterator over a subset of the points of the Grid. A subgrid is a determined subregion of the grid, defined by the two corners (the origin of the subgrid and the last point), which can can be iterated by skipping points (for example, by taking one point every two or every three points.

The firstPoint and lastPoint define the area of the subgrid: the firstPoint will define the starting range for all locations of the point of the subgrid while the lastPoint will define the ending range. The steps will define how fare apart will be the next point along each direction. For example, a step of 2 in one direction will mean that only 1 point every 2 will be taken, effectively skipping half of the points.

You can use this method within an enhanced for loop as in the following examples:

 for (Point point : grid.subgrid(grid.pointAt(1, 1),
                                 grid.pointAt(10, 10),
                                 3, 3)) {
     // doSomething(point);
 }

 for (Point point : grid.subgrid(pointA, pointB, 2, 2)) {
     // doSomething(point);
 }
 

Parameters:

firstPoint - the first point of the subgrid which establishes the low end of the range for all directions in the subgrid

lastPoint - the last point of the subgrid which establishes the high end of the range for all directions in the subgrid

steps - how far apart should one skip in each direction to find the next point along that direction

Returns:

an object iterable over the subgrid.