Open3D (C++ API)  0.12.0
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions
open3d::geometry::Line3D Class Reference

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>

Inheritance diagram for open3d::geometry::Line3D:
open3d::geometry::Ray3D open3d::geometry::Segment3D

Public Types

enum  LineType { LineType::Line = 0, LineType::Ray = 1, LineType::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...
 

Detailed Description

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 easy-to-use 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 de-virtualize 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.

Member Enumeration Documentation

◆ LineType

Specifies different semantic interpretations of 3d lines.

Enumerator
Line 

Lines extend infinitely in both directions.

Ray 

Rays have an origin and a direction, and extend to infinity in that direction

Segment 

Segments have both an origin and an endpoint and are finite in nature

Constructor & Destructor Documentation

◆ Line3D() [1/2]

open3d::geometry::Line3D::Line3D ( const Eigen::Vector3d &  origin,
const Eigen::Vector3d &  direction 
)

Default user constructor.

◆ ~Line3D()

virtual open3d::geometry::Line3D::~Line3D ( )
virtualdefault

◆ Line3D() [2/2]

open3d::geometry::Line3D::Line3D ( const Eigen::Vector3d &  origin,
const Eigen::Vector3d &  direction,
Line3D::LineType  type 
)
protected

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

Member Function Documentation

◆ ClampParameter()

virtual double open3d::geometry::Line3D::ClampParameter ( double  parameter) const
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.

◆ ClosestParameters()

std::pair< double, double > open3d::geometry::Line3D::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.

◆ ClosestPoints()

std::pair< Eigen::Vector3d, Eigen::Vector3d > open3d::geometry::Line3D::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.

◆ Direction()

const Eigen::Vector3d& open3d::geometry::Line3D::Direction ( ) const
inline

Gets the line's direction vector.

◆ DistanceTo()

double open3d::geometry::Line3D::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.

◆ ExactAABB()

utility::optional< double > open3d::geometry::Line3D::ExactAABB ( const AxisAlignedBoundingBox box) 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 axis-aligned 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.

◆ GetLineType()

LineType open3d::geometry::Line3D::GetLineType ( ) const
inline

Gets the semantic type of the line.

◆ IntersectionParameter()

utility::optional< double > open3d::geometry::Line3D::IntersectionParameter ( const Eigen::Hyperplane< double, 3 > &  plane) const
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.

◆ IsParameterValid()

virtual bool open3d::geometry::Line3D::IsParameterValid ( double  parameter) const
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.

◆ Length()

virtual double open3d::geometry::Line3D::Length ( ) const
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.

◆ Line()

const Eigen::ParametrizedLine<double, 3>& open3d::geometry::Line3D::Line ( ) const
inline

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

◆ Origin()

const Eigen::Vector3d& open3d::geometry::Line3D::Origin ( ) const
inline

Gets the line's origin point.

◆ Projection()

Eigen::Vector3d open3d::geometry::Line3D::Projection ( const Eigen::Vector3d &  point) const
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.

◆ ProjectionParameter()

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.

◆ SlabAABB()

utility::optional< double > open3d::geometry::Line3D::SlabAABB ( const AxisAlignedBoundingBox box) const
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.

Warning
A line that lies exactly in one of the AABB's planes within the double floating point precision will not intersect correctly by this method

Reimplemented in open3d::geometry::Segment3D, and open3d::geometry::Ray3D.

◆ SlabAABBBase()

std::pair< double, double > open3d::geometry::Line3D::SlabAABBBase ( const AxisAlignedBoundingBox box) const
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.

◆ Through()

static Line3D open3d::geometry::Line3D::Through ( const Eigen::Vector3d &  p0,
const Eigen::Vector3d &  p1 
)
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.

◆ Transform()

void open3d::geometry::Line3D::Transform ( const Eigen::Transform< double, 3, Eigen::Affine > &  t)
virtual

Transform the Line3D by the given matrix.

Reimplemented in open3d::geometry::Segment3D.


The documentation for this class was generated from the following files: