Package geomss.geom

Class PointString<E extends GeomPoint>

java.lang.Object

geomss.geom.AbstractGeomElement<T>

geomss.geom.AbstractGeomList<T,E>

geomss.geom.AbstractPointGeomList<PointString<E>,E>

geomss.geom.PointString<E>

Type Parameters:

E - The type of GeomPoint contained in this list of points.

All Implemented Interfaces:

GeomElement<PointString<E>>, GeometryList<PointString<E>,E>, PointGeometry<PointString<E>>, Transformable<PointString<E>>, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable, java.lang.Iterable<E>, java.util.Collection<E>, java.util.List<E>, javolution.lang.Reusable, javolution.xml.XMLSerializable

public final class PointString<E extends GeomPoint>
extends AbstractPointGeomList<PointString<E>,E>

A PointString is a collection of GeomPoint objects that make up a "string of points". Any number of points may be added to a string, but all points in a string must have the same dimensions.

WARNING: This list allows geometry to be stored in different units. If consistent units are required, then the user must specifically convert the list items.

Modified by: Joseph A. Huwaldt

Version:

February 17, 2025

Author:

Joseph A. Huwaldt, Date: March 5, 2003

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static double	GTOL	Generic/default tolerance for use in root finders, etc.

Fields inherited from class geomss.geom.AbstractGeomElement

RESOURCES

Method Summary

Modifier and Type	Method	Description
void	add(int index, E value)	Inserts the specified GeomPoint at the specified position in this list.
boolean	addAll(int index, java.util.Collection<? extends E> c)	Inserts all of the GeomPoint objects in the specified collection into this list at the specified position.
PointString<E>	copy()	Returns a copy of this PointString instance allocated by the calling thread (possibly on the stack).
PointString<E>	copyToReal()	Return a copy of this object with any transformations or subranges removed (applied).
PointString	enrich()	Returns a new PointString that is identical to this string but with a new point linearly interpolated half-way between each of the existing points.
Point	getAverage()	Calculate the average or centroid of all the points in this PointString.
int	getNumberOfPoints()	Return the total number of points in this geometry element.
PointString<E>	getRange(int first, int last)	Returns the range of elements in this list from the specified start and ending indexes.
PointString	getTransformed(GTransform transform)	Returns transformed version of this element.
boolean	isDegenerate(Parameter<javax.measure.quantity.Length> tol)	Return true if this string of points is degenerate (i.e.: has length less than the specified tolerance).
boolean	isLine(Parameter<javax.measure.quantity.Length> tol)	Returns true if this string of points is a line to within the specified tolerance.
boolean	isPlanar(Parameter<javax.measure.quantity.Length> tol)	Return true if this string of points is planar or false if it is not.
Parameter<javax.measure.quantity.Length>	length()	Returns the length of this PointString in terms of the sum of the distances between each consecutive point in the string.
static void	main(java.lang.String[] args)	Tests the methods in this class.
static PointString	newInstance()	Returns a new, preallocated or recycled PointString instance (on the stack when executing in a StackContext), that can store a list of GeomPoint objects.
static PointString	newInstance(java.lang.String name)	Returns a new, preallocated or recycled PointString instance (on the stack when executing in a StackContext) with the specified name, that can store a list of GeomPoint objects.
static void	recycle(PointString instance)	Recycles a case instance immediately (on the stack when executing in a StackContext).
PointString<E>	reverse()	Returns an new PointString with the elements in this list in reverse order.
E	set(int index, E element)	Replaces the GeomPoint at the specified position in this list with the specified element.
PointString<E>	sort(int dim, boolean removeDup, Parameter<javax.measure.quantity.Length> tol)	Return a new PointString with the points in this list sorted into ascending order with respect to the specified coordinate dimension.
PointString<E>	thin()	Returns a new PointString that is identical to this string but with every other point removed.
PointString	to(javax.measure.unit.Unit<javax.measure.quantity.Length> unit)	Returns the equivalent to this list but with all the elements stated in the specified unit.
PointString	toDimension(int newDim)	Return the equivalent of this list converted to the specified number of physical dimensions.
PointString	unique(Parameter<javax.measure.quantity.Length> tol)	Returns a new PointString that contains the points in this PointString with all duplicate points removed.
static <E extends GeomPoint> PointString<E>	valueOf(E... elements)	Return a PointString made up of the GeomPoint objects in the specified array.
static <E extends GeomPoint> PointString<E>	valueOf(java.lang.String name, E... elements)	Return a PointString made up of the GeomPoint objects in the specified array.
static <E extends GeomPoint> PointString<E>	valueOf(java.lang.String name, java.util.Collection<E> elements)	Return a PointString made up of the GeomPoint objects in the specified collection.

Methods inherited from class geomss.geom.AbstractPointGeomList

getPhyDimension

Methods inherited from class geomss.geom.AbstractGeomList

add, add, add, addAll, addAll, addAll, clear, contains, containsAll, containsGeometry, equals, get, get, getAll, getBoundsMax, getBoundsMin, getFirst, getIndexFromName, getLast, getLimitPoint, getParDimension, getUnit, hashCode, indexOf, isEmpty, isValid, iterator, lastIndexOf, listIterator, listIterator, remove, remove, remove, removeAll, reset, retainAll, size, subList, toArray, toArray, toText, unmodifiableList

Methods inherited from class geomss.geom.AbstractGeomElement

addChangeListener, clone, compareTo, getAllUserData, getID, getName, getUserData, putAllUserData, putUserData, removeChangeListener, removeUserData, setName, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream, toArray

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface geomss.geom.GeomElement

addChangeListener, getAllUserData, getBoundsMax, getBoundsMin, getID, getLimitPoint, getName, getParDimension, getUnit, getUserData, isValid, putAllUserData, putUserData, removeChangeListener, removeUserData, setName, size, toText

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface java.util.List

replaceAll, sort, spliterator

Field Detail

GTOL

public static final double GTOL

Generic/default tolerance for use in root finders, etc.

See Also:

Constant Field Values

Method Detail

newInstance

public static PointString newInstance()

Returns a new, preallocated or recycled PointString instance (on the stack when executing in a StackContext), that can store a list of GeomPoint objects.

Returns:

A new PointString instance.

newInstance

public static PointString newInstance(java.lang.String name)

Returns a new, preallocated or recycled PointString instance (on the stack when executing in a StackContext) with the specified name, that can store a list of GeomPoint objects.

Parameters:

name - The name to be assigned to this list (may be null).

Returns:

A new PointString instance with the specified name.

valueOf

public static <E extends GeomPoint> PointString<E> valueOf(java.lang.String name,
                                                           java.util.Collection<E> elements)

Return a PointString made up of the GeomPoint objects in the specified collection.

Type Parameters:

E - The type of GeomPoint contained in this list of points.

Parameters:

name - The name to be assigned to this list (may be null).

elements - A collection of points. May not be null.

Returns:

A new PointString instance made up of the specified points.

valueOf

public static <E extends GeomPoint> PointString<E> valueOf(java.lang.String name,
                                                           E... elements)

Return a PointString made up of the GeomPoint objects in the specified array.

Type Parameters:

E - The type of GeomPoint contained in this list of points.

Parameters:

name - The name to be assigned to this list (may be null).

elements - An array of points. May not be null.

Returns:

A new PointString instance made up of the specified points.

valueOf

public static <E extends GeomPoint> PointString<E> valueOf(E... elements)

Return a PointString made up of the GeomPoint objects in the specified array.

Type Parameters:

E - The type of GeomPoint contained in this list of points.

Parameters:

elements - An array of points. May not be null.

Returns:

A new PointString instance made up of the specified points.

getNumberOfPoints

public int getNumberOfPoints()

Return the total number of points in this geometry element.

Specified by:

getNumberOfPoints in interface PointGeometry<E extends GeomPoint>

Overrides:

getNumberOfPoints in class AbstractPointGeomList<PointString<E extends GeomPoint>,E extends GeomPoint>

Returns:

The total number of points in this geometry element.

getRange

public PointString<E> getRange(int first,
                               int last)

Returns the range of elements in this list from the specified start and ending indexes.

Specified by:

getRange in interface GeometryList<PointString<E extends GeomPoint>,E extends GeomPoint>

Specified by:

getRange in class AbstractGeomList<PointString<E extends GeomPoint>,E extends GeomPoint>

Parameters:

first - index of the first element to return (0 returns the 1st element, -1 returns the last, etc).

last - index of the last element to return (0 returns the 1st element, -1 returns the last, etc).

Returns:

the list of elements in the given range from this list.

Throws:

java.lang.IndexOutOfBoundsException - if the given index is out of range: index ≥ size()

reverse

public PointString<E> reverse()

Returns an new PointString with the elements in this list in reverse order.

Specified by:

reverse in interface GeometryList<PointString<E extends GeomPoint>,E extends GeomPoint>

Specified by:

reverse in class AbstractGeomList<PointString<E extends GeomPoint>,E extends GeomPoint>

Returns:

A new PointString with the elements in this string in reverse order.

thin

public PointString<E> thin()

Returns a new PointString that is identical to this string but with every other point removed. The 1st point (index = 0) and last point (index = size()-1) are always retained. If there are less than 3 points in the string, then a new string is returned that contains the same points as this string.

Returns:

A new PointString identical to this one but with every other point removed.

enrich

public PointString enrich()

Returns a new PointString that is identical to this string but with a new point linearly interpolated half-way between each of the existing points. If there are less than 2 points in the string, then a new string is returned that contains the same point as this string.

Returns:

A new PointString that is identical to this string but with a new point linearly interpolated half-way between each of the existing points.

unique

public PointString unique(Parameter<javax.measure.quantity.Length> tol)

Returns a new PointString that contains the points in this PointString with all duplicate points removed.

Parameters:

tol - The tolerance for determining if the points in this PointString are approx. equal. May not be null.

length

public Parameter<javax.measure.quantity.Length> length()

Returns the length of this PointString in terms of the sum of the distances between each consecutive point in the string.

Returns:

The length of the string: sum(point(i).distance(point(i-1))).

getAverage

public Point getAverage()

Calculate the average or centroid of all the points in this PointString.

Returns:

The average or centroid of all the points in this PointString.

isDegenerate

public boolean isDegenerate(Parameter<javax.measure.quantity.Length> tol)

Return true if this string of points is degenerate (i.e.: has length less than the specified tolerance).

Parameters:

tol - The tolerance for determining if this string of points is degenerate. May not be null.

Returns:

true if this string of points is degenerate

isLine

public boolean isLine(Parameter<javax.measure.quantity.Length> tol)

Returns true if this string of points is a line to within the specified tolerance.

Parameters:

tol - The tolerance for determining if this string of points is a line.

Returns:

true if this string of points is a line

isPlanar

public boolean isPlanar(Parameter<javax.measure.quantity.Length> tol)

Return true if this string of points is planar or false if it is not.

Parameters:

tol - The geometric tolerance to use in determining if the string of points is planar.

Returns:

true if this string of points is planar

sort

public PointString<E> sort(int dim,
                           boolean removeDup,
                           Parameter<javax.measure.quantity.Length> tol)

Return a new PointString with the points in this list sorted into ascending order with respect to the specified coordinate dimension. This can also be used to remove duplicate points after the list has been sorted. To sort in descending order, use this method followed immediately by reverse() (e.g.: str.sort(Point.X,false,null).reverse();).

Parameters:

dim - The physical coordinate dimension to be sorted (e.g.: 0=X, 1=Y, etc).

removeDup - Duplicate points are removed from the output if this is true.

tol - The tolerance for identifying duplicate points. If null is passed, then essentially exact equality is required (if removeDup is false, you may pass null).

Returns:

A new PointString with the points in this list sorted into ascending order with respect to the specified coordinate dimension and possibly with duplicate points removed.

toDimension

public PointString toDimension(int newDim)

Return the equivalent of this list converted to the specified number of physical dimensions. If the number of dimensions is greater than this element, then zeros are added to the additional dimensions. If the number of dimensions is less than this element, then the extra dimensions are simply dropped (truncated). If the new dimensions are the same as the dimension of this element, then this list is simply returned.

Parameters:

newDim - The dimension of the element to return.

Returns:

The equivalent of this list converted to the new dimensions.

to

public PointString to(javax.measure.unit.Unit<javax.measure.quantity.Length> unit)

Returns the equivalent to this list but with all the elements stated in the specified unit.

Parameters:

unit - the length unit of the list to be returned. May not be null.

Returns:

an equivalent to this list but stated in the specified unit.

Throws:

javax.measure.converter.ConversionException - if the the input unit is not a length unit.

copy

public PointString<E> copy()

Returns a copy of this PointString instance allocated by the calling thread (possibly on the stack).

Returns:

an identical and independent copy of this object.

copyToReal

public PointString<E> copyToReal()

Return a copy of this object with any transformations or subranges removed (applied).

Returns:

A copy of this object with any transformations or subranges removed (applied).

getTransformed

public PointString getTransformed(GTransform transform)

Returns transformed version of this element. The returned object implements GeomTransform and contains transformed versions of the contents of this list as children.

Parameters:

transform - The transformation to apply to this geometry. May not be null.

Returns:

A new PointString that is identical to this one with the specified transformation applied.

Throws:

DimensionException - if this element is not 3D.

set

public E set(int index,
             E element)

Replaces the GeomPoint at the specified position in this list with the specified element. Null elements are ignored. The input element must have the same physical dimensions as the other items in this list, or an exception is thrown.

Specified by:

set in interface java.util.List<E extends GeomPoint>

Overrides:

set in class AbstractPointGeomList<PointString<E extends GeomPoint>,E extends GeomPoint>

Parameters:

index - The index of the element to replace (0 returns the 1st element, -1 returns the last, -2 returns the 2nd from last, etc).

element - The element to be stored at the specified position. May not be null.

Returns:

The element previously at the specified position in this list.

Throws:

java.lang.IndexOutOfBoundsException - - if index > size()

DimensionException - if the input element's dimensions are different from this list's dimensions.

add

public void add(int index,
                E value)

Inserts the specified GeomPoint at the specified position in this list. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices). Null values are ignored. The input value must have the same physical dimensions as the other items in this list, or an exception is thrown.

Note: If this method is used concurrent access must be synchronized (the list is not thread-safe).

Specified by:

add in interface java.util.List<E extends GeomPoint>

Overrides:

add in class AbstractPointGeomList<PointString<E extends GeomPoint>,E extends GeomPoint>

Parameters:

index - the index at which the specified element is to be inserted. (0 returns the 1st element, -1 returns the last, -2 returns the 2nd from last, etc).

value - the element to be inserted. May not be null.

Throws:

java.lang.IndexOutOfBoundsException - if index > size()

DimensionException - if the input value dimensions are different from this list's dimensions.

addAll

public boolean addAll(int index,
                      java.util.Collection<? extends E> c)

Inserts all of the GeomPoint objects in the specified collection into this list at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in this list in the order that they are returned by the specified collection's iterator. The behavior of this operation is unspecified if the specified collection is modified while the operation is in progress. Note that this will occur if the specified collection is this list, and it's nonempty. The input elements must have the same physical dimensions as the other items in this list, or an exception is thrown.

Specified by:

addAll in interface java.util.List<E extends GeomPoint>

Overrides:

addAll in class AbstractGeomList<PointString<E extends GeomPoint>,E extends GeomPoint>

Parameters:

index - index at which to insert first element from the specified collection.

c - Elements to be inserted into this collection. May not be null.

Returns:

true if this collection changed as a result of the call

Throws:

DimensionException - if the input element's dimensions are different from this list's dimensions.

recycle

public static void recycle(PointString instance)

Recycles a case instance immediately (on the stack when executing in a StackContext).

Parameters:

instance - The instance to be recycled immediately.

main

public static void main(java.lang.String[] args)

Tests the methods in this class.

Parameters:

args - Command-line arguments (not used).