An algorithm in the point distribution scenario needs to take in a "scenario" and output a set of points representing the new positions of the input points. The following is an example that demonstrates one simple (and not very good) algorithm:

public Point2D.Double[] getNewPositions(DistributionScenarioInterface scenario) { // these are the points in the old scenario Point2D.Double[] oldPoints = scenario.getPoints(); // here we initialize a new array for the new locations of the points Point2D.Double[] newPoints = new Point2D.Double[oldPoints.length]; // this is the maximum change in distance from old position to new position double MAX_STEP_DISTANCE = .01; // here we loop over all the points in the scenario for (int i = 0; i < oldPoints.length; i++) { // here we iterate over all the neighbors of the current point // to find the one with maximum area Point2D.Double bestNbr = null; double bestArea = 0.0; for (Point2D.Double nbr : scenario.getPointsAdjacentTo(oldPoints[i])) { double area = scenario.getArea(nbr); if (area > bestArea) { bestNbr = nbr; bestArea = area; } } // once the point with maximum area is known, // we head directly towards that point double nbrDist = bestNbr.distance(oldPoints[i]); // this is a unit vector pointing from oldPoints[i] to bestNbr Point2D.Double posChange = new Point2D.Double( (bestNbr.x - oldPoints[i].x)/nbrDist, (bestNbr.y - oldPoints[i].y)/nbrDist); // this is the new location newPoints[i] = new Point2D.Double( oldPoints[i].x + MAX_STEP_DISTANCE * posChange.x, oldPoints[i].y + MAX_STEP_DISTANCE * posChange.y); } // this returns the computed value return newPoints; }

# Detailed Explanation of Java

Here is a line-by-line description of the underlying Java code.

public Point2D.Double[] getNewPositions(DistributionScenarioInterface scenario) { ... }

This declares the method, with input variable

**scenario**of type

`DistributionScenarioInterface`, and output variable of type

`Point2D.Double[]`. Every variable in Java has a certain type, and that is being specified explicitly here. The brackets

`[]`indicate that the output is an

*array*. The

`public`is a "modifier" that allows the method to be accessed from external classes. The curly braces { and } are used to specify the start and finish of the method.

Point2D.Double[] oldPoints = scenario.getPoints();

This declares a variable

**oldPoints**of type

`Point2D.Double[]`, and sets it to the value returned by the method

`scenario.getPoints()`. Here

**scenario**is the variable argument that was passed into the method, and the

`.`is used to access a method that "belongs" to

**scenario**.

In Java, variables will often have "properties" and "methods". Properties store additional variables that belong to the variable, whereas methods might operate on those variables or return something of interest. In this case, the `getPoints()` method simply returns an array of points that represents the points within the scenario.

Point2D.Double[] newPoints = new Point2D.Double[oldPoints.length];

This creates a new array of points. In Java, the length of the array must be specified when it is first created… here the length is

`oldPoints.length`, or the length of the array

**oldPoints**. Arrays are indexed by a number between 0 and length-1, e.g. an array created by the code "

`int[] var = new int[3];`" will have three values accessed by

`int[0]`,

`int[1]`, and

`int[2]`. See http://java.sun.com/docs/books/tutorial/java/nutsandbolts/arrays.html.

The `new` keyword is used whenever a variable is created for the first time. This is not used above for **oldPoints** since the array already existed in memory inside **scenario**.

for (int i = 0; i < oldPoints.length; i++) { ... }

Here we iterate over all points within

**oldPoints**. This is the standard way of iterating over an array. Inside the parentheticals, the first argument

`int i=0;`sets up the counter prior to the first run through the loop; the second argument

`i < oldPoints.length;`describes the termination condition… as long as the condition is true, the loop will keep running; the third argument

`i++`says what to do

*after*each iteration through the loop. Since arrays in Java start at 0, the resulting values of

**i**will be

`0,…,(oldPoints.length-1)`. Within a loop, the current point is accessible by

`oldPoints[i]`. See http://java.sun.com/docs/books/tutorial/java/nutsandbolts/for.html.

Point2D.Double bestNbr = null; double bestArea = 0.0; for (Point2D.Double nbr : scenario.getPointsAdjacentTo(oldPoints[i])) { double area = scenario.getArea(nbr); if (area > bestArea) { bestNbr = nbr; bestArea = area; } }

This code block finds the neighbor with the largest area. Two variables are set up to keep track of the "current" best,

**bestNbr**and

**bestArea**. Since we are trying to maximize the area, the initial value of

**bestArea**is 0. The variable

**bestNbr**begins as a

`null`, which means it stores no point value.

The iteration structure here is slightly different… this is known as the "for-each" construction, where the colon is interpreted as the "each". So the loop statement may be interpreted as *"for each point nbr in the set of points returned by the method scenario.getPointsAdjacentTo(oldPoints[i])"*. Within the loop, that point is accessible by the variable

**nbr**. See http://java.sun.com/docs/books/tutorial/java/nutsandbolts/for.html.

The `if` statement says that if a larger area is found, we should ubdate the best-so-far. See http://java.sun.com/docs/books/tutorial/java/nutsandbolts/if.html.

double nbrDist = bestNbr.distance(oldPoints[i]); Point2D.Double posChange = new Point2D.Double( (bestNbr.x - oldPoints[i].x)/nbrDist, (bestNbr.y - oldPoints[i].y)/nbrDist); newPoints[i] = new Point2D.Double( oldPoints[i].x + MAX_STEP_DISTANCE * posChange.x, oldPoints[i].y + MAX_STEP_DISTANCE * posChange.y);

This code sets the value of

**newPoints[i]**, the

*i*th point in the array, to be a new point which is a little distance from the old point. The

`distance`method returns the distance between two points. In the second line, the

**posChange**variable is used to store the unit vector pointing from

**oldPoints[i]**to

**bestNbr**. The

`new`keyword is used to construct a new point. In this case, a new point is created by the code

`new Point2D.Double(x,y)`, where

`x`and

`y`are the coordinates. These values are in turn retrieved by statements such as

`bestNbr.x`and

`bestNbr.y`.

return newPoints;

The final statement in any method that returns a value should be a

`return`statement. In this case, it returns what was guaranteed by the definition of the method, an array of points.