util.grid
Class PointTools

java.lang.Object
  util.grid.PointTools

public class PointTools
extends Object

Utilities for evaluating and modifying points and collections of points. Many are specific to either Cartesian or interlaced hexagonal coordinates.

Version:

January 11, 2008

Method Summary

static HashSet<Point>	copy(Collection<Point> locations) Deep clone of a collection of points.
static int	getBound(Collection<Point> locations, Direction dir) Provides the furthest index in a given direction.
static ArrayList<Point>	getCoordinates(Point start, Orientation... dir) Provides the path given from a series of offsets from an original point (not including the start).
static int	getHeight(Collection<Point> locations) Returns the height dimension.
static HashSet<Point>	getHexArea(Point center, int radius) Provides a hexagon shaped area with a given radius around a given location (empty if radius is less than one).
static HashSet<Point>	getHexBorder(Collection<Point> locations) Provides the points surrounding given positions.
static int	getHexDistance(Point p1, Point p2) Provides the shortest distance between two points in vertically-aligned interlaced hexagonal coordinates.
static ArrayList<HexDirection>	getHexPath(Point p1, Point p2, boolean route) Provides the the shortest directions from one point to another.
static HashSet<Point>	getHexReverse(Set<Point> locations, Point pivot) Constructs a set of points with a mirror reversal about all axes along the pivot point.
static ArrayList<Point>	getHexRotateCCW(Collection<Point> locations, Point pivot) Constructs a set with the points rotated counterclockwise about the pivot.
static ArrayList<Point>	getHexRotateCW(Collection<Point> locations, Point pivot) Constructs a set with the points rotated clockwise about the pivot.
static HashMap<HexDirection,ArrayList<Point>>	getHexRotations(Collection<Point> locations, Point pivot, HexDirection patternDir) Constructs all rotations for a collection of locations around a pivot point.
static HashSet<Point>	getQuadArea(Point center, int radius) Provides a diamond shaped pattern centered around a given location (empty if radius is less than one).
static HashSet<Point>	getQuadBorder(Collection<Point> locations, boolean diagonals) Provides the locations surrounding a set of positions.
static int	getQuadDistance(Point p1, Point p2) Provides the shortest distance between two points in Cartesian coordinates.
static int	getQuadDistance(Point p1, Point p2, boolean diagonals) Provides the shortest distance between two points.
static ArrayList<Orientation>	getQuadPath(Point p1, Point p2, boolean diagonal, boolean route) Provides the the shortest directions from one point to another.
static Point	getQuadPivot(Collection<Point> locations, Direction orientation) Provides the central location within a collection of points for standard cartesian rotations.
static HashSet<Point>	getQuadReverse(Set<Point> locations, Point pivot) Constructs a set of points with a mirror reversal about both axes along the pivot point.
static ArrayList<Point>	getQuadRotateCCW(Collection<Point> locations, Point pivot) Constructs a set with the points rotated counterclockwise about the pivot.
static ArrayList<Point>	getQuadRotateCW(Collection<Point> locations, Point pivot) Constructs a set with the points rotated clockwise about the pivot.
static int	getWidth(Collection<Point> locations) Returns the width dimension.
static HashSet<Point>	wrapper(Point location) Constructs a collection wrapper for a single point.

Methods inherited from class java.lang.Object

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

Method Detail

copy

public static HashSet<Point> copy(Collection<Point> locations)

Deep clone of a collection of points.

Parameters:

locations - locations to be copied

Returns:

deep copy of the passed collection

wrapper

public static HashSet<Point> wrapper(Point location)

Constructs a collection wrapper for a single point.

Parameters:

location - contents of the wrapper

Returns:

hash set containing the point

getBound

public static int getBound(Collection<Point> locations,
                           Direction dir)

Provides the furthest index in a given direction. This is valid for either Cartesian or interlaced hexagonal coordinates.

Parameters:

locations - locations to be checked

dir - direction of the side

Returns:

furthest index in a given direction

Throws:

IllegalArgumentException - if no points are provided

getWidth

public static int getWidth(Collection<Point> locations)

Returns the width dimension. This is valid for either Cartesian or interlaced hexagonal coordinates.

Parameters:

locations - locations to be checked

Returns:

width dimension

getHeight

public static int getHeight(Collection<Point> locations)

Returns the height dimension. This is valid for either Cartesian or interlaced hexagonal coordinates.

Parameters:

locations - locations to be checked

Returns:

height dimension

getCoordinates

public static ArrayList<Point> getCoordinates(Point start,
                                              Orientation... dir)

Provides the path given from a series of offsets from an original point (not including the start).

Parameters:

start - location from which to start the path

dir - orientation components of the steps in the path

Returns:

path from the starting location and following the directional components

getQuadDistance

public static int getQuadDistance(Point p1,
                                  Point p2)

Provides the shortest distance between two points in Cartesian coordinates.

Parameters:

p1 - location to be evaluated

p2 - location to be evaluated

Returns:

shortest distance between the two points

getQuadDistance

public static int getQuadDistance(Point p1,
                                  Point p2,
                                  boolean diagonals)

Provides the shortest distance between two points.

Parameters:

p1 - location to be evaluated

p2 - location to be evaluated

diagonals - if distance can include diagonals

Returns:

shortest distance between the two points

getHexDistance

public static int getHexDistance(Point p1,
                                 Point p2)

Provides the shortest distance between two points in vertically-aligned interlaced hexagonal coordinates.

Parameters:

p1 - location to be evaluated

p2 - location to be evaluated

Returns:

shortest distance between the two points

getQuadArea

public static HashSet<Point> getQuadArea(Point center,
                                         int radius)

Provides a diamond shaped pattern centered around a given location (empty if radius is less than one).

Parameters:

center - central position in the diamond

radius - distance that the diamond reaches from the center

Returns:

locations forming a diamond

getHexArea

public static HashSet<Point> getHexArea(Point center,
                                        int radius)

Provides a hexagon shaped area with a given radius around a given location (empty if radius is less than one). The shape of the hexagon has the opposite orientation of the grid coordinates.

Parameters:

center - central position in the hexagonal area

radius - distance that the hexagonal area reaches from the center

Returns:

locations forming a hexagonal area

getQuadBorder

public static HashSet<Point> getQuadBorder(Collection<Point> locations,
                                           boolean diagonals)

Provides the locations surrounding a set of positions.

Parameters:

locations - positions to be checked

diagonals - includes bordering diagonals if true, excluded otherwise

Returns:

set of bordering coordinates

getHexBorder

public static HashSet<Point> getHexBorder(Collection<Point> locations)

Provides the points surrounding given positions.

Parameters:

locations - positions to be checked

Returns:

set of bordering coordinates

getQuadPivot

public static Point getQuadPivot(Collection<Point> locations,
                                 Direction orientation)

Provides the central location within a collection of points for standard cartesian rotations.

Parameters:

locations - locations to be checked

orientation - forward direction of the collection (for rounding)

Returns:

pivot location in the collection

getQuadRotateCW

public static ArrayList<Point> getQuadRotateCW(Collection<Point> locations,
                                               Point pivot)

Constructs a set with the points rotated clockwise about the pivot.

Parameters:

locations - locations to be turned

pivot - central point about which to turn

Returns:

set with rotated points

getQuadRotateCCW

public static ArrayList<Point> getQuadRotateCCW(Collection<Point> locations,
                                                Point pivot)

Constructs a set with the points rotated counterclockwise about the pivot.

Parameters:

locations - locations to be turned

pivot - central point about which to turn

Returns:

set with rotated points

getHexRotateCW

public static ArrayList<Point> getHexRotateCW(Collection<Point> locations,
                                              Point pivot)

Constructs a set with the points rotated clockwise about the pivot. This isn't particularly effective, running in O(n*m) where n is the number of locations and m is the average distance from the pivot.

Parameters:

locations - locations to be turned

pivot - central point about which to turn

Returns:

set with rotated points

getHexRotateCCW

public static ArrayList<Point> getHexRotateCCW(Collection<Point> locations,
                                               Point pivot)

Constructs a set with the points rotated counterclockwise about the pivot. This isn't particularly effective, running in O(n*m) where n is the number of locations and m is the average distance from the pivot.

Parameters:

locations - locations to be turned

pivot - central point about which to turn

Returns:

set with rotated points

getHexRotations

public static HashMap<HexDirection,ArrayList<Point>> getHexRotations(Collection<Point> locations,
                                                                     Point pivot,
                                                                     HexDirection patternDir)

Constructs all rotations for a collection of locations around a pivot point. This is a bit more efficient than generating rotations individually.

Parameters:

locations - locations to be turned

pivot - central point about which to turn

patternDir - orientation of the provided locations

Returns:

set with rotated points

getQuadReverse

public static HashSet<Point> getQuadReverse(Set<Point> locations,
                                            Point pivot)

Constructs a set of points with a mirror reversal about both axes along the pivot point. This is equivalent the performing two clockwise or counter-clockwise rotations or both a horizontal and vertical flip (but more efficient).

Parameters:

locations - locations to be reversed

pivot - central point about which to reverse

Returns:

set with reversed points

getHexReverse

public static HashSet<Point> getHexReverse(Set<Point> locations,
                                           Point pivot)

Constructs a set of points with a mirror reversal about all axes along the pivot point. This is equivalent to performing three clockwise or counter-clockwise rotations (but more efficient).

Parameters:

locations - locations to be reversed

pivot - central point about which to reverse

Returns:

set with reversed points

getQuadPath

public static ArrayList<Orientation> getQuadPath(Point p1,
                                                 Point p2,
                                                 boolean diagonal,
                                                 boolean route)

Provides the the shortest directions from one point to another. Any shortest path between two points can be limited to at most two directional components, the order of which is determined by the route parameter. The primary route places the diagonal or horizontal portions first, the secondary places them last.

Parameters:

p1 - start of path

p2 - end of path

diagonal - if true the path may contain diagonal components

route - if true the primary path is listed, otherwise the secondary path is used

Returns:

shortest path from one point to another

getHexPath

public static ArrayList<HexDirection> getHexPath(Point p1,
                                                 Point p2,
                                                 boolean route)

Provides the the shortest directions from one point to another. Any shortest path between two points can be limited to at most two directional components, the order of which is determined by the route parameter. The primary route consists of preference given to directions in the following order: vertical components (up and down), upper diagonals (upper left and right), and finally lower diagonals (lower left and right).

Parameters:

p1 - start of path

p2 - end of path

route - if true the primary path is listed, otherwise the secondary path is used

Returns:

shortest path from one point to another