org.jeometry.geom3D.point.Point3D Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jeometry-api Show documentation
Show all versions of jeometry-api Show documentation
Jeometry, a Mathematic and Geometry library for Java
package org.jeometry.geom3D.point;
import org.jeometry.Jeometry;
import org.jeometry.geom3D.SpatialLocalization3D;
import org.jeometry.math.Vector;
/**
* This interface describes a point expressed within a three-dimensional Euclidean space.
* The coordinates of the point (x, y and z) are expressed within a Cartesian coordinate system and are stored as double values.
* @author Julien Seinturier - COMEX S.A. - [email protected] - https://github.com/jorigin/jeometry
* @version {@value Jeometry#version} build {@value Jeometry#BUILD}
* @since 1.0.0
*/
public interface Point3D extends Coord3D, SpatialLocalization3D {
/**
* Return a normalized point that is orthogonal to this one.
* @return a normalized point that is orthogonal to this one.
* @see #orthogonal(Vector)
*/
@Override
public Point3D orthogonal();
/**
* Set the given result point with the normalized point that is orthogonal to this one.
* @param result the point where the result has to be stored.
* @return the given result point with the normalized point that is orthogonal to this one.
* @see #orthogonal()
* @throws IllegalArgumentException if the result vector length is not equals to 3.
*/
@Override
public Point3D orthogonal(Vector result);
/**
* Set the coordinates values of this point according to the given ones.
* @param x the X coordinate
* @param y the Y coordinate
* @param z the Z coordinate
*/
public void setValues(double x, double y, double z);
/**
* Set this 3D point coordinates as a copy of those from the given 3D point.
* @param point the 3D point to copy
*/
public void setValues(Point3D point);
/**
* Compute the cross product between this point and the given one.
* The cross product, denoted x is such that for two point
* a = (xa, ya, za)
* and
* b = (xb, yb, zb)
* we have:
* $$a\ \times\ b\ =\ ( y_a\ \times\ z_b\ -\ z_a\ \times\ y_b,\ -x_a\ \times\ z_b\ +\ z_a\ \times\ x_b,\ -x_a\ \times\ y_b\ -\ y_a\ \times\ x_b)$$
* The creation of the cross product result as an instance of {@link Point3D} is delegated to implementations.
* @param point the second operand of the cross product.
* @return the cross product between this point and the given one.
* @see #cross(Point3D, Point3D)
*/
public Point3D cross(Point3D point);
/**
* Compute the cross product between this point and the given one.
* The cross product, denoted x is such that for two point
* a = (xa, ya, za)
* and
* b = (xb, yb, zb)
* we have:
* $$a\ \times\ b\ =\ ( y_a\ \times\ z_b\ -\ z_a\ \times\ y_b,\ -x_a\ \times\ z_b\ +\ z_a\ \times\ x_b,\ -x_a\ \times\ y_b\ -\ y_a\ \times\ x_b)$$
* The result the cross product is stored within the given result {@link Point3D}. The return value of this method is a reference on the result parameter.
* If the parameter is null, a new point is created and returned as the cross product result. The instantiation of the result is delegated to implementations.
* @param point the second operand of the cross product.
* @param result the result of the cross product.
* @return the cross product between this point and the given one.
* @see #cross(Point3D, Point3D)
* @see #dot(Point3D)
*/
public Point3D cross(Point3D point, Point3D result);
/**
* Compute the dot product, or scalar product, of the vector represented by this point and the given one.
* The dot product, denoted •, is such that for two points
* a = (xa, ya, za)
* and
* b = (xb, yb, zb)
* we have:
* $$a\ \boldsymbol{\cdot}\ b\ =\ x_a\ \times\ x_b\ +\ y_a\ \times\ y_b + z_a\ \times\ z_b $$
* We can denote that the dot product can also be expressed by:
* $$a\ \boldsymbol{\cdot}\ b\ =\ ||a||\ \times\ ||b||\ \times\ cos(\varphi)$$
* where ||a|| is the {@link #norm() Euclidean norm} of a and φ is the angle between the vectors a and b.
* @param point the second operand of the dot product.
* @return the dot product between this point and the given one.
* @see #cross(Point3D)
* @see #norm()
*/
public double dot(Point3D point);
/**
* Compute the sum of the vector represented by this point and the vector represented by the given one and return it as a new point.
* Let a and b be two vector, their sum, denoted a + b, is a vector such that:
* $$ a + b\ =\ (x_a + x_b,\ y_a + y_b,\ z_a + z_b)$$
* If this point has to be modified, the {@link #plusAffect(Point3D)} method can be used.
* @param point the point to sum with the current point.
* @return the sum of the vector represented by this point and the vector represented by the given one.
* @see #plus(Point3D, Point3D)
* @see #plus(double, Point3D)
* @see #plus(double)
*/
public Point3D plus(Point3D point);
/**
* Compute the sum of the vector represented by this point and the vector represented by the given one and store the values within result.
* Let a and b be two vector, their sum, denoted a + b, is a vector such that:
* $$ a + b\ =\ (x_a + x_b,\ y_a + y_b,\ z_a + z_b)$$
* @param point the point to sum with the current point.
* @param result the point that represents the resulting vector.
* @return a reference on the result object.
* @see #plus(Point3D)
* @see #plus(double, Point3D)
* @see #plus(double)
*/
public Point3D plus(Point3D point, Point3D result);
/**
* Compute the sum of the vector represented by this point and the scalar given in parameter and return the result as a new point.
* Let a be a vector and let λ be a scalar, the sum, denoted a + λ, is a vector such that:
* $$ a + b\ =\ (x_a + x_b,\ y_a + y_b,\ z_a + z_b)$$
* If this point has to be modified, the {@link #plusAffect(double)} method can be used.
* @param scalar the scalar to sum.
* @return the sum of the vector represented by this point and the given scalar.
* @see #plus(Point3D)
* @see #plus(Point3D, Point3D)
* @see #plus(double, Point3D)
*/
public Point3D plus(double scalar);
/**
* Compute the sum of the vector represented by this point and the scalar given in parameter one and then store the values within result.
* Let a be a vector and let λ be a scalar, the sum, denoted a + λ, is a vector such that:
* $$ a + b\ =\ (x_a + x_b,\ y_a + y_b,\ z_a + z_b)$$
* @param scalar the scalar to sum.
* @param result the point that represents the resulting vector.
* @return a reference on the result object.
* @see #plus(Point3D)
* @see #plus(Point3D, Point3D)
* @see #plus(double)
*/
public Point3D plus(double scalar, Point3D result);
/**
* Compute the difference between the vector represented by this point and the vector represented by the given one and return it as a new point.
* Let a and b be two vector, their difference, denoted a - b, is a vector such that:
* $$ a - b\ =\ (x_a - x_b,\ y_a - y_b,\ z_a - z_b)$$
* If this point has to be modified, the {@link #minusAffect(Point3D)} method can be used.
* @param point the point to differentiate with the current point.
* @return the difference between the vector represented by this point and the vector represented by the given one.
* @see #minus(Point3D, Point3D)
* @see #minus(double, Point3D)
* @see #minus(double)
*/
public Point3D minus(Point3D point);
/**
* Compute the difference between the vector represented by this point and the vector represented by the given one and then store the values within result.
* Let a and b be two vector, their difference, denoted a - b, is a vector such that:
* $$ a - b\ =\ (x_a - x_b,\ y_a - y_b,\ z_a - z_b)$$
* @param point the point to differentiate with the current point.
* @param result the point that represents the resulting vector.
* @return a reference on the result object.
* @see #minus(Point3D)
* @see #minus(double, Point3D)
* @see #minus(double)
*/
public Point3D minus(Point3D point, Point3D result);
/**
* Compute the difference between the vector represented by this point and the scalar given in parameter and return the result as a new point.
* Let a be a vector and let λ be a scalar, the difference, denoted a - λ, is a vector such that:
* $$ a - b\ =\ (x_a - x_b,\ y_a - y_b,\ z_a - z_b)$$
* If this point has to be modified, the {@link #minusAffect(double)} method can be used.
* @param scalar the scalar to differentiate.
* @return the difference between the vector represented by this point and the given scalar.
* @see #minus(Point3D)
* @see #minus(Point3D, Point3D)
* @see #minus(double, Point3D)
*/
public Point3D minus(double scalar);
/**
* Compute the difference between the vector represented by this point and the scalar given in parameter one and then store the values within result.
* Let a be a vector and let λ be a scalar, the difference, denoted a - λ, is a vector such that:
* $$ a - b\ =\ (x_a - x_b,\ y_a - y_b,\ z_a - z_b)$$
* @param scalar the scalar to differentiate.
* @param result the point that represents the resulting vector.
* @return a reference on the result object.
* @see #minus(Point3D)
* @see #minus(Point3D, Point3D)
* @see #minus(double)
*/
public Point3D minus(double scalar, Point3D result);
/**
* Affect this point with the result of the sum of this point and the one given in parameter.
* Let a and b be two vector, their sum, denoted a + b, is a vector such that:
* $$ a + b\ =\ (x_a + x_b,\ y_a + y_b,\ z_a + z_b)$$
* This point is modified by this operation. If its is not needed to modify this point, the method {@link #plus(Point3D)} can be used.
* @param point the point to sum with the this one.
* @return a reference on this point (can be useful for chaining operations).
* @see #plusAffect(double)
*/
public Point3D plusAffect(Point3D point);
/**
* Affect this point with the result of the sum of this point and the scalar given in parameter.
* Let a be a vector and let λ be a scalar, the sum, denoted a + λ, is a vector such that:
* $$ a + b\ =\ (x_a + x_b,\ y_a + y_b,\ z_a + z_b)$$
* This point is modified by this operation. If its is not needed to modify this point, the method {@link #plus(double)} can be used.
* @param scalar the scalar to sum with this point.
* @return a reference on this point (can be useful for chaining operations).
* @see #plusAffect(Point3D)
*/
public Point3D plusAffect(double scalar);
/**
* Affect this point with the result of the difference of this point and the one given in parameter.
* Let a and b be two vector, their difference, denoted a - b, is a vector such that:
* $$ a - b\ =\ (x_a - x_b,\ y_a - y_b,\ z_a - z_b)$$
* This point is modified by this operation. If its is not needed to modify this point, the method {@link #minus(Point3D)} can be used.
* @param point the point to differentiate with the this one.
* @return a reference on this point (can be useful for chaining operations).
* @see #minusAffect(double)
*/
public Point3D minusAffect(Point3D point);
/**
* Affect this point with the result of the difference of this point and the scalar given in parameter.
* Let a be a vector and let λ be a scalar, the sum, denoted a - λ, is a vector such that:
* $$ a - b\ =\ (x_a - x_b,\ y_a - y_b,\ z_a - z_b)$$
* This point is modified by this operation. If its is not needed to modify this point, the method {@link #plus(double)} can be used.
* @param scalar the scalar to differentiate with this point.
* @return a reference on this point (can be useful for chaining operations).
* @see #minusAffect(Point3D)
*/
public Point3D minusAffect(double scalar);
/**
* Compute the product of the vector represented by this point and the scalar given in parameter and return the result as a new point.
* Let a be a vector and let λ be a scalar, the product, denoted a × λ, is a vector such that:
* $$ a \times \lambda\ =\ (x \times \lambda,\ y \times \lambda,\ z \times \lambda)$$
* If this point has to be modified, the {@link #multiplyAffect(double)} method can be used.
* @param scalar the scalar to multiply.
* @return the product of the vector represented by this point and the scalar given in parameter.
* @see #multiply(double, Point3D)
*/
public Point3D multiply(double scalar);
/**
* Compute the product of the vector represented by this point and the scalar given in parameter and store it as the given result.
* Let a be a vector and let λ be a scalar, the product, denoted a × λ, is a vector such that:
* $$ a \times \lambda\ =\ (x \times \lambda,\ y \times \lambda,\ z \times \lambda)$$
* @param scalar the scalar to multiply.
* @param result the point that represents the resulting vector.
* @return a reference on the given result (can be useful for chaining operations).
* @see #multiply(double)
*/
public Point3D multiply(double scalar, Point3D result);
/**
* Affect this point with the product of the vector represented by this point and the scalar given in parameter.
* Let a be a vector and let λ be a scalar, the product, denoted a × λ, is a vector such that:
* $$ a \times \lambda\ =\ (x \times \lambda,\ y \times \lambda,\ z \times \lambda)$$
* This point is modified by this operation. If its is not needed to modify this point, the method {@link #multiply(double)} can be used.
* @param scalar the scalar to multiply.
* @return a reference on this point (can be useful for chaining operations).
*/
public Point3D multiplyAffect(double scalar);
/**
* Compute the division of the vector represented by this point and the scalar given in parameter and return the result as a new point.
* Let a be a vector and let λ be a scalar, the division, denoted a / λ, is a vector such that:
* $$ \frac{a}{\lambda}\ =\ (\frac{x}{\lambda},\ \frac{y}{\lambda},\ \frac{z}{\lambda})$$
* If this point has to be modified, the {@link #divideAffect(double)} method can be used.
* @param scalar the scalar to divide.
* @return the division of the vector represented by this point and the scalar given in parameter.
* @see #divide(double, Point3D)
*/
public Point3D divide(double scalar);
/**
* Compute the division of the vector represented by this point and the scalar given in parameter and store it as the given result.
* Let a be a vector and let λ be a scalar, the division, denoted a / λ, is a vector such that:
* $$ \frac{a}{\lambda}\ =\ (\frac{x}{\lambda},\ \frac{y}{\lambda},\ \frac{z}{\lambda})$$
* @param scalar the scalar to divide.
* @param result the point that represents the resulting vector.
* @return a reference on the given result (can be useful for chaining operations).
* @see #divide(double)
*/
public Point3D divide(double scalar, Point3D result);
/**
* Affect this point with the division of the vector represented by this point and the scalar given in parameter.
* Let a be a vector and let λ be a scalar, the division, denoted a / λ, is a vector such that:
* $$ \frac{a}{\lambda}\ =\ (\frac{x}{\lambda},\ \frac{y}{\lambda},\ \frac{z}{\lambda})$$
* This point is modified by this operation. If its is not needed to modify this point, the method {@link #divide(double)} can be used.
* @param scalar the scalar to divide.
* @return a reference on this point (can be useful for chaining operations).
*/
public Point3D divideAffect(double scalar);
}