#include <CGAL/Polytope_distance_d.h>

Definition

template<typename Traits>
class CGAL::Polytope_distance_d< Traits >

An object of the class Polytope_distance_d represents the (squared) distance between two convex polytopes, given as the convex hulls of two finite point sets in \( d\)-dimensional Euclidean space \( \E^d\).

For point sets \( P\) and \( Q\) we denote by \( pd(P,Q)\) the distance between the convex hulls of \( P\) and \( Q\). Note that \( pd(P,Q)\) can be degenerate, i.e. \( pd(P,Q)=\infty\) if \( P\) or \( Q\) is empty.

Two inclusion-minimal subsets \( S_P\) of \( P\) and \( S_Q\) of \( Q\) with \( pd(S_P,S_Q)=pd(P,Q)\) are called pair of support sets, the points in \( S_P\) and \( S_Q\) are the support points. A pair of support sets has size at most \( d+2\) (by size we mean \( |S_P|+|S_Q|\)). The distance between the two polytopes is realized by a pair of points \( p\) and \( q\) lying in the convex hull of \( S_P\) and \( S_Q\), respectively, i.e. \( \sqrt{||p-q||}=pd(P,Q)\). In general, neither the support sets nor the realizing points are necessarily unique.

The underlying algorithm can cope with all kinds of input, e.g. \( P\) and \( Q\) may be in non-convex position or points may occur more than once. The algorithm computes a pair of support sets \( S_P\) and \( S_Q\) with realizing points \( p\) and \( q\) which remain fixed until the next set, insert, or clear operation.

Template Parameters

Traits must be a model for PolytopeDistanceDTraits.

We provide the models Polytope_distance_d_traits_2, Polytope_distance_d_traits_3, and Polytope_distance_d_traits_d using the two-, three-, and \( d\)-dimensional CGAL kernel, respectively.

See also: CGAL::Polytope_distance_d_traits_2<K,ET,NT>; CGAL::Polytope_distance_d_traits_3<K,ET,NT>; CGAL::Polytope_distance_d_traits_d<K,ET,NT>; PolytopeDistanceDTraits

Implementation

The problem of finding the distance between two convex polytopes given as the convex hulls of two finite point sets can be formulated as an optimization problem with linear constraints and a convex quadratic objective function. The solution is obtained using our exact solver for quadratic programs [2].

The creation time is almost always linear in the number of points. Access functions and predicates take constant time, inserting a point might take up to linear time. The clear operation and the check for validity each take linear time.

Examples: Polytope_distance_d/polytope_distance_d.cpp, and Polytope_distance_d/polytope_distance_d_fast_exact.cpp.

Related Functions
(Note that these are not member functions.)
std::ostream &	operator<< (std::ostream &os, const Polytope_distance_d< Traits > &poly_dist)
	writes `poly_dist` to output stream `os`.

std::istream &	operator>> (std::istream &is, Polytope_distance_d< Traits > poly_dist &)
	reads `poly_dist` from input stream `is`.

Types
typedef unspecified_type	Point
	typedef to `Traits::Point_d`.

typedef unspecified_type	FT
	typedef to `Traits::FT`.

typedef unspecified_type	ET
	typedef to `Traits::ET`.

typedef unspecified_type	Point_iterator
	non-mutable model of the STL concept RandomAccessIterator with value type `Point`.

typedef unspecified_type	Support_point_iterator
	non-mutable model of the STL concept RandomAccessIterator with value type `Point`.

typedef unspecified_type	Support_point_index_iterator
	non-mutable model of the STL concept RandomAccessIterator with value type `int`.

typedef unspecified_type	Coordinate_iterator
	non-mutable model of the STL concept RandomAccessIterator with value type `ET`.

Creation
	Polytope_distance_d (const Traits &traits=Traits(), int verbose=0, std::ostream &stream=std::cout)
	initializes `poly_dist` to \( pd(\emptyset, \emptyset)\).

template<class InputIterator1 , class InputIterator2 >
	Polytope_distance_d (InputIterator1 p_first, InputIterator1 p_last, InputIterator2 q_first, InputIterator2 q_last, const Traits &traits=Traits(), int verbose=0, std::ostream &stream=std::cout)
	initializes `poly_dist` to \( pd(P,Q)\) with \( P\) and \( Q\) being the sets of points in the range [`p_first`,`p_last`) and [`q_first`,`q_last`), respectively.

Access Functions
int	ambient_dimension () const
	returns the dimension of the points in \( P\) and \( Q\).

int	number_of_points () const
	returns the number of all points of `poly_dist`, i.e. \( \|P\|+\|Q\|\).

int	number_of_points_p () const
	returns the number of points in \( P\).

int	number_of_points_q () const
	returns the number of points in \( Q\).

int	number_of_support_points () const
	returns the number of support points of `poly_dist`, i.e. \( \|S_P\|+\|S_Q\|\).

int	number_of_support_points_p () const
	returns the number of support points in \( S_P\).

int	number_of_support_points_q () const
	returns the number of support points in \( S_Q\).

Point_iterator	points_p_begin () const
	returns an iterator referring to the first point in \( P\).

Point_iterator	points_p_end () const
	returns the corresponding past-the-end iterator.

Point_iterator	points_q_begin () const
	returns an iterator referring to the first point in \( Q\).

Point_iterator	points_q_end () const
	returns the corresponding past-the-end iterator.

Support_point_iterator	support_points_p_begin () const
	returns an iterator referring to the first support point in \( S_P\).

Support_point_iterator	support_points_p_end () const
	returns the corresponding past-the-end iterator.

Support_point_iterator	support_points_q_begin () const
	returns an iterator referring to the first support point in \( S_Q\).

Support_point_iterator	support_points_q_end () const
	returns the corresponding past-the-end iterator.

Support_point_index_iterator	support_points_p_indices_begin () const
	returns an iterator referring to the index of the first support point in \( P\).

Support_point_index_iterator	support_points_p_indices_end () const
	returns the corresponding past-the-end iterator.

Support_point_index_iterator	support_points_q_indices_begin () const
	returns an iterator referring to the index of the first support point in \( Q\).

Support_point_index_iterator	support_points_q_indices_end () const
	returns the corresponding past-the-end iterator.

Point	realizing_point_p () const
	returns the realizing point of \( P\).

Point	realizing_point_q () const
	returns the realizing point of \( Q\).

FT	squared_distance () const
	returns the squared distance of `poly_dist`, i.e. \( (pd(P,Q))^2\).

Coordinate_iterator	realizing_point_p_coordinates_begin () const
	returns an iterator referring to the first coordinate of the realizing point of \( P\).

Coordinate_iterator	realizing_point_p_coordinates_end () const
	returns the corresponding past-the-end iterator.

Coordinate_iterator	realizing_point_q_coordinates_begin () const
	returns an iterator referring to the first coordinate of the realizing point of \( Q\).

Coordinate_iterator	realizing_point_q_coordinates_end () const
	returns the corresponding past-the-end iterator.

ET	squared_distance_numerator () const
	returns the numerator of the squared distance of `poly_dist`.

ET	squared_distance_denominator () const
	returns the denominator of the squared distance of `poly_dist`.

Predicates
bool	is_finite () const
	returns `true`, if \( pd(P,Q)\) is finite, i.e. none of the two polytopes is empty.

bool	is_zero () const
	returns `true`, if \( pd(P,Q)\) is zero, i.e. the two polytopes intersect (this implies degeneracy).

bool	is_degenerate () const
	returns `true`, iff \( pd(P,Q)\) is degenerate, i.e. \( pd(P,Q)\) is not finite.

Modifiers
void	clear ()
	resets `poly_dist` to \( pd(\emptyset, \emptyset)\).

template<class InputIterator1 , class InputIterator2 >
void	set (InputIterator1 p_first, InputIterator1 p_last, InputIterator2 q_first, InputIterator2 q_last)
	sets `poly_dist` to \( pd(P,Q)\) with \( P\) and \( Q\) being the sets of points in the ranges [`p_first`,`p_last`) and [`q_first`,`q_last`), respectively.

template<class InputIterator >
void	set_p (InputIterator p_first, InputIterator p_last)
	sets `poly_dist` to \( pd(P,Q)\) with \( P\) being the set of points in the range [`p_first`,`p_last`) ( \( Q\) remains unchanged).

template<class InputIterator >
void	set_q (InputIterator q_first, InputIterator q_last)
	sets `poly_dist` to \( pd(P,Q)\) with \( Q\) being the set of points in the range [`q_first`,`q_last`) ( \( P\) remains unchanged).

void	insert_p (const Point &p)
	inserts `p` into \( P\).

void	insert_q (const Point &q)
	inserts `q` into \( Q\).

template<class InputIterator1 , class InputIterator2 >
void	insert (InputIterator1 p_first, InputIterator1 p_last, InputIterator2 q_first, InputIterator2 q_last)
	inserts the points in the range [`p_first`,`p_last`) and [`q_first`,`q_last`) into \( P\) and \( Q\), respectively, and recomputes the (squared) distance.

template<class InputIterator >
void	insert_p (InputIterator p_first, InputIterator p_last)
	inserts the points in the range [`p_first`,`p_last`) into \( P\) and recomputes the (squared) distance ( \( Q\) remains unchanged).

template<class InputIterator >
void	insert_q (InputIterator q_first, InputIterator q_last)
	inserts the points in the range [`q_first`,`q_last`) into \( Q\) and recomputes the (squared) distance ( \( P\) remains unchanged).

Validity Check
bool	is_valid (bool verbose=false, int level=0) const
	returns `true`, iff `poly_dist` is valid.

Miscellaneous
const Traits &	traits () const
	returns a const reference to the traits class object.

Member Typedef Documentation

◆ Coordinate_iterator

template<typename Traits >

typedef unspecified_type CGAL::Polytope_distance_d< Traits >::Coordinate_iterator

non-mutable model of the STL concept RandomAccessIterator with value type ET.

Used to access the coordinates of the realizing points.

◆ ET

template<typename Traits >

typedef unspecified_type CGAL::Polytope_distance_d< Traits >::ET

typedef to Traits::ET.

Number type used to do the exact computations in the underlying solver for quadratic programs (cf. Implementation).

◆ FT

template<typename Traits >

typedef unspecified_type CGAL::Polytope_distance_d< Traits >::FT

typedef to Traits::FT.

Number type used to return the squared distance between the two polytopes.

◆ Point

template<typename Traits >

typedef unspecified_type CGAL::Polytope_distance_d< Traits >::Point

typedef to Traits::Point_d.

Point type used to represent the input points.

◆ Point_iterator

template<typename Traits >

typedef unspecified_type CGAL::Polytope_distance_d< Traits >::Point_iterator

non-mutable model of the STL concept RandomAccessIterator with value type Point.

Used to access the points of the two polytopes.

◆ Support_point_index_iterator

template<typename Traits >

typedef unspecified_type CGAL::Polytope_distance_d< Traits >::Support_point_index_iterator

non-mutable model of the STL concept RandomAccessIterator with value type int.

Used to access the indices of the support points in the provided input order (starting from 0 in both point sets).

◆ Support_point_iterator

template<typename Traits >

typedef unspecified_type CGAL::Polytope_distance_d< Traits >::Support_point_iterator

non-mutable model of the STL concept RandomAccessIterator with value type Point.

Used to access the support points.

Constructor & Destructor Documentation

◆ Polytope_distance_d()

template<typename Traits >

template<class InputIterator1 , class InputIterator2 >

CGAL::Polytope_distance_d< Traits >::Polytope_distance_d	(	InputIterator1	p_first,
		InputIterator1	p_last,
		InputIterator2	q_first,
		InputIterator2	q_last,
		const Traits &	traits = `Traits()`,
		int	verbose = `0`,
		std::ostream &	stream = `std::cout`
	)

initializes poly_dist to \( pd(P,Q)\) with \( P\) and \( Q\) being the sets of points in the range [p_first,p_last) and [q_first,q_last), respectively.

Template Parameters

InputIterator1	has `Point` as value type.
InputIterator2	has `Point` as value type.

Precondition: All points have the same dimension.

Attention: If verbose is set to \( 1\), \( 2\), or \( 3\) then some, more, or full verbose output of the underlying solver for quadratic programs is written to stream, resp.

Member Function Documentation

◆ ambient_dimension()

template<typename Traits >

int CGAL::Polytope_distance_d< Traits >::ambient_dimension ( ) const

returns the dimension of the points in \( P\) and \( Q\).

If poly_dist is \( pd(\emptyset, \emptyset)\), the ambient dimension is \( -1\).

◆ insert()

template<typename Traits >

template<class InputIterator1 , class InputIterator2 >

void CGAL::Polytope_distance_d< Traits >::insert	(	InputIterator1	p_first,
		InputIterator1	p_last,
		InputIterator2	q_first,
		InputIterator2	q_last
	)

inserts the points in the range [p_first,p_last) and [q_first,q_last) into \( P\) and \( Q\), respectively, and recomputes the (squared) distance.

Template Parameters

InputIterator1	has `Point` as value type.
InputIterator2	has `Point` as value type.

Precondition: All points have the same dimension. If poly_dist is not \( pd(\emptyset, \emptyset)\), this dimension must be equal to poly_dist.ambient_dimension().

◆ insert_p() [1/2]

template<typename Traits >

void CGAL::Polytope_distance_d< Traits >::insert_p ( const Point & p )

inserts p into \( P\).

Precondition: The dimension of p equals poly_dist.ambient_dimension() if poly_dist is not \( pd(\emptyset, \emptyset)\).

◆ insert_p() [2/2]

template<typename Traits >

template<class InputIterator >

void CGAL::Polytope_distance_d< Traits >::insert_p	(	InputIterator	p_first,
		InputIterator	p_last
	)

inserts the points in the range [p_first,p_last) into \( P\) and recomputes the (squared) distance ( \( Q\) remains unchanged).

Template Parameters

InputIterator has Point as value type.

Precondition: All points have the same dimension. If poly_dist is not empty, this dimension must be equal to poly_dist.ambient_dimension().

◆ insert_q() [1/2]

template<typename Traits >

void CGAL::Polytope_distance_d< Traits >::insert_q ( const Point & q )

inserts q into \( Q\).

Precondition: The dimension of q equals poly_dist.ambient_dimension() if poly_dist is not \( pd(\emptyset, \emptyset)\).

◆ insert_q() [2/2]

template<typename Traits >

template<class InputIterator >

void CGAL::Polytope_distance_d< Traits >::insert_q	(	InputIterator	q_first,
		InputIterator	q_last
	)

inserts the points in the range [q_first,q_last) into \( Q\) and recomputes the (squared) distance ( \( P\) remains unchanged).

Template Parameters

InputIterator has Point as value type.

Precondition: All points have the same dimension. If poly_dist is not empty, this dimension must be equal to poly_dist.ambient_dimension().

◆ is_valid()

template<typename Traits >

bool CGAL::Polytope_distance_d< Traits >::is_valid	(	bool	verbose = `false`,
		int	level = `0`
	)		const

returns true, iff poly_dist is valid.

If verbose is true, some messages concerning the performed checks are written to standard error stream. The second parameter level is not used, we provide it only for consistency with interfaces of other classes.

An object poly_dist is valid, iff \( ldots\)

poly_dist contains all points of its defining set \( P\),
poly_dist is the smallest sphere containing its support set \( S\),
and \( S\) is minimal, i.e. no support point is redundant.

◆ realizing_point_p()

template<typename Traits >

Point CGAL::Polytope_distance_d< Traits >::realizing_point_p ( ) const

returns the realizing point of \( P\).

An implicit conversion from ET to RT must be available.

Precondition: \( pd(P,Q)\) is finite.

◆ realizing_point_p_coordinates_begin()

template<typename Traits >

Coordinate_iterator CGAL::Polytope_distance_d< Traits >::realizing_point_p_coordinates_begin ( ) const

returns an iterator referring to the first coordinate of the realizing point of \( P\).

Note: The coordinates have a rational representation, i.e. the first \( d\) elements of the iterator range are the numerators and the \( (d\!+\!1)\)-st element is the common denominator.

◆ realizing_point_q()

template<typename Traits >

Point CGAL::Polytope_distance_d< Traits >::realizing_point_q ( ) const

returns the realizing point of \( Q\).

An implicit conversion from ET to RT must be available.

Precondition: \( pd(P,Q)\) is finite.

◆ realizing_point_q_coordinates_begin()

template<typename Traits >

Coordinate_iterator CGAL::Polytope_distance_d< Traits >::realizing_point_q_coordinates_begin ( ) const

returns an iterator referring to the first coordinate of the realizing point of \( Q\).

Note: The coordinates have a rational representation, i.e. the first \( d\) elements of the iterator range are the numerators and the \( (d\!+\!1)\)-st element is the common denominator.

◆ set()

template<typename Traits >

template<class InputIterator1 , class InputIterator2 >

void CGAL::Polytope_distance_d< Traits >::set	(	InputIterator1	p_first,
		InputIterator1	p_last,
		InputIterator2	q_first,
		InputIterator2	q_last
	)

sets poly_dist to \( pd(P,Q)\) with \( P\) and \( Q\) being the sets of points in the ranges [p_first,p_last) and [q_first,q_last), respectively.

Template Parameters

InputIterator1	has `Point` as value type.
InputIterator2	has `Point` as value type.

Precondition: All points have the same dimension.

◆ set_p()

template<typename Traits >

template<class InputIterator >

void CGAL::Polytope_distance_d< Traits >::set_p	(	InputIterator	p_first,
		InputIterator	p_last
	)

sets poly_dist to \( pd(P,Q)\) with \( P\) being the set of points in the range [p_first,p_last) ( \( Q\) remains unchanged).

Template Parameters

InputIterator has Point as value type.

Precondition: All points in \( P\) have dimension poly_dist.ambient_dimension() if \( Q\) is not empty.

◆ set_q()

template<typename Traits >

template<class InputIterator >

void CGAL::Polytope_distance_d< Traits >::set_q	(	InputIterator	q_first,
		InputIterator	q_last
	)

sets poly_dist to \( pd(P,Q)\) with \( Q\) being the set of points in the range [q_first,q_last) ( \( P\) remains unchanged).

Template Parameters

InputIterator has Point as value type.

Precondition: All points in \( Q\) have dimension poly_dist.ambient_dimension() if \( P\) is not empty.

◆ squared_distance()

template<typename Traits >

FT CGAL::Polytope_distance_d< Traits >::squared_distance ( ) const

returns the squared distance of poly_dist, i.e. \( (pd(P,Q))^2\).

An implicit conversion from ET to RT must be available.

Precondition: \( pd(P,Q)\) is finite.

Friends And Related Function Documentation

◆ operator<<()

template<typename Traits >

std::ostream & operator<<	(	std::ostream &	os,
		const Polytope_distance_d< Traits > &	poly_dist
	)

An overload of operator<< must be defined for Point_d.

◆ operator>>()

template<typename Traits >

std::istream & operator>>	(	std::istream &	is,
		Polytope_distance_d< Traits > poly_dist &
	)

An overload of operator>> must be defined for Point_d.

Definition

Related Functions

Types

Creation

Access Functions

Predicates

Modifiers

Validity Check

Miscellaneous

Member Typedef Documentation

◆ Coordinate_iterator

◆ ET

◆ FT

◆ Point

◆ Point_iterator

◆ Support_point_index_iterator

◆ Support_point_iterator

Constructor & Destructor Documentation

◆ Polytope_distance_d()

Member Function Documentation

◆ ambient_dimension()

◆ insert()

◆ insert_p() [1/2]

◆ insert_p() [2/2]

◆ insert_q() [1/2]

◆ insert_q() [2/2]

◆ is_valid()

◆ realizing_point_p()

◆ realizing_point_p_coordinates_begin()

◆ realizing_point_q()

◆ realizing_point_q_coordinates_begin()

◆ set()

◆ set_p()

◆ set_q()

◆ squared_distance()

Friends And Related Function Documentation

◆ operator<<()

◆ operator>>()