org.jeometry.geom3D.primitive.Plane 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
Jeometry, a Mathematic and Geometry library for Java
There is a newer version: 1.0.5
package org.jeometry.geom3D.primitive;

import org.jeometry.Jeometry;
import org.jeometry.geom3D.SpatialLocalization3D;
import org.jeometry.geom3D.point.Point3D;

/**
 * An infinite plane that represents a two-dimensional doubly ruled surface spanned by two linearly independent vectors.


 * A plane can be defined by a normal vector, denoted n, and an origin point, denoted p₀.  
 * Let n = (a, b, c) a vector and let p₀ = (x₀, y₀, z₀) a point.
 * A point p = (x, y, z) lies on the plane if and only if:

 * n · (p - p₀) = 0

 * The equation of a place can be developped into:


 * ax + by + cz + d = 0

 * where d = -ax₀ - by₀ - cz₀.


 * source: http://mathworld.wolfram.com/Plane.html
 * @param  The type of underlying 3D points
 * @author Julien Seinturier - COMEX S.A. - [email protected] - https://github.com/jorigin/jeometry
 * @version {@value Jeometry#version}
 * @since 1.0.0
 */
public interface Plane {

	/**
	 * Get the normal vector of the plane.
	 * @return the normal vector of the plane.
	 * @see #setPlaneNormal(Point3D)
	 * @see #setPlaneParameters(Point3D, Point3D)
	 */
	public T getPlaneNormal();
	
	/**
	 * Set the normal vector of the plane.
	 * @param normal the normal vector of the plane.
	 * @see #getPlaneNormal()
	 */
	public void setPlaneNormal(T normal);
	
	/**
	 * Get the plane origin.
	 * @return the plane origin
	 * @see #setPlaneOrigin(Point3D)
	 * @see #setPlaneParameters(Point3D, Point3D)
	 */
	public T getPlaneOrigin();
	
	/**
	 * Set the plane origin.
	 * @param origin the plane origin
	 * @see #getPlaneOrigin()
	 */
	public void setPlaneOrigin(T origin);
	
	/**
	 * Get the plane parameters (normal and origin) by copying it within the given ones.
	 * @param origin the point that will hold the copy of the plane origin.
	 * @param normal the point that will hold the copy of the plane normal.
	 * @see #setPlaneParameters(Point3D, Point3D)
	 */
	public void getPlaneParameters(T origin, T normal);
	
	/**
	 * Set the plane origin and normal.
	 * @param origin the plane origin
	 * @param normal the plane normal
	 */
	public void setPlaneParameters(T origin, T normal);
	
	/**
	 * Get the a coefficient within the plane equation ax + by + cz + d = 0.
	 * @return the a coefficient
	 * @see #getCoefB()
	 * @see #getCoefC()
	 * @see #getCoefD()
	 */
	public double getCoefA();
	
	/**
	 * Get the b coefficient within the plane equation ax + by + cz + d = 0.
	 * @return the b coefficient
	 * @see #getCoefA()
	 * @see #getCoefC()
	 * @see #getCoefD()
	 */
	public double getCoefB();
	
	/**
	 * Get the c coefficient within the plane equation ax + by + cz + d = 0.
	 * @return the c coefficient
	 * @see #getCoefA()
	 * @see #getCoefB()
	 * @see #getCoefD()
	 */
	public double getCoefC();
	
	/**
	 * Get the d coefficient within the plane equation ax + by + cz + d = 0.
	 * @return the d coefficient
	 * @see #getCoefA()
	 * @see #getCoefB()
	 * @see #getCoefC()
	 */
	public double getCoefD();
	
    /**
     * Compute the distance between this plane and the given {@link SpatialLocalization3D spatial localization}. 
     * The result is the minimal distance between the plane and the localization.
     * @param spatial the spatial localization.
     * @return the distance between this plane and the given {@link SpatialLocalization3D spatial localization} or Double.Nan if the given spatial is null or if this localization is not known.
     */
    public double distance(SpatialLocalization3D spatial);
}