lass::prim::Line2D< T, EquationPolicy, NormalizingPolicy > Class Template Reference

2D Line More...

#include <line_2d.h>

Inheritance diagram for lass::prim::Line2D< T, EquationPolicy, NormalizingPolicy >:

Collaboration diagram for lass::prim::Line2D< T, EquationPolicy, NormalizingPolicy >:

Public Member Functions
Side	classify (const TPoint &iPoint) const
	Return on what side a point is located.
const TValue	signedDistance (const TPoint &iPoint) const
	Return signed distance of point to line.
const TValue	squaredDistance (const TPoint &iPoint) const
	Return signed distance of point to line.
Side	classify (const TPoint &iPoint, TParam iRelativeTolerance) const
	Return on what side a point is located.
const TValue	signedDistance (const TPoint &iPoint, TParam iRelativeTolerance) const
	Return signed distance of point to line.
const TValue	squaredDistance (const TPoint &iPoint, TParam iRelativeTolerance) const
	Return signed distance of point to line.
const TPoint	support () const
	return generated support point.
const TVector	direction () const
	return generated direction vector.
const TValue	equation (const TPoint &iPoint) const
	Return value of point in equation.
const TValue	equation (const TPoint &iPoint, TParam iRelativeTolerance) const
	Return value of point in equation, snapped to zero by iRelativeTolerance.
const TVector	reject (const TPoint &iPoint) const
	return the vector that, if added to the PROJECTION of iPoint, you get iPoint again.
const TVector	reject (const TVector &iVector) const
	return the part of iVector that is orthogonal to the line.
const TPoint	project (const TPoint &iPoint) const
	project a point orthogonally onto the line
const TVector	project (const TVector &iVector) const
	project a vector orthogonally onto the line
const TPoint	reflect (const TPoint &iPoint) const
	reflect a point orthogonally into the line.
const TVector	reflect (const TVector &iVector) const
	reflect a vector orthogonally into the line
const TPoint	point (TParam iT) const
	return point by filling in parameter in generated parametric equation
const TValue	t (const TPoint &iPoint) const
	return parameter along generated paremetric equation.
bool	isValid () const
	return true if line is a valid line (no normal or direction vectors that are zero).

Related Symbols
(Note that these are not member symbols.)
template<typename T, class EP, class NP>
T	distance (const Point2D< T > &iA, const Line2D< T, EP, NP > &iB)
	absolute distance between point and line.
template<typename T, class EPa, class NPa, class EPb, class NPb>
T	distance (const Line2D< T, EPa, NPa > &iA, const Line2D< T, EPb, NPb > &iB)
	absolute distance between two lines
template<typename T, class EPa, class NPa, class EPb, class NPb>
Result	intersect (const Line2D< T, EPa, NPa > &iA, const Line2D< T, EPb, NPb > &iB, T &oTa, T &oTb)
	intersection of two lines
template<typename T, class EPa, class NPa, class EPb, class NPb>
Result	intersect (const Line2D< T, EPa, NPa > &iA, const Line2D< T, EPb, NPb > &iB, Point2D< T > &oPoint)
	intersection of two lines
template<typename T, class PPa, class PPb>
Result	intersect (const LineSegment2D< T, PPa > &a, const LineSegment2D< T, PPb > &b, Point2D< T > &point)
	intersection of two line segments

Detailed Description

template<typename T, class EquationPolicy = Cartesian, class NormalizingPolicy = Normalized>
class lass::prim::Line2D< T, EquationPolicy, NormalizingPolicy >

2D Line

Author

Bram de Greve [BdG]

Date

2003

I assume if you look to this class, you'll wonder ... "where the heck did all the code go?" Hah, I'll tell ya. There is more than one possible model to represent a line. We can use a cartesian equation N.P+S=0, or we can use a parametric equation P=S+t*U. This class lets you choose what implementation you want: a pure cartesian model, a pure parametric model, or a model that combines both. This is done by moving all code to implemenations impl::Line2DCartesian, impl::Line2DParametric or impl::Line2DCombined. Line2D will inherit its implementation of the model you've choosen. You can select the one you want by specifying the template parameter EquationPolicy. You can either use Cartesian (which is the default), Parametric or Combined. Each of them will model the line differently. They all provide the same interface, but might have different results. They might have different memory footprints, different performances, and are optimized for different purposes. Cartesian will select an implementation that only uses the cartesian equation and will be the smallest and the fastest for most purposes (that's why it is the default :). But sometimes, you might more like the Parametric model, because it has better support for direction vectors, but it'll have to calculate the normal on the spot if you need it. Combined is the workhorse for heavy duties and implements both..

arguments

• T: the underlying data type, the proton.
• @ref EquationPolicy: chooses the model: Cartesian, Parametric or Combined
• @ref NormalizingPolicy: enables automatic normalizing or not: Normalized or Unnormalized

common interface

Anyway, let me give you some general info on this whole Line2D thing. Though there are three different implentations, they all have the same interface. We'll explore them by this common interface:

type definitions

• TSelf: the type of this
• TImpl: type of implemantion, can be impl::Line2DCartesian, impl::Line2DParametric or impl::Line2DCombined.
• TNormalizingPolicy: the type you've used as NormalizingPolicy.
• TPoint: type of a afine point in space.
• TVector: type of a vector in space.
• TValue: same as util::CallTraits<T>::TValue.
• TParam: same as util::CallTraits<T>::TParam.
• TReference: same as util::CallTraits<T>::TReference.
• TConstReference: same as util::CallTraits<T>::TConstReference.
• TNumTraits: same as num::NumTraits<T>.

constructors

Line2D():

the default constructor brings the line in an invalid state. normal and/or direction vector will have zero length, which indicates for this invalid state.

Line2D(const TPoint& iSupport, const TPoint& iPoint):

construct a line through two points. The parametric equation P=S+t*U is going to be constructed as following: iSupport will be the support point S, and direction vector U will be drawn from the support point to iPoint: U = iPointU - iSupport. The cartesian equation N.P+d==0 is constructed as following: the normal N=perpDot(U) and d is determined by demaning that N.S+d==0.

Line2D(const TPoint& iSupport, const TVector& iDirection):

constructs a line through one support point and one direction vector (the parametric equation, anyone? :). For the parametric equation P=S+t*U, we have iSupport for S, iDirection for U. Again the cartesian equation N.P+d==0 is given by N=perpDot(U) and N.S+d==0.

Line2D(const TPoint& iSupport, const TVector& iNormal):

constructs a line through a support point and a normal vector. For the parametric equation P=S+t*U, we have iSupport for S, and U=-perpDot(N). The cartesian N.P+d==0 is simple, we have iNormal for N and d can be found by N.S+d==0.

Line2D(const TVector& iNormal, TParam iD):

construct a line by a normal vector and fourth value (cartesian equation? :). For the parametric equation P=S+t*U, all have to generated: for S we use the point -iD*iNormal that is the closest point of the line to the origin, U is given by U=-perpDot(N). For the cartesian equation N.P+d==0, we of course use N = iNormal and d = iD.

accessors

After construction, all vectors are normalized depending on the NormalizingPolicy you've choosen as template argument. if the normal vector N is scaled, then d is scaled as well, so it still represents the same line.

Now, we have a series of accessors that give you access to the internal data of the line, including support point, direction vectors, normal vector, ... Only Line2DCombined will be able to pull these directly from its internals, but the others don't have all data aboard, so they have to generate them. Be carefull, because it's not always what you suspect.

const TPoint support():

returns the support point of the line. If you used a support point for the construction of the line, models Line2DParametric and Line2DCombined will give you back this original one, exactly till the last bit. Line2DCartesian doesn't keep track of support points, so it has to create one if you ask for it. It uses -d*N, the point of the line that is closest to the origin. Mind you that this one probably will not be the same as the original one, totally different even! Of course, if you used a cartesian equation to construct the line (without any support point), then all three models need to generate a support point at some point: -d*N. In that case, all three models will return the same support point.

const TVector direction():

get the direction vector of the line. almost same story as for support(). If you've created the line by a direction vector ot two points (which leads to the direction vector), then models Line2DParametric and Line2DCombined will give you back these originals (for Unnormalized lines only! but in case of Normalized lines, they still correspond with the original directions). Line2DCartesian has to regenerate them, but it will result in the same direction vector as the others.

void getCartesian(TVector& oNormal, TReference oD):

gets normal vector and d-value for the cartesian equation. Now, this is the first one Line2DCartesian has aboard itself. Line2DCombined also has it, but now it's up to Line2DParametric to generate some stuff :) Though, it's less worse than the other way around. This is because the parametric equation contains more information on the support point, and doesn't have to 'invent' anything like Line2DCartesian has to. Actually, in theory, all three models should return the same normal and d-value. In practice however, we have to deal with numerical imprecisions. so the result of Line2DParametric can differ a little in the last bits. not a big difference, but enough to be inequal.

const TVector normal():

returns only the normal vector of the cartesian equation. For Line2DParametric we have again the same remark as for getDirections and getReciprocals: it uses getCartesian anyway, so that might be faster if you both need the normal and d-value.

TValue d():

same as normal(), but returns only the value d instead of the normal vector.

cartesian methods

So far the accessors. let's get to cooler stuff. For most of this stuff, we need the cartesian equation. Line2DCartesian and Line2DCombined have it on board, but Line2DParametric will have to generate it each call. Keep that in mind!

Side classify(const TPoint& iPoint):

tells at which side of the line we can find the point iPoint: the front (sFront), the back (sBack), or right on the surface (sSurface). the front is the side where the normal sticks or points to. The back is the other one. iPoint is exactly one the surface if N.iPoint+d==0. Since we need the parametric equation, Line2DParametric might have a performance hit here.

TValue equation(const TPoint& iPoint):

fills in the point iPoint in the cartesian equation and returns the resutl. N.iPoint+d will usually not be equal to zero (it's only zero for points on the line). This method returns what it is equal to. i.e. it returns N.iPoint+d. For Normalized lines this is the same as the distance of iPoint to the line, but not for Unnormalized lines, keep that in mind! If you need the distance, used signedDistances() as described below. Again you might have a performance hit for the Line2DParametric model because of the need of the cartesian equation.

TValue signedDistance(const TPoint& iPoint):

returns the distance of the point to the line, but signed. it will be positive for points in front of the line, and negative for the ones in the back (also see: classify()). The real (absolute) distances is simply the absolute value of the result. For Normalized lines signedDistances() will be equal to equation(). But for Unnormalized lines signedDistances still divides through the normal's length Again performance hit for Line2DParametric because of the need of the cartesian equation.

TVector reject(const TPoint& iPoint):

returns rejection of iPoint by the line. This is a bit tricky to explain. If you have a support point S, then this rejection is the part of iPoint-S that is parallel to the normal vector (or orthogonal to the line). This would be the same as the rejection of iPoint-S (given by reject(iPoint-S), see below). But more descriptive might be: it is the vector you have to add to the projection of this point on the line (given by project(iPoint), see below), to get back iPoint: iPoint==project(iPoint)+reject(iPoint). Again performance hit for Line2DParametric because of the cartesian equation.

TVector reject(const TVector& iVector):

returns rejection of iVector by the line. This is already somewhat easier. the rejection of iVector is that part of iVector that is parallel to the normal vector of the line. You can also say that it is the orthogonal projection of iVector on the normal vector. Or the part of iVector that is orthogonal to the line. Again performance hit for Line2DParametric because of the cartersian equation.

TPoint project(const TPoint& iPoint):

return the orthogonal projection of iPoint on the line. It is the point on the line that is the closest one to iPoint. If you draw a line through iPoint parallel to the normal vector, this projection is the point where this line intersects the line. It is know that in theory iPoint==project(iPoint)+reject(iPoint). Again performance hit for Line2DParametric because of the cartesian equation.

TVector project(const TVector& iVector):

return the orthogonal projection of iVector on the line. It is the part of iVector that is parallel to the line, or orthogonal to the normal vector. It is known that in theory iVector==project(iVector)+reject(iVector). Again performance hit for Line2DParametric because of the cartesian equation.

TPoint reflect(const TPoint& iPoint):

return the reflection of iPoint in the line. It is the point at the same distance of the line, but at the exact opposite side of the line. If you draw a line through iPoint parallel to the normal vector, it's the only other point on that line that is at the same (absolute) distance of the line. If you walk from iPoint to the intersection point of the line and the line, and you walk further the same distance again, you arrive at reflection of iPoint. It is known that in theory reflect(iPoint)==project(iPoint)-reject(iPoint). Again performance hit for Line2DParametric because of the cartesian equation.

TVector reflect(const TVector& iVector):

return the reflection of iVector in the line. It's the vector of which the orthogonal part to the line is flipped. It is know that reflect(iVector)==project(iVector)-reject(iVector). Again performance hit for Line2DParametric because of the cartesian equation.

parametric methods

So far functions for the cartesian boys. Now some stuff for parametric fellows. It's about how we can get a point of the line if we now its parametr t, and how we can find @t if we know the point on the line.

TPoint point(TParam iT):

returns a point of the parametric equation P=S+iT*U. In case of Line2DCartesian, we have the same remarks as for direction(): not only we have a performance hit, we probably also have to deal with totally different direction vectors than the ones we have put in the constructor.

TValue t(const TPoint& iPoint):

returns a value t so that iPoint==S+t*U. In theory, if you put this back in point(), you should end up with the projection of iPoint: point(t(iPoint))==project(iPoint) ? Well, this is not totally true. In practice, numerical imprecisions will probably give you a slightly different result. You'll be very close, but the last bits will differ enough to make the them inequal. But with some epsilons, you'll be alright.

misc. methods

void flip():

flips the line so that the front becomes the back and the back becomes the front. For the cartesian equation, this is done by negating the normal and d: N=-N and d=-d. Of the parametric equation, direction vector U is flipped: U=-U.

bool isValid():

returns true if the interal data represents a valid line, and false if not. A line is valid if none of the direction vectors nor the normal vector are zero vectors. And above of that, the direction vectors may not be colinear. Of course, we only test internal data. We will not generate direction vectors (in case of Line2DCartesian), just to test the if they are valid. We can safely do that, because we know that if the normal vector is valid, then the generated directions will be too.

functions

There are some free functions listed below: distances and intersections. They are common for all lines and can handle mixed equation policies (two lines with different equation policies).

Definition at line 305 of file line_2d.h.

Member Function Documentation

signedDistance() [1/2]

template<typename T, typename EP, typename NP>

const Line2D< T, EP, NP >::TValue lass::prim::Line2D< T, EP, NP >::signedDistance

(

const TPoint &

iPoint

)

const

Return signed distance of point to line.

negative value means point is in the back.

Definition at line 118 of file line_2d.inl.

References lass::prim::impl::Line2DCartesian< T, NormalizingPolicy >::equation(), and signedDistance().

Referenced by distance(), distance(), signedDistance(), signedDistance(), squaredDistance(), and squaredDistance().

squaredDistance() [1/2]

template<typename T, typename EP, typename NP>

const Line2D< T, EP, NP >::TValue lass::prim::Line2D< T, EP, NP >::squaredDistance

(

const TPoint &

iPoint

)

const

Return signed distance of point to line.

negative value means point is in the back.

Definition at line 130 of file line_2d.inl.

References signedDistance(), lass::num::sqr(), and squaredDistance().

Referenced by squaredDistance(), and squaredDistance().

signedDistance() [2/2]

template<typename T, typename EP, typename NP>

const Line2D< T, EP, NP >::TValue lass::prim::Line2D< T, EP, NP >::signedDistance	(	const TPoint &	iPoint,
		TParam	iRelativeTolerance ) const

Return signed distance of point to line.

negative value means point is in the back.

Definition at line 153 of file line_2d.inl.

References lass::prim::impl::Line2DCartesian< T, NormalizingPolicy >::equation(), and signedDistance().

squaredDistance() [2/2]

template<typename T, typename EP, typename NP>

const Line2D< T, EP, NP >::TValue lass::prim::Line2D< T, EP, NP >::squaredDistance	(	const TPoint &	iPoint,
		TParam	iRelativeTolerance ) const

Return signed distance of point to line.

negative value means point is in the back.

Definition at line 165 of file line_2d.inl.

References signedDistance(), lass::num::sqr(), and squaredDistance().

support() [1/2]

const TPoint lass::prim::impl::Line2DCartesian< T, NormalizingPolicy >::support ( ) const

inherited

return generated support point.

Returns

-d * N

support() [2/2]

const Line2DCartesian< T, NP >::TPoint lass::prim::impl::Line2DCartesian< T, NP >::support ( ) const

inherited

return generated support point.

Returns

-d * N

Definition at line 88 of file line_2d_cartesian.inl.

reject() [1/4]

const TVector lass::prim::impl::Line2DCartesian< T, NormalizingPolicy >::reject ( const TPoint & iPoint ) const

inherited

return the vector that, if added to the PROJECTION of iPoint, you get iPoint again.

iPoint == (almost) project(iPoint) + reject(iPoint)

reject() [2/4]

const TVector lass::prim::impl::Line2DCartesian< T, NormalizingPolicy >::reject ( const TVector & iVector ) const

inherited

return the part of iVector that is orthogonal to the line.

it's the vector that, if added to the PROJECTION of iVector, you get iVector again. iVector == (almost) project(iVector) + reject(iVector).

reject() [3/4]

const Line2DCartesian< T, NP >::TVector lass::prim::impl::Line2DCartesian< T, NP >::reject ( const TPoint & iPoint ) const

inherited

return the vector that, if added to the PROJECTION of iPoint, you get iPoint again.

iPoint == (almost) project(iPoint) + reject(iPoint)

Definition at line 98 of file line_2d_cartesian.inl.

reject() [4/4]

const Line2DCartesian< T, NP >::TVector lass::prim::impl::Line2DCartesian< T, NP >::reject ( const TVector & iVector ) const

inherited

return the part of iVector that is orthogonal to the line.

it's the vector that, if added to the PROJECTION of iVector, you get iVector again. iVector == (almost) project(iVector) + reject(iVector).

Definition at line 99 of file line_2d_cartesian.inl.

Friends And Related Symbol Documentation

distance() [1/2]

template<typename T, class EP, class NP>

T distance ( const Point2D< T > & iA, const Line2D< T, EP, NP > & iB )

related

absolute distance between point and line.

Parameters

iA	point
iB	line

Returns

absolute distance.

Definition at line 189 of file line_2d.inl.

distance() [2/2]

template<typename T, class EPa, class NPa, class EPb, class NPb>

T distance ( const Line2D< T, EPa, NPa > & iA, const Line2D< T, EPb, NPb > & iB )

related

absolute distance between two lines

Parameters

iA	line A
iB	line B

Returns

absolute distance.

Definition at line 203 of file line_2d.inl.

intersect() [1/3]

template<typename T, class EPa, class NPa, class EPb, class NPb>

Result intersect ( const Line2D< T, EPa, NPa > & iA, const Line2D< T, EPb, NPb > & iB, T & oTa, T & oTb )

related

intersection of two lines

Parameters

iA	line A
iB	line B
oTa	parameter of intersection point on line A
oTb	parameter of intersection point on line B

Returns

• rNone the lines don't intersect, they have no points in common. oTa and oTb are not assigned.
• rOne both lines have exactly one point in common. oTa and oTb contain parameters of intersection point.
• rInfinite the lines are coincident, they have all points in common. oTa and oTb are not assigned.

Definition at line 235 of file line_2d.inl.

intersect() [2/3]

template<typename T, class EPa, class NPa, class EPb, class NPb>

Result intersect ( const Line2D< T, EPa, NPa > & iA, const Line2D< T, EPb, NPb > & iB, Point2D< T > & oPoint )

related

intersection of two lines

Parameters

iA	line A
iB	line B
oPoint	intersection point

Returns

• rNone the lines don't intersect, they have no points in common. oPoint is not assigned.
• rOne both lines have exactly one point in common. oPoint contains intersection point.
• rInfinite the lines are coincident, they have all points in common. oPoint is not assigned.

Definition at line 285 of file line_2d.inl.

intersect() [3/3]

template<typename T, class PPa, class PPb>

Result intersect ( const LineSegment2D< T, PPa > & a, const LineSegment2D< T, PPb > & b, Point2D< T > & point )

related

intersection of two line segments

Parameters

a	[in] line segment A
b	[in] line segment B
point	[out] intersection point

Returns

• rNone the line segments don't intersect, they have no points in common. point is not assigned.
• rOne both line segments have exactly one point in common. point contains intersection point.
• rInfinite the line segments have more than one point in common, they overlap. point is not assigned.

Definition at line 276 of file line_segment_2d.inl.

---

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

• line_2d.h
• line_2d.inl
• line_segment_2d.inl