/*
* Copyright (c) 2008, 2019, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javafx.geometry;
import javafx.animation.Interpolatable;
import javafx.beans.NamedArg;
// PENDING_DOC_REVIEW of this whole class
A 2D geometric point that usually represents the x, y coordinates.
It can also represent a relative magnitude vector's x, y magnitudes.
Since: JavaFX 2.0
/**
* A 2D geometric point that usually represents the x, y coordinates.
* It can also represent a relative magnitude vector's x, y magnitudes.
* @since JavaFX 2.0
*/
public class Point2D implements Interpolatable<Point2D> {
Point or vector with both coordinates set to 0.
/**
* Point or vector with both coordinates set to 0.
*/
public static final Point2D ZERO = new Point2D(0.0, 0.0);
The x coordinate.
@defaultValue 0.0
/**
* The x coordinate.
*
* @defaultValue 0.0
*/
private final double x;
The x coordinate.
Returns: the x coordinate
/**
* The x coordinate.
* @return the x coordinate
*/
public final double getX() {
return x;
}
The y coordinate.
@defaultValue 0.0
/**
* The y coordinate.
*
* @defaultValue 0.0
*/
private final double y;
The y coordinate.
Returns: the y coordinate
/**
* The y coordinate.
* @return the y coordinate
*/
public final double getY() {
return y;
}
Cache the hash code to make computing hashes faster.
/**
* Cache the hash code to make computing hashes faster.
*/
private int hash = 0;
Creates a new instance of Point2D
. Params: - x – the x coordinate of the point
- y – the y coordinate of the point
/**
* Creates a new instance of {@code Point2D}.
* @param x the x coordinate of the point
* @param y the y coordinate of the point
*/
public Point2D(@NamedArg("x") double x, @NamedArg("y") double y) {
this.x = x;
this.y = y;
}
Computes the distance between this point and point (x1, y1)
. Params: - x1 – the x coordinate of other point
- y1 – the y coordinate of other point
Returns: the distance between this point and point (x1, y1)
.
/**
* Computes the distance between this point and point {@code (x1, y1)}.
*
* @param x1 the x coordinate of other point
* @param y1 the y coordinate of other point
* @return the distance between this point and point {@code (x1, y1)}.
*/
public double distance(double x1, double y1) {
double a = getX() - x1;
double b = getY() - y1;
return Math.sqrt(a * a + b * b);
}
Computes the distance between this point and the specified point
. Params: - point – the other point
Throws: - NullPointerException – if the specified
point
is null
Returns: the distance between this point and the specified point
.
/**
* Computes the distance between this point and the specified {@code point}.
*
* @param point the other point
* @return the distance between this point and the specified {@code point}.
* @throws NullPointerException if the specified {@code point} is null
*/
public double distance(Point2D point) {
return distance(point.getX(), point.getY());
}
Returns a point with the specified coordinates added to the coordinates
of this point.
Params: - x – the X coordinate addition
- y – the Y coordinate addition
Returns: the point with added coordinates Since: JavaFX 8.0
/**
* Returns a point with the specified coordinates added to the coordinates
* of this point.
* @param x the X coordinate addition
* @param y the Y coordinate addition
* @return the point with added coordinates
* @since JavaFX 8.0
*/
public Point2D add(double x, double y) {
return new Point2D(
getX() + x,
getY() + y);
}
Returns a point with the coordinates of the specified point added to the
coordinates of this point.
Params: - point – the point whose coordinates are to be added
Throws: - NullPointerException – if the specified
point
is null
Returns: the point with added coordinates Since: JavaFX 8.0
/**
* Returns a point with the coordinates of the specified point added to the
* coordinates of this point.
* @param point the point whose coordinates are to be added
* @return the point with added coordinates
* @throws NullPointerException if the specified {@code point} is null
* @since JavaFX 8.0
*/
public Point2D add(Point2D point) {
return add(point.getX(), point.getY());
}
Returns a point with the specified coordinates subtracted from
the coordinates of this point.
Params: - x – the X coordinate subtraction
- y – the Y coordinate subtraction
Returns: the point with subtracted coordinates Since: JavaFX 8.0
/**
* Returns a point with the specified coordinates subtracted from
* the coordinates of this point.
* @param x the X coordinate subtraction
* @param y the Y coordinate subtraction
* @return the point with subtracted coordinates
* @since JavaFX 8.0
*/
public Point2D subtract(double x, double y) {
return new Point2D(
getX() - x,
getY() - y);
}
Returns a point with the coordinates of this point multiplied
by the specified factor
Params: - factor – the factor multiplying the coordinates
Returns: the point with multiplied coordinates Since: JavaFX 8.0
/**
* Returns a point with the coordinates of this point multiplied
* by the specified factor
* @param factor the factor multiplying the coordinates
* @return the point with multiplied coordinates
* @since JavaFX 8.0
*/
public Point2D multiply(double factor) {
return new Point2D(getX() * factor, getY() * factor);
}
Returns a point with the coordinates of the specified point subtracted
from the coordinates of this point.
Params: - point – the point whose coordinates are to be subtracted
Throws: - NullPointerException – if the specified
point
is null
Returns: the point with subtracted coordinates Since: JavaFX 8.0
/**
* Returns a point with the coordinates of the specified point subtracted
* from the coordinates of this point.
* @param point the point whose coordinates are to be subtracted
* @return the point with subtracted coordinates
* @throws NullPointerException if the specified {@code point} is null
* @since JavaFX 8.0
*/
public Point2D subtract(Point2D point) {
return subtract(point.getX(), point.getY());
}
Normalizes the relative magnitude vector represented by this instance.
Returns a vector with the same direction and magnitude equal to 1.
If this is a zero vector, a zero vector is returned.
Returns: the normalized vector represented by a Point2D
instance Since: JavaFX 8.0
/**
* Normalizes the relative magnitude vector represented by this instance.
* Returns a vector with the same direction and magnitude equal to 1.
* If this is a zero vector, a zero vector is returned.
* @return the normalized vector represented by a {@code Point2D} instance
* @since JavaFX 8.0
*/
public Point2D normalize() {
final double mag = magnitude();
if (mag == 0.0) {
return new Point2D(0.0, 0.0);
}
return new Point2D(
getX() / mag,
getY() / mag);
}
Returns a point which lies in the middle between this point and the
specified coordinates.
Params: - x – the X coordinate of the second endpoint
- y – the Y coordinate of the second endpoint
Returns: the point in the middle Since: JavaFX 8.0
/**
* Returns a point which lies in the middle between this point and the
* specified coordinates.
* @param x the X coordinate of the second endpoint
* @param y the Y coordinate of the second endpoint
* @return the point in the middle
* @since JavaFX 8.0
*/
public Point2D midpoint(double x, double y) {
return new Point2D(
x + (getX() - x) / 2.0,
y + (getY() - y) / 2.0);
}
Returns a point which lies in the middle between this point and the
specified point.
Params: - point – the other endpoint
Throws: - NullPointerException – if the specified
point
is null
Returns: the point in the middle Since: JavaFX 8.0
/**
* Returns a point which lies in the middle between this point and the
* specified point.
* @param point the other endpoint
* @return the point in the middle
* @throws NullPointerException if the specified {@code point} is null
* @since JavaFX 8.0
*/
public Point2D midpoint(Point2D point) {
return midpoint(point.getX(), point.getY());
}
Computes the angle (in degrees) between the vector represented
by this point and the specified vector.
Params: - x – the X magnitude of the other vector
- y – the Y magnitude of the other vector
Returns: the angle between the two vectors measured in degrees Since: JavaFX 8.0
/**
* Computes the angle (in degrees) between the vector represented
* by this point and the specified vector.
* @param x the X magnitude of the other vector
* @param y the Y magnitude of the other vector
* @return the angle between the two vectors measured in degrees
* @since JavaFX 8.0
*/
public double angle(double x, double y) {
final double ax = getX();
final double ay = getY();
final double delta = (ax * x + ay * y) / Math.sqrt(
(ax * ax + ay * ay) * (x * x + y * y));
if (delta > 1.0) {
return 0.0;
}
if (delta < -1.0) {
return 180.0;
}
return Math.toDegrees(Math.acos(delta));
}
Computes the angle (in degrees) between the vector represented
by this point and the vector represented by the specified point.
Params: - point – the other vector
Throws: - NullPointerException – if the specified
point
is null
Returns: the angle between the two vectors measured in degrees, NaN
if any of the two vectors is a zero vector Since: JavaFX 8.0
/**
* Computes the angle (in degrees) between the vector represented
* by this point and the vector represented by the specified point.
* @param point the other vector
* @return the angle between the two vectors measured in degrees,
* {@code NaN} if any of the two vectors is a zero vector
* @throws NullPointerException if the specified {@code point} is null
* @since JavaFX 8.0
*/
public double angle(Point2D point) {
return angle(point.getX(), point.getY());
}
Computes the angle (in degrees) between the three points with this point
as a vertex.
Params: - p1 – one point
- p2 – other point
Throws: - NullPointerException – if
p1
or p2
is null
Returns: angle between the vectors (this, p1) and (this, p2) measured in degrees, NaN
if the three points are not different from one another Since: JavaFX 8.0
/**
* Computes the angle (in degrees) between the three points with this point
* as a vertex.
* @param p1 one point
* @param p2 other point
* @return angle between the vectors (this, p1) and (this, p2) measured
* in degrees, {@code NaN} if the three points are not different
* from one another
* @throws NullPointerException if {@code p1} or {@code p2} is null
* @since JavaFX 8.0
*/
public double angle(Point2D p1, Point2D p2) {
final double x = getX();
final double y = getY();
final double ax = p1.getX() - x;
final double ay = p1.getY() - y;
final double bx = p2.getX() - x;
final double by = p2.getY() - y;
final double delta = (ax * bx + ay * by) / Math.sqrt(
(ax * ax + ay * ay) * (bx * bx + by * by));
if (delta > 1.0) {
return 0.0;
}
if (delta < -1.0) {
return 180.0;
}
return Math.toDegrees(Math.acos(delta));
}
Computes magnitude (length) of the relative magnitude vector represented
by this instance.
Returns: magnitude of the vector Since: JavaFX 8.0
/**
* Computes magnitude (length) of the relative magnitude vector represented
* by this instance.
* @return magnitude of the vector
* @since JavaFX 8.0
*/
public double magnitude() {
final double x = getX();
final double y = getY();
return Math.sqrt(x * x + y * y);
}
Computes dot (scalar) product of the vector represented by this instance
and the specified vector.
Params: - x – the X magnitude of the other vector
- y – the Y magnitude of the other vector
Returns: the dot product of the two vectors Since: JavaFX 8.0
/**
* Computes dot (scalar) product of the vector represented by this instance
* and the specified vector.
* @param x the X magnitude of the other vector
* @param y the Y magnitude of the other vector
* @return the dot product of the two vectors
* @since JavaFX 8.0
*/
public double dotProduct(double x, double y) {
return getX() * x + getY() * y;
}
Computes dot (scalar) product of the vector represented by this instance
and the specified vector.
Params: - vector – the other vector
Throws: - NullPointerException – if the specified
vector
is null
Returns: the dot product of the two vectors Since: JavaFX 8.0
/**
* Computes dot (scalar) product of the vector represented by this instance
* and the specified vector.
* @param vector the other vector
* @return the dot product of the two vectors
* @throws NullPointerException if the specified {@code vector} is null
* @since JavaFX 8.0
*/
public double dotProduct(Point2D vector) {
return dotProduct(vector.getX(), vector.getY());
}
Computes cross product of the vector represented by this instance
and the specified vector.
Params: - x – the X magnitude of the other vector
- y – the Y magnitude of the other vector
Returns: the cross product of the two vectors Since: JavaFX 8.0
/**
* Computes cross product of the vector represented by this instance
* and the specified vector.
* @param x the X magnitude of the other vector
* @param y the Y magnitude of the other vector
* @return the cross product of the two vectors
* @since JavaFX 8.0
*/
public Point3D crossProduct(double x, double y) {
final double ax = getX();
final double ay = getY();
return new Point3D(
0, 0, ax * y - ay * x);
}
Computes cross product of the vector represented by this instance
and the specified vector.
Params: - vector – the other vector
Throws: - NullPointerException – if the specified
vector
is null
Returns: the cross product of the two vectors Since: JavaFX 8.0
/**
* Computes cross product of the vector represented by this instance
* and the specified vector.
* @param vector the other vector
* @return the cross product of the two vectors
* @throws NullPointerException if the specified {@code vector} is null
* @since JavaFX 8.0
*/
public Point3D crossProduct(Point2D vector) {
return crossProduct(vector.getX(), vector.getY());
}
{@inheritDoc}
Since: 13
/**
* {@inheritDoc}
*
* @since 13
*/
@Override
public Point2D interpolate(Point2D endValue, double t) {
if (t <= 0.0) return this;
if (t >= 1.0) return endValue;
return new Point2D(
getX() + (endValue.getX() - getX()) * t,
getY() + (endValue.getY() - getY()) * t
);
}
Indicates whether some other object is "equal to" this one.
Params: - obj – the reference object with which to compare
Returns: true if this point is the same as the obj argument; false otherwise
/**
* Indicates whether some other object is "equal to" this one.
*
* @param obj the reference object with which to compare
* @return true if this point is the same as the obj argument; false otherwise
*/
@Override public boolean equals(Object obj) {
if (obj == this) return true;
if (obj instanceof Point2D) {
Point2D other = (Point2D) obj;
return getX() == other.getX() && getY() == other.getY();
} else return false;
}
Returns a hash code value for the point.
Returns: a hash code value for the point.
/**
* Returns a hash code value for the point.
* @return a hash code value for the point.
*/
@Override public int hashCode() {
if (hash == 0) {
long bits = 7L;
bits = 31L * bits + Double.doubleToLongBits(getX());
bits = 31L * bits + Double.doubleToLongBits(getY());
hash = (int) (bits ^ (bits >> 32));
}
return hash;
}
Returns a string representation of this Point2D
. This method is intended to be used only for informational purposes. The content and format of the returned string might vary between implementations. The returned string might be empty but cannot be null
. /**
* Returns a string representation of this {@code Point2D}.
* This method is intended to be used only for informational purposes.
* The content and format of the returned string might vary between
* implementations.
* The returned string might be empty but cannot be {@code null}.
*/
@Override public String toString() {
return "Point2D [x = " + getX() + ", y = " + getY() + "]";
}
}