Runtime

## 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

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

Constructor Summary
`PointListUtilities()`

Method Summary
`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 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`

Field Detail

### 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

Constructor Detail

### PointListUtilities

    public PointListUtilities()

Method Detail

### normalizeSegments

    public static boolean normalizeSegments(PointList points)

  Normalizes the line segments in the polyline. Checks for lines that are with-in 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 with-in 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

Runtime

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp., Borland Software Corp., and others 2005,2006. All rights reserved.