Michael Thomas Flanagan's Java Scientific LibraryPoint Class:     Point in n-Dimensional Space

Last update: 5 December 2011                                                                                                                              Main Page of Michael Thomas Flanagan's Java Scientific Library

This class contains the constructor and methods for the manipulations of a point in n-dimensional space. For dimensions n = 2 and n = 3, Point represents a point in 2-dimensional and 3-dimensional Cartesian space respectively. Care should be taken with values of n greater than 3 as several of the method using Points are only meaningful in 2 or 3-dimensional Cartesian space.

This class is required by the VectorMaths and PolylineSimplification classes.

import directive: import flanagan.math.Point;

### SUMMARY OF CONSTRUCTOR AND METHODS

 Constructors public Point(double xCoordinate, double yCoordinate, double zCoordinate) public Point(double xCoordinate, double yCoordinate) public Point(double xCoordinate) public Point(double[] coordinates) public Point(float[] coordinates) public Point(long[] coordinates) public Point(int[] coordinates) public Point(short[] coordinates) public Point(BigDecimal[] coordinates) public Point(BigInteger[] coordinates) public Point() Reset the coordinates public void setPoint(double xCoordinate, double yCoordinate, double zCoordinate) public void setPoint(double xCoordinate, double yCoordinate) public void setPoint(double xCoordinate) public void setPoint(double[] coordinates) public void setPoint(float[] coordinates) public void setPoint(long[] coordinates) public void setPoint(int[] coordinates) public void setPoint(short[] coordinates) public void setPoint(BigDecimal[] coordinates) public void setPoint(BigInteger[] coordinates) Return the coordinates public double[] getCoordinates() public int getPointDimensions() Point array public static Point[] oneDarray(int n) public static Point[] oneDarray(double[] xCoordinates, double[] yCoordinates, double[] zCoordinates) public static Point[] oneDarray(double[] xCoordinates, double[] yCoordinates) public static Point[] oneDarray(double[] xCoordinates) public static Point[] oneDarray(double[][] coordinates) public static Point[] oneDarray(float[][] coordinates) public static Point[] oneDarray(long[][] coordinates) public static Point[] oneDarray(int[][] coordinates) public static Point[] oneDarray(short[][] coordinates) public static Point[] oneDarray(BigDecimal[][] coordinates) public static Point[] oneDarray(BigInteger[][] coordinates) public static double[][] getArrayCoordinates(Point[] array) public static int[] getArrayDimensions(Point[] array) Distance between two points public double distance(Point point2) public static double distance(Point point1, Point point2) public double distanceSquared(Point point2) public static double distanceSquared(Point point1, Point point2) Centre of a constellation of points public static Point centre(Point[] points) Equality test public boolean isEqual(Point point2) public static boolean isEqual(Point point1, Point point2) Deep copies public Point copy() public static Point copy(Point point) public static Point[] copy(Point[] array) Change dimensions public void toThreeD() public void toTwoD() Convert to VectorMaths public VectorMaths toVectorMaths()

CONSTRUCTORS
public Point(double xCoordinate, double yCoordinate, double zCoordinate)
public Point(double xCoordinate, double yCoordinate)
public Point(double xCoordinate)
public Point(double[] coordinates)
public Point(float[] coordinates)
public Point(long[] coordinates)
public Point(int[] coordinates)
public Point(short[] coordinates)
public Point(BigDecimal[] coordinates)
public Point(BigInteger[] coordinates)
public Point()

Constructor with a point entered as three cartesian coordinates
public Point(double xCoordinate, double yCoordinate, double zCoordinate)
Usage:                      Point pp = new Point(xcoord, ycoord, zcoord);
Creates an instance of Point representing a point with three Cartesian coordinates, xcoord, ycoord and zcoord.

Constructor with a point entered as two cartesian coordinates
public Point(double xCoordinate, double yCoordinate)
Usage:                      Point pp = new Point(xcoord, ycoord);
Creates an instance of Point representing a point with two Cartesian coordinates, xcoord and ycoord.

Constructor with a point entered as a single cartesian coordinate
public Point(double xCoordinate)
Usage:                      Point pp = new Point(xcoord);
Creates an instance of Point representing a point with a single Cartesian coordinates, xcoord.

Constructor with a point entered as an array of coordinates
Usage:                      Point pp = new Point(coordinates);
Creates an instance of Point representing a point with n Cartesian coordinates, coordinates, where n is the length of the array of coordinates, coordinates. Care should be exercised if n is greater than 3 as several of the methods and classes that use Point are only valid for three dimensional Cartesian space. The array, cordinates, may be an array of data types double, float, long, int, short, BigDecimal or BigInteger. Point converts all entered data types to double.

Constructor for a 3D point at the Cartesian origin
public Point()
Usage:                      Point pp = new Point();
Creates an instance of Point representing a point with three cartesian coordinates all set to zero.

### METHODS

RESET THE COORDINATES
public void setPoint(double xCoordinate, double yCoordinate, double zCoordinate)
public void setPoint(double xCoordinate, double yCoordinate)
public void setPoint(double xCoordinate)
public void setPoint(double[] coordinates)
public void setPoint(float[] coordinates)
public void setPoint(long[] coordinates)
public void setPoint(int[] coordinates)
public void setPoint(short[] coordinates)
public void setPoint(BigDecimal[] coordinates)
public void setPoint(BigInteger[] coordinates)

Reset to a point with three cartesian coordinates
public void setPoint(double xCoordinate, double yCoordinate, double zCoordinate)
Usage:                      pp.setPoint(xcoord, ycoord, zcoord);
Resets the coordinates of pp to those of a point with three Cartesian coordinates, xcoord, ycoord and zcoord.

Reset to a point with two cartesian coordinates
public void setPoint(double xCoordinate, double yCoordinate)
Usage:                      pp.setPoint(xcoord, ycoord);
Resets the coordinates of pp to those of a point with two Cartesian coordinates, xcoord and ycoord.

Reset to a point with a single cartesian coordinate
public void setPoint(double xCoordinate)
Usage:                      pp.setPoint(xcoord);
Resets the coordinates of pp to those of a point with a single Cartesian coordinates, xcoord.

Reset to a point with an array of coordinates
Usage:                      pp.setPoint(coordinates);
Resets the coordinates of pp to those of a point with n Cartesian coordinates, coordinates, where n is the length of the array of coordinates, coordinates. Care should be exercised if n is greater than 3 as several of the methods and classes that use Point are only valid for two or three dimensional Cartesian space. The array, cordinates, may be an array of data types double, float, long, int, short, BigDecimal or BigInteger. Point converts all entered data types to double.

RETURN THE COORDINATES
public double[] getCoordinates()
public int getPointDimensions()

Return coordinate values
public double[] getCoordinates()
Usage:                      coordinates = pls.getCoordinates();
Returns the point coordinates as an array of doubles whose length is the dimensions of the point.

Return the point dimensions
public int getPointDimensions()
Usage:                      nDim = pls.getPointDimensions();
Returns the value of the point dimensions.

ARRAY OF Point
public static Point[] oneDarray(int n)
public static Point[] oneDarray(double[] xCoordinates, double[] yCoordinates, double[] zCoordinates)
public static Point[] oneDarray(double[] xCoordinates, double[] yCoordinates)
public static Point[] oneDarray(double[] xCoordinates)
public static Point[] oneDarray(double[][] coordinates)
public static Point[] oneDarray(float[][] coordinates)
public static Point[] oneDarray(long[][] coordinates)
public static Point[] oneDarray(int[][] coordinates)
public static Point[] oneDarray(short[][] coordinates)
public static Point[] oneDarray(BigDecimal[][] coordinates)
public static Point[] oneDarray(BigInteger[][] coordinates)
public static double[][] getArrayCoordinates(Point[] array)
public static int[] getArrayDimensions(Point[] array)

Create a one dimensional array of Point each initialised to a 3D zero point.
public static Point[] oneDarray(int n)
Usage:                      array = Point.oneDarray(n);
This static method creates an one dimensional array of Point of length, n. Each element of the array is initialised to a 3D point with all 3 coordinate values initialised to zero.

Create a one dimensional array of 3D Points each initialised to supplied coordinate values.
public static Point[] oneDarray(double[] xCoordinates, double[] yCoordinates, double[] zCoordinates)
Usage:                      array = Point.oneDarray(xCoordinates, yCoordinates, zCoordinates);
This static method creates an one dimensional array of 3D Points. Each element of the array is initialised to a 3D point with the x-coordinate value taken from the array xCoordinates, the y-coordinate value taken from the array yCoordinates and the z-coordinate value taken from the array zCoordinates.

Create a one dimensional array of 2D Points each initialised to supplied coordinate values.
public static Point[] oneDarray(double[] xCoordinates, double[] yCoordinates)
Usage:                      array = Point.oneDarray(xCoordinates, yCoordinates);
This static method creates an one dimensional array of 2D Points. Each element of the array is initialised to a 2D point with the x-coordinate value taken from the array xCoordinates and the y-coordinate value taken from the array yCoordinates.

Create a one dimensional array of 1D Points each initialised to supplied coordinate values.
public static Point[] oneDarray(double[] xCoordinates)
Usage:                      array = Point.oneDarray(xCoordinates);
This static method creates an one dimensional array of 1D Points. Each element of the array is initialised to a 1D point with the x-coordinate value taken from the array xCoordinates.

Create a one dimensional array of n-dimensional Points each initialised to supplied coordinate values.
Usage:                      array = Point.oneDarray(coordinates);
This static method creates an one dimensional array of n-dimensional Points. Each element of the array is initialised to a n-dimensional point with the coordinate values taken from the array coordinates, supplied as a two dimensional array, cordinates[m][n], where m is the dimensions of each point and n is the length of the array. Care should be exercised if m is greater than 3 as several of the methods and classes that use Point are only valid for two or three dimensional Cartesian space. The array, cordinates, may be an array of data types double, float, long, int, short, BigDecimal or BigInteger. Point converts all entered data types to double.

Return the coordinate values of a one dimensional array of Point
public static Object getArrayCoordinates(Point[] array)
Usage:                      coordinates = Point.getArrayCoordinates(array);
This static method returns the coordinates of all Points in an one dimensional array of Point, array, as a two dimensional array of doubles, double[m][n], where n is the number of Points in the array and m is the number of dimensions of the Points.

Return the dimensions of a one dimensional array of Point
public static int[] getArrayDimensions(Point[] array)
Usage:                      dimensions = Point.getArrayDimensions(array);
This static method returns the dimensions of an one dimensional array of Point, array, as an array of int of length 2, dimensions, in the above usage. The first element, dimensions[0], holds the length of the array of Points, array. The second element, dimensions[1], contains the dimensions of the Points.

DISTANCE BETWEEN TWO POINTS
public double distance(Point point2)
public static double distance(Point point1, Point point2)
public double distanceSquared(Point point2)
public static double distanceSquared(Point point1, Point point2)

Return the distance between two points
public double distance(Point point2)
public static double distance(Point point1, Point point2)

Usage:                      distance = pp.distance(point2);
distance = Point.distance(point1, point2);

The instance method returns the distance between the two points represented by the Points pp and point2. The static method returns the distance between the two points represented by the Points point1 and point2. These methods only return a meaningful distance for 1-, 2- or 3-dimensional points.

Return the square of the distance between two points
public double distanceSquared(Point point2)
public static double distanceSquared(Point point1, Point point2)

Usage:                      distance2 = pp.distanceSquared(point2);
distance2 = Point.distanceSquared(point1, point2);

The instance method returns the the square of the distance between the two points represented by the Points pp and point2. The static method returns the square of the distance between the two points represented by the Points point1 and point2. These methods only return a meaningful distance for 1-, 2- or 3-dimensional points.

CENTRE OF A CONSTELLATION OF POINTS
public static Point centre(Point[] parray)

Usage:                      centrePoint = pp.centre(parray);
This method returns a Point representing the point whose coordinates are the unweighted mean of the coordinates of the points represented by the 1D array of Points, parray.

EQUALITY TESTS
public boolean isEqual(Point point2)
public static boolean isEqual(Point point1, Point point2)

Usage:                      test = pp.isEqual(point2);
test = Point.isEqual(point1, point2);

The instance method returns true if the points represented by pp and point2 are identical and returns false if they are not identical.
The static method returns true if the points represented by point1 and point2 are identical and returns false if they are not identical.

DEEP COPIES
public Point copy()
public static Point copy(Point point)
public static Point[] copy(Point[] array)

Make a deep copy of a single Point
public Point copy()
public static Point copy(Point point)
Usage:                      copy = pp.copy();
copy = Point.copy(point1);

The instance method returns a deep copy of pp. The static method returns a deep copy of point1.

Make a deep copy of a 1D array of Points
public static Point[] copy(Point[] array)
Usage:                      arrayCopy = Point.copy(array);
This static method returns a deep copy of the 1D array of Points, array.

CHANGE DIMENSIONS
public void toThreeD()
public void toTwoD()

Convert a 1D or 2D Point to a 3D point
public void toThreeD()
Usage:                      pp.toThreeD();
If pp is either a one or two dimensional Point this method converts it to a three dimensional Point by adding zeros to pp’s internal coordinate array.

Convert a n dimensional Point to a 2D point
public void toTwoD()
Usage:                      pp.toTwoD();
If the dimensions of pp are greater than two this method converts pp to a two dimensional Point. This action will only be performed if the extra dimensions above two are all characterised by zero coordinate values.

CONVERT Point TO VectorMaths
public VectorMaths toVectorMaths()
Usage:                      vector = pp.toVectorMaths();
This method returns an instance of VectorMaths representing a vector from the Cartesian origin to a point represented by the Point, pp. This method will only convert a Point of three or less dimensions.

### OTHER CLASSES USED BY THIS CLASS

This class uses the following classes in this library:
• None