org.eclipse.gmf.runtime.draw2d.ui.geometry
Class PointListUtilities
java.lang.Object
org.eclipse.gmf.runtime.draw2d.ui.geometry.PointListUtilities

public class PointListUtilities
 extends java.lang.Object
A set of utility methods around manipulating PointList objects
Method Summary

static
PointList

calcRoundedCornersPolyline
(
PointList points,
int r,
java.util.Hashtable<java.lang.Integer,java.lang.Integer> rForBendpoint,
boolean calculateAppoxPoints)
Replaces bendpoints (all points except the first and last) in points list by points defining
corresponding arcs. 
static
PointList

calcSmoothPolyline
(
PointList points,
int nSmoothFactor,
int nBezierSteps)
Method calcSmoothPolyline. 
static
PointList

calcSmoothPolyline
(
PointList points,
int nSmoothFactor,
int nBezierSteps,
int nStartIndex,
int nEndIndex)
Calculates the smooth polyline equivalent of the given points list. 
static
Point

calculatePointRelativeToLine
(
PointList pointList,
int fromLine,
int fromEnd,
boolean isPercentage)
Finds a point relative to the pointList passed in based on the parameters passed in. 
static boolean

containsPoint
(
PointList points,
Point point)
Utility method used to check if a point is contained inside a polygon 
static
PointList

copyPoints
(
PointList pointsFrom)
copyPoints
This method is necessary because of an apparrent defect in the getCopy()
routine of PointList class. 
static
PointList

createPointsFromRect
(
Rectangle rBox)
createPointsFromRect 
protected static double

distanceAlong
(java.util.List mySegments,
Point aPoint)
Method distanceAlong. 
static boolean

findIntersections
(
PointList points,
PointList poly,
PointList intersections,
PointList distances)
Method findIntersections. 
static int

findNearestLineSegIndexOfPoint
(
PointList points,
Point ptCoord)
Method findNearestLineSegIndexOfPoint. 
static java.util.List

getLineSegments
(
PointList points)
Method getLineSegments. 
static
LineSeg

getNearestSegment
(java.util.List mySegments,
int xCoord,
int yCoord)
Static utility method to get the nearest segment in the polyline
from the given coordinates. 
static
Point

getPointsInfimum
(
PointList points)
Method getPointsSupremum. 
static long

getPointsLength
(
PointList points)
Method getPointsLength. 
static
Point

getPointsSupremum
(
PointList points)
Method getPointsSupremum. 
protected static long

length
(java.util.List mySegments)
Method length. 
static boolean

normalizeSegments
(
PointList points)
Normalizes the line segments in the polyline. 
static boolean

normalizeSegments
(
PointList points,
int straightLineTolerance)
Normalizes the line segments in the polyline. 
static
Point

pickClosestPoint
(
PointList points,
Point p)
Assumption: Points in the PointList and Point p lie on the same line. 
static
Point

pickFarestPoint
(
PointList points,
Point p)
Assumption: Points in the PointList and Point p lie on the same line. 
protected static
Point

pointOn
(java.util.List mySegments,
long theDistance,
LineSeg.KeyPoint fromKeyPoint,
Point ptResult)
Method pointOn. 
static
Point

pointOn
(
PointList points,
long theDistance,
LineSeg.KeyPoint fromKeyPoint,
Point ptResult)
Calculate the point on the polyline given a distance from a key point. 
static
PointList

routeAroundPoint
(
PointList points,
Point ptCenter,
int nHeight,
int nWidth,
int nSmoothFactor,
int nInclineOffset,
boolean bTop)
Method routeAroundPoint. 
static
PointList

routeAroundPoly
(
PointList points,
PointList poly,
int nSmoothFactor,
boolean bShortestDistance,
boolean bIncludeIntersectionPoints,
int nBuffer)
Routes this polyline around another polyline that is presumably intersecting with
it. 
static
PointList

routeAroundRect
(
PointList points,
Rectangle rBox,
int nSmoothFactor,
boolean bIncludeIntersectionPoints,
int nBuffer)
Method routeAroundRect. 
protected static double

segmentDistance
(java.util.List mySegments,
LineSeg theSegment,
LineSeg.KeyPoint uptoKeyPoint)
Method segmentDistance. 
Methods inherited from class java.lang.Object

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

DEFAULT_BEZIERLINES
public static final int DEFAULT_BEZIERLINES
 Constant that is the default number of lines that a bezier is approximated by as a polyline
point list.

See Also:

Constant Field Values
DEFAULT_CORNER_APPROXIMATION_PTS
public static final int DEFAULT_CORNER_APPROXIMATION_PTS

Since:
 1.2

See Also:

Constant Field Values
PointListUtilities
public PointListUtilities()
normalizeSegments
public static boolean normalizeSegments(
PointList points)
 Normalizes the line segments in the polyline. Checks for lines that are within a threshold for length
and removes them. Additionally, it will remove points that that adjacent segments that are both
horizontal, or both vertical.


Parameters:

points
 PointList
to be normalized

Returns:

boolean
true
if segments were changed, false
otherwise
normalizeSegments
public static boolean normalizeSegments(
PointList points,
int straightLineTolerance)
 Normalizes the line segments in the polyline. Checks for lines that are within a threshold for length
and removes them. Additionally, it will remove points that that adjacent segments that are both
horizontal, or both vertical. Will utilize a tolerance value to determine if segments needs to flattened
or not.


Parameters:

points
 PointList
to normalize 
straightLineTolerance
 the tolerance value within which indicates the line is straight in
relative coordinates.

Returns:

boolean
true
if segments were changed, false
otherwise
getPointsSupremum
public static
Point getPointsSupremum(
PointList points)
 Method getPointsSupremum.
Get points representing the extrema for this poly line.


Parameters:

points
 PointList to calculate the highest point from.

Returns:
 Point value of the highest point in the bounding box of the
polyline.
getPointsInfimum
public static
Point getPointsInfimum(
PointList points)
 Method getPointsSupremum.
Get points representing the minimum for this poly line.


Parameters:

points
 PointList to calculate the minimum point from.

Returns:
 Point value of the lowest point in the bounding box of the
polyline.
createPointsFromRect
public static
PointList createPointsFromRect(
Rectangle rBox)
 createPointsFromRect


Parameters:

rBox
 Rectangle to base the PointList from

Returns:
 PointList that is equivalent to the Rectangle
routeAroundRect
public static
PointList routeAroundRect(
PointList points,
Rectangle rBox,
int nSmoothFactor,
boolean bIncludeIntersectionPoints,
int nBuffer)
 Method routeAroundRect.
Route this polyline around a rectangle that is presumably intersecting with
it.


Parameters:

points
 PointList that will be modified to route around the given rectangle 
rBox
 the Rectangle
around which the routing will occur. 
nSmoothFactor
 the int
smooth factor to route the line with
0  None, 15  some, 30  lots 
bIncludeIntersectionPoints
 the boolean
determining whether to include the
points that intersect with the rectangle in the newly routed polyline. 
nBuffer
 the int
buffer around the rectangle.

Returns:

PointList
that is the newly routed version of points
of null
if operation was not successful or if the calculation is not possible.
getLineSegments
public static java.util.List getLineSegments(
PointList points)
 Method getLineSegments.
Converts the points of this polyline into a list of
LineSeg
objects


Parameters:

points
 PointList to get LineSeg equivalents of.

Returns:
 List of LineSeg objects.
routeAroundPoly
public static
PointList routeAroundPoly(
PointList points,
PointList poly,
int nSmoothFactor,
boolean bShortestDistance,
boolean bIncludeIntersectionPoints,
int nBuffer)
 Routes this polyline around another polyline that is presumably intersecting with
it.


Parameters:

points
 the PointList
that is to be modified based on
the routing calculations made around the poly
parameter. 
poly
 the PolylinePointList
around which the routing will occur. 
nSmoothFactor
 the int
smooth factor to route the line with
0  None, 15  some, 30  lots 
bShortestDistance
 the boolean
determining whether to use the
shortest distance possible to achieve this or else minimally modify the existing polyline. 
bIncludeIntersectionPoints
 the boolean
determining whether to include the
points that intersect with the rectangle in the newly routed polyline. 
nBuffer
 the int
buffer around the rectangle.

Returns:

PointList
that is the newly routed version of points
of null
if operation was not successful or if the calculation is not possible.
copyPoints
public static
PointList copyPoints(
PointList pointsFrom)
 copyPoints
This method is necessary because of an apparrent defect in the getCopy()
routine of PointList class. It is initializing the copy based on size
but then making the copy based on the array allocation which may be different
causing an ArrayIndexOutOfBounds exception.


Parameters:

pointsFrom


Returns:
 PointList
calcSmoothPolyline
public static final
PointList calcSmoothPolyline(
PointList points,
int nSmoothFactor,
int nBezierSteps)
 Method calcSmoothPolyline.
Calculate the smooth polyline approximation of this polyline based on
a smooth factor.


Parameters:

points
 the PointList
that is used to calculate the
smooth point list from. 
nSmoothFactor
 the int
smooth factor to smooth the line with
0  None, 15  some, 30  lots 
nBezierSteps
 the int
number of line steps used to approximate the smooth curve

Returns:
 PolylinePointList List of PolylinePoint representing the smooth
polyline.
calcSmoothPolyline
public static
PointList calcSmoothPolyline(
PointList points,
int nSmoothFactor,
int nBezierSteps,
int nStartIndex,
int nEndIndex)
 Calculates the smooth polyline equivalent of the given points list. It will extrapolate a bezier
approximation in polylines that resembles a curved line.


Parameters:

points
 the PointList
that is used to calculate the smooth bezier approximation. 
nSmoothFactor
 the int
smooth factor to smooth the line with
0  None, 15  some, 30  lots 
nBezierSteps
 the int
number of line steps used to approximate the smooth curve 
nStartIndex
 the int
index in the line to start from to create the smooth approximation 
nEndIndex
 the int
index in the line to end at to create the smooth approximation

Returns:
 PolylinePointList List of PolylinePoint representing the smooth
polyline.
pointOn
public static
Point pointOn(
PointList points,
long theDistance,
LineSeg.KeyPoint fromKeyPoint,
Point ptResult)
 Calculate the point on the polyline given a distance from a key point.


Parameters:

points
 the PointList
to calculate the point on the polyline. 
theDistance
 the long
x coordinate of the point 
fromKeyPoint
 the int
constant value indicating the key point
Origin, Terminus, Midpoint 
ptResult
 the Point
where the resulting point value is set.

Returns:
 Point the calculated point residing on the polyline.
getPointsLength
public static long getPointsLength(
PointList points)
 Method getPointsLength.
Static utility function to calculate the length of a series of
points if interpreted as line segments.


Parameters:

points
 PointList to calculate the length of.

Returns:
 length of the line segments
length
protected static long length(java.util.List mySegments)
 Method length.
Static utility function to calculate the length of a series of
line segments.


Parameters:

mySegments
 List of line segments to calculate the length of.

Returns:
 long length of the line segments
getNearestSegment
public static
LineSeg getNearestSegment(java.util.List mySegments,
int xCoord,
int yCoord)
 Static utility method to get the nearest segment in the polyline
from the given coordinates.


Parameters:

mySegments
 the List
of LineSeg
objects 
xCoord
 the int
x coordinate of the point 
yCoord
 the int
y coordinate of the point

Returns:
 the
LineSeg
by reference which is closest to the given coordinates.
pointOn
protected static
Point pointOn(java.util.List mySegments,
long theDistance,
LineSeg.KeyPoint fromKeyPoint,
Point ptResult)
 Method pointOn.
Static utility function used by
pointOn
.


Parameters:

mySegments
 
theDistance
 the long
x coordinate of the point 
fromKeyPoint
 the int
constant value indicating the key point
Origin, Terminus, Midpoint 
ptResult
 the Point
where the resulting point value is set.

Returns:
 Point the calculated point residing on the polyline.
distanceAlong
protected static double distanceAlong(java.util.List mySegments,
Point aPoint)
 Method distanceAlong.
Static utility function to calculate the distanceAlong a series of line segments
a given point is on the line.


Parameters:

mySegments
 
aPoint
 Point to calculate the distance along the polyline of.

Returns:
 double value of the distance along the polyline of the given point.
segmentDistance
protected static double segmentDistance(java.util.List mySegments,
LineSeg theSegment,
LineSeg.KeyPoint uptoKeyPoint)
 Method segmentDistance.
Compute the percentage of the distance along this polyline
that the given segment occurs. If the keypoint specified is
Origin, then the given segment will not be included in the
percentage; if the keypoint is Midpoint, then half of the
length will be included; if the keypoint is Terminus, the
the whole length will be included. The segment must be a
segment of this polyline.


Parameters:

mySegments
 
theSegment
 
uptoKeyPoint


Returns:
 double
routeAroundPoint
public static
PointList routeAroundPoint(
PointList points,
Point ptCenter,
int nHeight,
int nWidth,
int nSmoothFactor,
int nInclineOffset,
boolean bTop)
 Method routeAroundPoint.
Calculate a new routed version of this polyline that will route itself around a
given point.


Parameters:

points
 PointList to modify 
ptCenter
 the Point
around which the routing will occur. 
nHeight
 the int
height to route around the point. 
nWidth
 the int
width to route around the point. 
nSmoothFactor
 the int
smooth factor to route the line with
0  None, 15  some, 30  lots 
nInclineOffset
 the int
amount to incline the routed points. 
bTop
 the boolean
route above or below the point on the line.

Returns:

PointList
that is the newly routed version of points
of null
if operation was not successful or if the calculation is not possible.
findNearestLineSegIndexOfPoint
public static int findNearestLineSegIndexOfPoint(
PointList points,
Point ptCoord)
 Method findNearestLineSegIndexOfPoint.
Calculate the nearest line segment index distance wise to the given point.


Parameters:

points
 PointList to calculate the nearest line segment of. 
ptCoord
 the Point
to test containment of.

Returns:
 int Index of line segment that is nearest in the polyline to the given point.
The index is 1 based where 1 represents the first segment.
findIntersections
public static boolean findIntersections(
PointList points,
PointList poly,
PointList intersections,
PointList distances)
 Method findIntersections.
Find all intersection points between this polyline and another polyline passed
into the method.


Parameters:

points
 PointList to calculate interesections with. 
poly
 the PointList
to calculate intersections with. 
intersections
 the PointList
containing the resulting calculated
intersection points. 
distances
 the PointList
containing point values representing the
distance along the polyline the intersections occur.

Returns:
 boolean true if intersections could be calculated, false otherwise.
calculatePointRelativeToLine
public static
Point calculatePointRelativeToLine(
PointList pointList,
int fromLine,
int fromEnd,
boolean isPercentage)
 Finds a point relative to the pointList passed in based on the parameters passed in.


Parameters:

pointList
 the PointList

fromLine
 distance off the line 
fromEnd
 distance from the starting point of the line (i.e. distance from source end along the line) 
isPercentage
 is the fromEnd given as a percentage?

Returns:
 Point
pickClosestPoint
public static
Point pickClosestPoint(
PointList points,
Point p)
 Assumption: Points in the
PointList
and Point
p lie on the same line.
Returns the Point
from the PointList
closest to @param p


Parameters:

points
  the list of points to select the result from 
p
  the point to which the closest point must be found

Returns:
 the
Point
from the PointList
closest to @param p
pickFarestPoint
public static
Point pickFarestPoint(
PointList points,
Point p)
 Assumption: Points in the
PointList
and Point
p lie on the same line.
Returns the Point
from the PointList
closest to @param p


Parameters:

points
  the list of points to select the result from 
p
  the point to which the closest point must be found

Returns:
 the
Point
from the PointList
closest to @param p
containsPoint
public static boolean containsPoint(
PointList points,
Point point)
 Utility method used to check if a point is contained inside a polygon


Parameters:

points
 the polygon 
point
 point to check

Returns:
 true is the pointis inside the polygon, otherwise false
calcRoundedCornersPolyline
public static
PointList calcRoundedCornersPolyline(
PointList points,
int r,
java.util.Hashtable<java.lang.Integer,java.lang.Integer> rForBendpoint,
boolean calculateAppoxPoints)
 Replaces bendpoints (all points except the first and last) in points list by points defining
corresponding arcs. That is, each bendpoint is replaced with the start and end point of the arc,
and if calculateApproxPoints is true, there will also be points in between that approximate the arc.
Arc size is r. Sometimes, segment between two bendpoints is shorter than r. In that case, arc size for
both bendpoints has to be reduced to be half of the segment length, so that both arcs can fit.
These reduced arc sizes (if any) are kept in rForBendpoint hashtable.


Parameters:

points
 Initial list of connection points 
r
 Size (radius) of the arc that should replace bendpoint 
rForBendpoint
 Hashtable keeping track of bendpoints whose arcs have to be smaller than r 
calculateAppoxPoints
 Indicates if arcs replacing bendpoints should be approximated

Returns:


Since:
 1.2
Guidelines for using Eclipse APIs.
Copyright (c) IBM Corp., Borland Software Corp., and others 2005,2006. All rights reserved.