AlgART Home
net.algart.math

## Class Point

• java.lang.Object
• net.algart.math.Point
• All Implemented Interfaces:
java.lang.Comparable<Point>

```public class Point
extends java.lang.Object
implements java.lang.Comparable<Point>```

Point in multidimensional space with real coordinates. Represented as an array of double numbers.

All calculations in this class are performed in strictfp mode, so the result is absolutely identical on all platforms.

This class is immutable and thread-safe: there are no ways to modify settings of the created instance.

Since:
JDK 1.5
Version:
1.2
Author:
Daniel Alievsky
`IPoint`
• ### Method Summary

All Methods
Modifier and Type Method and Description
`Point` `add(Point point)`
Returns the vector sum of this and given point: every coordinate #i in the result is thisInstance.`coord(i)`+point.`coord(i)`.
`Point` `addToAllCoordinates(double increment)`
Adds the given value to all coordinates of this point and returns the resulting point: every coordinate #i in the result is thisInstance.`coord(i)`+increment.
`int` `compareTo(Point o)`
Compares points lexicographically.
`int` ```compareTo(Point o, int firstCoordIndex)```
Compares points lexicographically alike `compareTo(Point)` method, but with the cyclical shift of all indexes of coordinates: the coordinate #firstCoordIndex instead of x, #firstCoordIndex+1 instead of y, etc.
`double` `coord(int coordIndex)`
Returns the coordinate #coordIndex: x-coordinate for coordIndex=0, y-coordinate for coordIndex=1, etc.
`int` `coordCount()`
Returns the number of dimensions of this point.
`double[]` `coordinates()`
Returns all coordinates of this point.
`double[]` `coordinates(double[] result)`
Copies all coordinates of this point into result array.
`double` `distanceFrom(java.util.Collection<Point> points)`
Returns the minimal distance between this point and any point from the passed collection.
`double` `distanceFromOrigin()`
Returns the distance between this point and the origin of coordinates.
`boolean` `equals(java.lang.Object obj)`
Indicates whether some other point is equal to this instance, that is the number of coordinates is the same and all corresponding coordinates are equal.
`int` `hashCode()`
Returns the hash code of this point.
`boolean` `isInteger()`
Returns true if and only if this point is really integer, that is if for any its coordinate xi=`coord`(i) the Java expression xi==(long)xi is true.
`boolean` `isOrigin()`
Returns true if this point is the origin of coordinates.
`Point` `max(Point point)`
Returns the coordinate-wise maximum of this and given point: every coordinate #i in the result is Math.max(thisInstance.`coord(i)`,point.`coord(i)`).
`static Point` `maxValue(int coordCount)`
Returns the "maximal" point in n-dimensional space, where n=coordCount is the argument of this method, that is the point with all coordinates are equal to Double.POSITIVE_INFINITY.
`Point` `min(Point point)`
Returns the coordinate-wise minimum of this and given point: every coordinate #i in the result is Math.min(thisInstance.`coord(i)`,point.`coord(i)`).
`static Point` `minValue(int coordCount)`
Returns the "minimal" point in n-dimensional space, where n=coordCount is the argument of this method, that is the point with all coordinates are equal to Double.NEGATIVE_INFINITY.
`Point` `multiply(double multiplier)`
Returns the product of this point and the given scalar multiplier: every coordinate #i in the result is thisInstance.`coord(i)`*multiplier.
`static Point` `origin(int coordCount)`
Returns the origin of coordinates in n-dimensional space, where n=coordCount is the argument of this method.
`Point` `projectionAlongAxis(int coordIndex)`
Returns the projection of this point along the given axis with the number of coordinates, decreased by 1.
`double` `scalarProduct(Point point)`
Returns the scalar product of this and given point.
`Point` `scale(double... multipliers)`
Returns new point, each coordinate #i of which is thisInstance.`coord(i)`*multipliers[i].
`void` ```scaleAndShift(double[] resultCoordinates, double[] multipliers, Point shift)```
More efficient version of `scaleAndShift(double[], Point)` method, which stores the coordinates of the result in the passed Java array instead of creating new instance of this class.
`Point` ```scaleAndShift(double[] multipliers, Point shift)```
Returns new point, each coordinate #i of which is shift.`coord(i)`+thisInstance.`coord(i)`*multipliers[i].
`Point` ```shiftAlongAxis(int coordIndex, double shift)```
Returns this point shifted by the passed shift along the axis #coordIndex.
`Point` `subtract(Point point)`
Returns the vector difference of this and given point: every coordinate #i in the result is thisInstance.`coord(i)`-point.`coord(i)`.
`Point` `symmetric()`
Returns the symmetric point relatively the origin of coordinates.
`IPoint` `toIntegerPoint()`
Equivalent to `IPoint.valueOf`(thisInstance).
`IPoint` `toRoundedPoint()`
Equivalent to `IPoint.roundOf`(thisInstance).
`java.lang.String` `toString()`
Returns a brief string description of this object.
`static Point` `valueOf(double... coordinates)`
Returns a new point with the given set of coordinates: x, y, z, ...
`static Point` `valueOf(IPoint iPoint)`
Returns a new point with the same coordinates as the given integer point.
`static Point` ```valueOfEqualCoordinates(int coordCount, double filler)```
Returns a new point in n-dimensional space, where n=coordCount and all coordinates of the point are equal to the given value filler.
`double` `x()`
Returns the x-coordinate: equivalent to `coord(0)`.
`double` `y()`
Returns y-coordinate: equivalent to `coord(1)`.
`double` `z()`
Returns z-coordinate: equivalent to `coord(2)`.
• ### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`
• ### Method Detail

• #### valueOf

`public static Point valueOf(double... coordinates)`
Returns a new point with the given set of coordinates: x, y, z, ... For example, valueOf(x,y) returns the 2D point with given coordinates.

The coordinates array must contain at least 1 element.

The passed coordinates array is cloned by this method: no references to it are maintained by the created object.

Parameters:
`coordinates` - cartesian coordinates of the point.
Returns:
the point with the given coordinates.
Throws:
`java.lang.NullPointerException` - if the passed array is null.
`java.lang.IllegalArgumentException` - if the passed array is empty (no coordinates are passed).
• #### valueOfEqualCoordinates

```public static Point valueOfEqualCoordinates(int coordCount,
double filler)```
Returns a new point in n-dimensional space, where n=coordCount and all coordinates of the point are equal to the given value filler. For example, valueOfEqualCoordinates(3, 1) returns the 3D point (1,1,1). If filler==0, this method is equivalent to `origin(coordCount)`.
Parameters:
`coordCount` - the number of dimensions.
`filler` - the value of each coordinate of the created point.
Returns:
the point with equal coordinates.
Throws:
`java.lang.IllegalArgumentException` - if the passed number of dimensions is zero or negative.
• #### origin

`public static Point origin(int coordCount)`
Returns the origin of coordinates in n-dimensional space, where n=coordCount is the argument of this method.
Parameters:
`coordCount` - the number of dimensions.
Returns:
the origin of coordinates in n-dimensional space.
Throws:
`java.lang.IllegalArgumentException` - if the passed number of dimensions is zero or negative.
• #### minValue

`public static Point minValue(int coordCount)`
Returns the "minimal" point in n-dimensional space, where n=coordCount is the argument of this method, that is the point with all coordinates are equal to Double.NEGATIVE_INFINITY.
Parameters:
`coordCount` - the number of dimensions.
Returns:
the "minimal" point in n-dimensional space.
Throws:
`java.lang.IllegalArgumentException` - if the passed number of dimensions is zero or negative.
• #### maxValue

`public static Point maxValue(int coordCount)`
Returns the "maximal" point in n-dimensional space, where n=coordCount is the argument of this method, that is the point with all coordinates are equal to Double.POSITIVE_INFINITY.
Parameters:
`coordCount` - the number of dimensions.
Returns:
the "maximal" point in n-dimensional space.
Throws:
`java.lang.IllegalArgumentException` - if the passed number of dimensions is zero or negative.
• #### valueOf

`public static Point valueOf(IPoint iPoint)`
Returns a new point with the same coordinates as the given integer point. All long coordinates of the passed integer point are converted to double coordinates of the returned point by standard Java typecast (double)longValue.
Parameters:
`iPoint` - the integer point.
Returns:
the real point with same coordinates.
Throws:
`java.lang.NullPointerException` - if the passed integer point is null.
• #### coordCount

`public int coordCount()`
Returns the number of dimensions of this point. Equivalent to `coordinates()`.length, but works faster.

The result of this method is always positive (>0).

Returns:
the number of dimensions of this point.
• #### coordinates

`public double[] coordinates()`
Returns all coordinates of this point. The element #0 of the returned array is x-coordinate, the element #1 is y-coordinate, etc. The length of the returned array is the number of dimensions of this point.

The returned array is a clone of the internal coordinates array stored in this object. The returned array is never empty (its length >0 always).

Returns:
all coordinates of this point.
• #### coordinates

`public double[] coordinates(double[] result)`
Copies all coordinates of this point into result array. The element #0 of this array will contain x-coordinate, the element #1 will contain y-coordinate, etc. The length of the passed array must be not less than the number of dimensions of this point.
Parameters:
`result` - the array where you want to store results.
Returns:
a reference to the passed result array.
Throws:
`java.lang.NullPointerException` - if result argument is null.
`java.lang.IllegalArgumentException` - if result.length<`coordCount()`.
• #### coord

`public double coord(int coordIndex)`
Returns the coordinate #coordIndex: x-coordinate for coordIndex=0, y-coordinate for coordIndex=1, etc.
Parameters:
`coordIndex` - the index of the coordinate.
Returns:
the coordinate.
Throws:
`java.lang.IndexOutOfBoundsException` - if coordIndex<0 or coordIndex>=`coordCount()`.
• #### x

`public double x()`
Returns the x-coordinate: equivalent to `coord(0)`.
Returns:
x-coordinate.
• #### y

`public double y()`
Returns y-coordinate: equivalent to `coord(1)`. The only difference: in a case of 1-dimensional point (`coordCount()`<2), this method throws IllegalStateException instead of IndexOutOfBoundsException.
Returns:
y-coordinate.
Throws:
`java.lang.IllegalStateException` - if `coordCount()`<2.
• #### z

`public double z()`
Returns z-coordinate: equivalent to `coord(2)`. The only difference: in a case of 1- or 2-dimensional point (`coordCount()`<3), this method throws IllegalStateException instead of IndexOutOfBoundsException.
Returns:
z-coordinate.
Throws:
`java.lang.IllegalStateException` - if `coordCount()`<3.
• #### isOrigin

`public boolean isOrigin()`
Returns true if this point is the origin of coordinates. In other words, returns true if all coordinates of this point are zero.
Returns:
true if this point is the origin of coordinates.
• #### distanceFromOrigin

`public double distanceFromOrigin()`
Returns the distance between this point and the origin of coordinates.

All calculations are performed in strictfp mode, so the result is absolutely identical on all platforms.

Returns:
the distance between this point and the origin of coordinates.
• #### distanceFrom

`public double distanceFrom(java.util.Collection<Point> points)`
Returns the minimal distance between this point and any point from the passed collection. If is also called the Hausdorff distance between the point and the point set. If the passed collection is empty, returns Double.POSITIVE_INFINITY.

All calculations are performed in strictfp mode, so the result is absolutely identical on all platforms.

Parameters:
`points` - some collection of points.
Returns:
the Hausdorff distance from this point to the set of points, passed via the collection.
Throws:
`java.lang.NullPointerException` - if the argument is null or if some elements of the passed collection are null.
`java.lang.IllegalArgumentException` - if the `numbers of dimensions` in this point and in some of the given points are different.

`public Point add(Point point)`
Returns the vector sum of this and given point: every coordinate #i in the result is thisInstance.`coord(i)`+point.`coord(i)`.
Parameters:
`point` - the added point.
Returns:
the vector sum of this and given point.
Throws:
`java.lang.NullPointerException` - if the argument is null.
`java.lang.IllegalArgumentException` - if the `numbers of dimensions` in this and given points are different.
• #### subtract

`public Point subtract(Point point)`
Returns the vector difference of this and given point: every coordinate #i in the result is thisInstance.`coord(i)`-point.`coord(i)`.
Parameters:
`point` - the subtracted point.
Returns:
the vector difference of this and given point.
Throws:
`java.lang.NullPointerException` - if the argument is null.
`java.lang.IllegalArgumentException` - if the `numbers of dimensions` in this and given points are different.
• #### min

`public Point min(Point point)`
Returns the coordinate-wise minimum of this and given point: every coordinate #i in the result is Math.min(thisInstance.`coord(i)`,point.`coord(i)`).
Parameters:
`point` - the compared point.
Returns:
the coordinate-wise minimum this and given point.
Throws:
`java.lang.NullPointerException` - if the argument is null.
`java.lang.IllegalArgumentException` - if the `numbers of dimensions` in this and given points are different.
• #### max

`public Point max(Point point)`
Returns the coordinate-wise maximum of this and given point: every coordinate #i in the result is Math.max(thisInstance.`coord(i)`,point.`coord(i)`).
Parameters:
`point` - the compared point.
Returns:
the coordinate-wise maximum this and given point.
Throws:
`java.lang.NullPointerException` - if the argument is null.
`java.lang.IllegalArgumentException` - if the `numbers of dimensions` in this and given points are different.

`public Point addToAllCoordinates(double increment)`
Adds the given value to all coordinates of this point and returns the resulting point: every coordinate #i in the result is thisInstance.`coord(i)`+increment. In other words, shifts this point along all axes by the given value.

Equivalent to `add`(`Point.valueOfEqualCoordinates`(n,increment)), where n=`coordCount()`.

Parameters:
`increment` - the value, which will be added to all coordinates of this point.
Returns:
this resulting point.
• #### multiply

`public Point multiply(double multiplier)`
Returns the product of this point and the given scalar multiplier: every coordinate #i in the result is thisInstance.`coord(i)`*multiplier.

Equivalent to `scale(double... multipliers)`, where all `coordCount()` arguments of that method are equal to multiplier.

Parameters:
`multiplier` - the multiplier.
Returns:
the product of this point and the given scalar multiplier.
• #### scale

`public Point scale(double... multipliers)`
Returns new point, each coordinate #i of which is thisInstance.`coord(i)`*multipliers[i]. The length of multipliers array must be equal to `coordCount()`.

Note: this method does not perform actual multiplication to multipliers, equal to 1.0, 0.0 and −1.0. If the condition multipliers[k]==1.0 is true for some k, then the coordinate #k is just copied from this point into the result. If the condition multipliers[k]==0.0 is true for some k, then the coordinate #k in the result will be 0.0 (always +0.0, regardless of the sign of this coordinate in the source point). If the condition multipliers[k]==-1.0 is true for some k, then the coordinate #k in the result will be equal to -`coord`(k).

Parameters:
`multipliers` - the multipliers for all coordinates.
Returns:
the point, each coordinate #i of which is product of the corresponding coordinate #i of this one and the corresponding multiplier multiplier[i].
Throws:
`java.lang.NullPointerException` - if the argument is null.
`java.lang.IllegalArgumentException` - if the `numbers of dimensions` is not equal to multipliers.length.
• #### scaleAndShift

```public Point scaleAndShift(double[] multipliers,
Point shift)```
Returns new point, each coordinate #i of which is shift.`coord(i)`+thisInstance.`coord(i)`*multipliers[i]. The length of multipliers array must be equal to `coordCount()`.

Note: this method does not perform actual multiplication to multipliers, equal to 1.0, 0.0 and −1.0. If the condition multipliers[k]==1.0 is true for some k, then the coordinate #k will be equal to shift.`coord`(k)+thisInstance.`coord`(k). If the condition multipliers[k]==0.0 is true for some k, then the coordinate #k in the result will be equal to shift.`coord`(k). If the condition multipliers[k]==-1.0 is true for some k, then the coordinate #k in the result will be equal to shift.`coord`(k)-thisInstance.`coord`(k).

Parameters:
`multipliers` - the multipliers for all coordinates.
`shift` - the shift along all coordinates.
Returns:
the point, each coordinate #i of which is product of the corresponding coordinate #i of this one and the corresponding multiplier multiplier[i], incremented by the corresponding coordinate shift.`coord(i)`.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`java.lang.IllegalArgumentException` - if the `numbers of dimensions` is not equal to multipliers.length.
• #### scaleAndShift

```public void scaleAndShift(double[] resultCoordinates,
double[] multipliers,
Point shift)```
More efficient version of `scaleAndShift(double[], Point)` method, which stores the coordinates of the result in the passed Java array instead of creating new instance of this class. Equivalent to the following call: `scaleAndShift`(multipliers,shift).`coordinates`(resultCoordinates), but works little faster.
Parameters:
`resultCoordinates` - Java array for storing results.
`multipliers` - the multipliers for all coordinates.
`shift` - the shift along all coordinates.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`java.lang.IllegalArgumentException` - if the `numbers of dimensions` is greater than resultCoordinates.length or is not equal to multipliers.length.
• #### shiftAlongAxis

```public Point shiftAlongAxis(int coordIndex,
double shift)```
Returns this point shifted by the passed shift along the axis #coordIndex. Equivalent to `add(p)`, where p is the point with coordinates p0, p1, ..., pk=0 for k!=coordIndex, pk=shift for k=coordIndex.
Parameters:
`coordIndex` - the index of the axis.
`shift` - the shift along this axis.
Returns:
this point shifted along this axis.
Throws:
`java.lang.IndexOutOfBoundsException` - if coordIndex<0 or coordIndex>=`coordCount()`.
• #### scalarProduct

`public double scalarProduct(Point point)`
Returns the scalar product of this and given point. The result is the sum of all products thisInstance.`coord(i)`*point.`coord(i)` for all coordinate indexes i.

All calculations are performed in strictfp mode, so the result is absolutely identical on all platforms.

Parameters:
`point` - another point.
Returns:
the scalar product of this and given point.
Throws:
`java.lang.NullPointerException` - if the argument is null.
`java.lang.IllegalArgumentException` - if the `numbers of dimensions` in this and given points are different.
• #### symmetric

`public Point symmetric()`
Returns the symmetric point relatively the origin of coordinates. Equivalent to `multiply(-1.0)`.
Returns:
the symmetric point relatively the origin of coordinates.
• #### projectionAlongAxis

`public Point projectionAlongAxis(int coordIndex)`
Returns the projection of this point along the given axis with the number of coordinates, decreased by 1. Namely, the resulting point P has `coordCount()`−1 coordinates, equal to P.`coord`(i)=thisInstance.`coord`(i'), i'=i for i<coordIndex or i'=i+1 for icoordIndex.
Parameters:
`coordIndex` - the number of coordinate, along which the projecting is performed.
Returns:
the projection of this point along the coordinates axis #coordIndex.
Throws:
`java.lang.IndexOutOfBoundsException` - if coordIndex<0 or coordIndex>=`coordCount()`.
`java.lang.IllegalStateException` - if this point is 1-dimensional (`coordCount()`==1).
• #### compareTo

`public int compareTo(Point o)`
Compares points lexicographically.

More precisely, let xi is thisInstance.`coord`(i) for 0<=i<thisInstance.`coordCount()` and xi=0 for i>=thisInstance.`coordCount()`. Then, let yi is o.`coord`(i) for 0<=i<o.`coordCount()` and yi=0 for i>=o.`coordCount()`. This method returns a negative integer if there is such index k that xk<yk and xi=yi for all i>k; this method returns a positive integer if there is such index k that xk>yk and xi=yi for all i>k. If all xi=yi, this method returns a negative integer, 0 or a positive integer if thisInstance.`coordCount()` is less than, equal to, or greater than o.`coordCount()`.

Specified by:
`compareTo` in interface `java.lang.Comparable<Point>`
Parameters:
`o` - the point to be compared.
Returns:
negative integer, zero, or a positive integer as this point is lexicographically less than, equal to, or greater than o.
Throws:
`java.lang.NullPointerException` - if the argument is null.
• #### compareTo

```public int compareTo(Point o,
int firstCoordIndex)```
Compares points lexicographically alike `compareTo(Point)` method, but with the cyclical shift of all indexes of coordinates: the coordinate #firstCoordIndex instead of x, #firstCoordIndex+1 instead of y, etc.

More precisely, let n=max(thisInstance.`coordCount()`,o.`coordCount()`), xi is thisInstance.`coord`((i+firstCoordIndex)%n), yi is o.`coord`((i+firstCoordIndex)%n). As in `compareTo(Point)` method, we suppose here that all coordinates `coord(k)` with k>=`coordCount()` are zero. This method returns a negative integer if there is such index k that xk<yk and xi=yi for all i>k; this method returns a positive integer if there is such index k that xk>yk and xi=yi for all i>k. If all xi=yi, this method returns a negative integer, 0 or a positive integer if thisInstance.`coordCount()` is less than, equal to, or greater than o.`coordCount()`.

Parameters:
`o` - the point to be compared.
`firstCoordIndex` - the index of "first" coordinate, that is compared after all other coordinates.
Returns:
negative integer, zero, or a positive integer as this point is lexicographically less than, equal to, or greater than o.
Throws:
`java.lang.NullPointerException` - if the o argument is null.
`java.lang.IllegalArgumentException` - if firstCoordIndex is negative.
• #### toString

`public java.lang.String toString()`
Returns a brief string description of this object.

The result of this method may depend on implementation and usually contains a list of all point coordinates.

Overrides:
`toString` in class `java.lang.Object`
Returns:
a brief string description of this object.
• #### hashCode

`public int hashCode()`
Returns the hash code of this point. The result depends on all `coordinates`.
Overrides:
`hashCode` in class `java.lang.Object`
Returns:
the hash code of this point.
• #### equals

`public boolean equals(java.lang.Object obj)`
Indicates whether some other point is equal to this instance, that is the number of coordinates is the same and all corresponding coordinates are equal. The corresponding coordinates are compared as in Double.equals method, i.e. they are converted to long values by Double.doubleToLongBits method and the results are compared.
Overrides:
`equals` in class `java.lang.Object`
Parameters:
`obj` - the object to be compared for equality with this instance.
Returns:
true if the specified object is a point equal to this one.
• #### isInteger

`public boolean isInteger()`
Returns true if and only if this point is really integer, that is if for any its coordinate xi=`coord`(i) the Java expression xi==(long)xi is true.
Returns:
true if all coordinates of this point are integer numbers.
• #### toIntegerPoint

`public IPoint toIntegerPoint()`
Equivalent to `IPoint.valueOf`(thisInstance).
Returns:
the integer point with same (cast) coordinates.
• #### toRoundedPoint

`public IPoint toRoundedPoint()`
Equivalent to `IPoint.roundOf`(thisInstance).
Returns:
the integer point with same (rounded) coordinates.