Open3D (C++ API)
0.18.0+85981ff

Line3D is a class which derives from Eigen::ParametrizedLine<double, 3> in order to capture the semantic differences between a "line", "ray", and "line segment" for operations in which the difference is important, such as intersection and distance tests. The underlying Eigen object can always be retrieved with the .Line() method. More...
#include <Line3D.h>
Public Types  
enum class  LineType { Line = 0 , Ray = 1 , Segment = 2 } 
Specifies different semantic interpretations of 3d lines. More...  
Public Member Functions  
Line3D (const Eigen::Vector3d &origin, const Eigen::Vector3d &direction)  
Default user constructor. More...  
virtual  ~Line3D ()=default 
LineType  GetLineType () const 
Gets the semantic type of the line. More...  
const Eigen::Vector3d &  Origin () const 
Gets the line's origin point. More...  
const Eigen::Vector3d &  Direction () const 
Gets the line's direction vector. More...  
virtual double  Length () const 
Gets the length of the line, which for lines and rays will return positive infinity, but for segments will return a finite positive value. More...  
virtual void  Transform (const Eigen::Transform< double, 3, Eigen::Affine > &t) 
Transform the Line3D by the given matrix. More...  
const Eigen::ParametrizedLine< double, 3 > &  Line () const 
Returns a const reference to the underlying Eigen::ParametrizedLine object. More...  
virtual utility::optional< double >  IntersectionParameter (const Eigen::Hyperplane< double, 3 > &plane) const 
Calculates the intersection parameter between the line and a plane taking into account line semantics. Returns an empty result if there is no intersection. On a Line3D this returns the same result as .Line().intersectionParameter(plane) More...  
double  ProjectionParameter (const Eigen::Vector3d &point) const 
Calculates the parameter of a point projected onto the line taking into account special semantics. More...  
virtual Eigen::Vector3d  Projection (const Eigen::Vector3d &point) const 
Calculates a point projected onto the line, taking into account special semantics. More...  
virtual utility::optional< double >  SlabAABB (const AxisAlignedBoundingBox &box) const 
Returns the lower intersection parameter for a line with an axis aligned bounding box or empty if no intersection. Uses the slab method, see warning below. More...  
virtual utility::optional< double >  ExactAABB (const AxisAlignedBoundingBox &box) const 
Returns the lower intersection parameter for a line with an axis aligned bounding box or empty if no intersection. This method is about 20x slower than the slab method, see details to know when to use. More...  
std::pair< double, double >  ClosestParameters (const Line3D &other) const 
Computes the two corresponding parameters of the closest distance between two Line3D objects, including derived types Ray3D and Segment3D, respecting the semantics of the line type. More...  
std::pair< Eigen::Vector3d, Eigen::Vector3d >  ClosestPoints (const Line3D &other) const 
Computes the two closest points between this Line3D object and the other, including of derived types Ray3D and Segment3D, respecting the semantics of the line types. More...  
double  DistanceTo (const Line3D &other) const 
Gets the closest distance between two Line3D objects, including derived types Ray3D and Segment3D, respecting the semantics of the line type. More...  
virtual double  ClampParameter (double parameter) const 
Clamps/bounds a parameter value to the closest valid place where the entity exists. On a Line3D, the value will be unchanged, on a Ray3D a negative value will be made 0, and on a Segment3D a negative value will be made 0 and a positive value greater than Length() will take the value of Length() More...  
virtual bool  IsParameterValid (double parameter) const 
Verifies that a given parameter value is valid for the semantics of the line object. For lines, any parameter is valid, for rays any positive parameter is valid, and for segments any parameter between 0 and the segment length is valid. More...  
Static Public Member Functions  
static Line3D  Through (const Eigen::Vector3d &p0, const Eigen::Vector3d &p1) 
Creates a line through two points. The line origin will take the value of p0, and the line direction will be a normalized vector from p0 to p1. More...  
Protected Member Functions  
Line3D (const Eigen::Vector3d &origin, const Eigen::Vector3d &direction, LineType type)  
Internal constructor for inherited classes that allows the setting of the LineType. More...  
std::pair< double, double >  SlabAABBBase (const AxisAlignedBoundingBox &box) const 
Calculates the common t_min and t_max values of the slab AABB intersection method. These values are computed identically for any semantic interpretation of the line, it's up to the derived classes to use them in conjunction with other information to determine what the intersection parameter is. More...  
Line3D is a class which derives from Eigen::ParametrizedLine<double, 3> in order to capture the semantic differences between a "line", "ray", and "line segment" for operations in which the difference is important, such as intersection and distance tests. The underlying Eigen object can always be retrieved with the .Line() method.
The taxonomy of the Line3D class and its derived classes, Ray3D and Segment3D, was created in order to find a compromise between the goals of providing an easytouse API, enforcing obvious correctness when dealing with operations in which line semantics are important, and maintaining reasonably high performance.
The underlying motivation is to enforce correctness when performing line operations based on Eigen::ParametrizedLine<double, 3> even as subtleties about how a line is represented begin to affect the outcomes of different operations. Some performance is sacrificed in the use of virtual functions for a clean API in cases where the compiler cannot determine at compile time which function will be called and cannot devirtualize the call.
In such cases where performance is extremely important, avoid iterating through a list of derived objects stored as Line3D and calling virtual functions on them so that the compiler can hopefully remove the vtable lookup, or consider a hand implementation of your problem in which you carefully account for the semantics yourself.

strong 
open3d::geometry::Line3D::Line3D  (  const Eigen::Vector3d &  origin, 
const Eigen::Vector3d &  direction  
) 
Default user constructor.

virtualdefault 

protected 
Internal constructor for inherited classes that allows the setting of the LineType.

inlinevirtual 
Clamps/bounds a parameter value to the closest valid place where the entity exists. On a Line3D, the value will be unchanged, on a Ray3D a negative value will be made 0, and on a Segment3D a negative value will be made 0 and a positive value greater than Length() will take the value of Length()
Reimplemented in open3d::geometry::Segment3D, and open3d::geometry::Ray3D.
std::pair< double, double > open3d::geometry::Line3D::ClosestParameters  (  const Line3D &  other  )  const 
std::pair< Eigen::Vector3d, Eigen::Vector3d > open3d::geometry::Line3D::ClosestPoints  (  const Line3D &  other  )  const 

inline 
Gets the line's direction vector.
double open3d::geometry::Line3D::DistanceTo  (  const Line3D &  other  )  const 

virtual 
Returns the lower intersection parameter for a line with an axis aligned bounding box or empty if no intersection. This method is about 20x slower than the slab method, see details to know when to use.
Calculates the lower intersection parameter of a parameterized line with an axis aligned bounding box. The intersection point can be recovered with .Line().pointAt(...). If the line does not intersect the box the return value will be empty. Also note that if the AABB is behind the line's origin point, the value returned will still be of the lower intersection, which is the first intersection in the direction of the line, not the intersection closer to the origin.
This implementation is a naive exact method that considers intersections with all six bounding box planes. It is not optimized for speed and should only be used when a problem is conditioned such that the slab method is unacceptable. Use this when a line is likely to lie exactly in one of the AABB planes and false negatives are unacceptable. Typically this will only happen when lines are axisaligned and both lines and bounding volumes are regularly spaced, and every intersection is important. In such cases if performance is important, a simple custom implementation based on the problem directionality will likely outperform even the slab method.
Reimplemented in open3d::geometry::Segment3D.

inline 
Gets the semantic type of the line.

virtual 
Calculates the intersection parameter between the line and a plane taking into account line semantics. Returns an empty result if there is no intersection. On a Line3D this returns the same result as .Line().intersectionParameter(plane)
Reimplemented in open3d::geometry::Segment3D, and open3d::geometry::Ray3D.

inlinevirtual 
Verifies that a given parameter value is valid for the semantics of the line object. For lines, any parameter is valid, for rays any positive parameter is valid, and for segments any parameter between 0 and the segment length is valid.
Reimplemented in open3d::geometry::Segment3D, and open3d::geometry::Ray3D.

inlinevirtual 
Gets the length of the line, which for lines and rays will return positive infinity, but for segments will return a finite positive value.
Reimplemented in open3d::geometry::Segment3D, and open3d::geometry::Ray3D.

inline 
Returns a const reference to the underlying Eigen::ParametrizedLine object.

inline 
Gets the line's origin point.

virtual 
Calculates a point projected onto the line, taking into account special semantics.
On a Line3D this is the point directly projected onto the infinite line, and represents the closest point on the line to the test point. On a Ray3D this will either be a point on the ray's positive direction or the ray origin, whichever is closer. On a Segment3D this will be either one of the segment's endpoints or a point between them, whichever is closest to the test point.
double open3d::geometry::Line3D::ProjectionParameter  (  const Eigen::Vector3d &  point  )  const 
Calculates the parameter of a point projected onto the line taking into account special semantics.
On a Line3D this is the point directly projected onto the infinite line, and represents the closest point on the line to the test point. A negative value indicates the projection lies behind the origin, a positive value is in front of the origin. On a Ray3D this will be a positive value only, since rays do not exist in the negative direction. On a Segment3D this will be a positive value which is less than or equal to the segment length.

virtual 
Returns the lower intersection parameter for a line with an axis aligned bounding box or empty if no intersection. Uses the slab method, see warning below.
Calculates the lower intersection parameter of a parameterized line with an axis aligned bounding box. The intersection point can be recovered with .Line().pointAt(...). If the line does not intersect the box the optional return value will be empty. Also note that if the AABB is behind the line's origin point, the value returned will still be of the lower intersection, which is the first intersection in the direction of the line, not the intersection closer to the origin.
This implementation is based off of Tavian Barnes' optimized branchless slab method. https://tavianator.com/2011/ray_box.html. It runs in roughly 5% of the time as the the naive exact method, but can degenerate in specific conditions where a line lies exactly in one of the AABB's planes.
Reimplemented in open3d::geometry::Segment3D, and open3d::geometry::Ray3D.

protected 
Calculates the common t_min and t_max values of the slab AABB intersection method. These values are computed identically for any semantic interpretation of the line, it's up to the derived classes to use them in conjunction with other information to determine what the intersection parameter is.

inlinestatic 
Creates a line through two points. The line origin will take the value of p0, and the line direction will be a normalized vector from p0 to p1.

virtual 
Transform the Line3D by the given matrix.
Reimplemented in open3d::geometry::Segment3D.