CGAL 6.1.2 - Bounding Volumes: CGAL::Min_sphere_d< Traits > Class Template Reference

CGAL 6.1.2 - Bounding Volumes

Loading...
Searching...
No Matches
List of all members | Related Functions
CGAL::Min_sphere_d< Traits > Class Template Reference
Reference Manual

`#include <CGAL/Min_sphere_d.h>`

## Definition

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

An object of the class `Min_sphere_d` is the unique sphere of smallest volume enclosing a finite (multi)set of points in \( d\)-dimensional Euclidean space \( \E^d\).

For a set \( P\) we denote by \( ms(P)\) the smallest sphere that contains all points of \( P\). \( ms(P)\) can be degenerate, i.e. \( ms(P)=\emptyset\) if \( P=\emptyset\) and \( ms(P)=\{p\}\) if \( P=\{p\}\).

An inclusion-minimal subset \( S\) of \( P\) with \( ms(S)=ms(P)\) is called a support set, the points in \( S\) are the support points. A support set has size at most \( d+1\), and all its points lie on the boundary of \( ms(P)\). In general, neither the support set nor its size are unique.

The algorithm computes a support set \( S\) which remains fixed until the next insert or clear operation.

Note
  This class is (almost) obsolete. The class `CGAL::Min_sphere_of_spheres_d<Traits>` solves a more general problem and is faster than `Min_sphere_d` even if used only for points as input. Most importantly, `CGAL::Min_sphere_of_spheres_d<Traits>` has a specialized implementation for floating-point arithmetic which ensures correct results in a large number of cases (including highly degenerate ones). In contrast, `Min_sphere_d` is not reliable under floating-point computations. The only advantage of `Min_sphere_d` over `CGAL::Min_sphere_of_spheres_d<Traits>` is that the former can deal with points in homogeneous coordinates, in which case the algorithm is division-free. Thus, `Min_sphere_d` might still be an option in case your input number type cannot (efficiently) divide.

Template Parameters

  Traits | must be a model of the concept `MinSphereAnnulusDTraits` as its template argument.

We provide the models `CGAL::Min_sphere_annulus_d_traits_2`, `CGAL::Min_sphere_annulus_d_traits_3` and `CGAL::Min_sphere_annulus_d_traits_d` for two-, three-, and \( d\)-dimensional points respectively.

See also
  `CGAL::Min_sphere_annulus_d_traits_2<K,ET,NT>`
  `CGAL::Min_sphere_annulus_d_traits_3<K,ET,NT>`
  `CGAL::Min_sphere_annulus_d_traits_d<K,ET,NT>`
  `MinSphereAnnulusDTraits`
  `CGAL::Min_circle_2<Traits>`
  `CGAL::Min_sphere_of_spheres_d<Traits>`
  `CGAL::Min_annulus_d<Traits>`

Implementation

We implement the algorithm of Welzl with move-to-front heuristic [16] for small point sets, combined with a new efficient method for large sets, which is particularly tuned for moderately large dimension ( \( d \leq 20\)) [8]. 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, but substantially less than computing the new smallest enclosing sphere from scratch. The clear operation and the check for validity each take linear time.

Example

File Min_sphere_d/min_sphere_homogeneous_3.cpp

#include <CGAL/Exact_integer.h>
#include <CGAL/Homogeneous.h>
#include <CGAL/Random.h>
#include <CGAL/Min_sphere_annulus_d_traits_3.h>
#include <CGAL/Min_sphere_d.h>
#include <iostream>
#include <cstdlib>
#include <array>
typedef CGAL::Homogeneous<CGAL::Exact_integer> K;
typedef CGAL::Min_sphere_annulus_d_traits_3<K> Traits;
typedef CGAL::Min_sphere_d<Traits> Min_sphere;
typedef K::Point_3 Point;
int
main ()
{
const int n = 10; // number of points
std::array<Point, n> P; // n points
CGAL::Random r; // random number generator
for (int i=0; i<n; ++i) {
P.at(i) = Point(r.get_int(0, 1000),r.get_int(0, 1000), r.get_int(0, 1000), 1 );
}
Min_sphere ms (P.begin(), P.end()); // smallest enclosing sphere
CGAL::IO::set_pretty_mode (std::cout);
std::cout << ms; // output the sphere
return 0;
}
Exact_integer.h
CGAL::Min_sphere_annulus_d_traits_3
The class Min_sphere_annulus_d_traits_3 is a traits class for the -dimensional optimization algorithm...
Definition: Min_sphere_annulus_d_traits_3.h:21
CGAL::Min_sphere_d
An object of the class Min_sphere_d is the unique sphere of smallest volume enclosing a finite (multi...
Definition: Min_sphere_d.h:75
CGAL::Min_sphere_d::Point
unspecified_type Point
typedef to Traits::Point.
Definition: Min_sphere_d.h:94
unspecified_type
CGAL::IO::set_pretty_mode
Mode set_pretty_mode(std::ios &s)
CGAL::Homogeneous

Examples
  Min_sphere_d/min_sphere_homogeneous_3.cpp.

## Related Functions
(Note that these are not member functions.)
std::ostream & | operator<< (std::ostream &os, const Min_sphere_d< Traits > &min_sphere)
| writes `min_sphere` to output stream `os`.
std::istream & | operator>> (std::istream &is, Min_sphere_d< Traits > min_sphere &)
| reads `min_sphere` from input stream `is`.

## Types
typedef unspecified_type | FT
| typedef to `Traits::FT`.
typedef unspecified_type | Point
| typedef to `Traits::Point`.
typedef unspecified_type | Point_iterator
| non-mutable model of the STL concept `BidirectionalIterator` with value type `Point`.
typedef unspecified_type | Support_point_iterator
| non-mutable model of the STL concept `BidirectionalIterator` with value type `Point`.

## Creation
| Min_sphere_d (const Traits &traits=Traits())
| creates a variable of type `Min_sphere_d` and initializes it to \( ms(\emptyset)\).
template<class InputIterator >
| Min_sphere_d (InputIterator first, InputIterator last, const Traits &traits=Traits())
| creates a variable `min_sphere` of type `Min_sphere_d`.
int | number_of_points () const
| returns the number of points of `min_sphere`, i.e. \( |P|\).
int | number_of_support_points () const
| returns the number of support points of `min_sphere`, i.e. \( |S|\).
Point_iterator | points_begin () const
| returns an iterator referring to the first point of `min_sphere`.
Point_iterator | points_end () const
| returns the corresponding past-the-end iterator.
Support_point_iterator | support_points_begin () const
| returns an iterator referring to the first support point of `min_sphere`.
Support_point_iterator | support_points_end () const
| returns the corresponding past-the-end iterator.
int | ambient_dimension () const
| returns the dimension of the points in \( P\).
const Point & | center () const
| returns the center of `min_sphere`.
FT | squared_radius () const
| returns the squared radius of `min_sphere`.

## Predicates
By definition, an empty `Min_sphere_d` has no boundary and no bounded side, i.e. its unbounded side equals the whole space \( \E^d\).
Bounded_side | bounded_side (const Point &p) const
| returns `CGAL::ON_BOUNDED_SIDE`, `CGAL::ON_BOUNDARY`, or `CGAL::ON_UNBOUNDED_SIDE` iff `p` lies properly inside, on the boundary, or properly outside of `min_sphere`, resp.
bool | has_on_bounded_side (const Point &p) const
| returns `true`, iff `p` lies properly inside `min_sphere`.
bool | has_on_boundary (const Point &p) const
| returns `true`, iff `p` lies on the boundary of `min_sphere`.
bool | has_on_unbounded_side (const Point &p) const
| returns `true`, iff `p` lies properly outside of `min_sphere`.
bool | is_empty () const
| returns `true`, iff `min_sphere` is empty (this implies degeneracy).
bool | is_degenerate () const
| returns `true`, iff `min_sphere` is degenerate, i.e. if `min_sphere` is empty or equal to a single point, equivalently if the number of support points is less than 2.

## Modifiers
void | clear ()
| resets `min_sphere` to \( ms(\emptyset)\).
template<class InputIterator >
void | set (InputIterator first, InputIterator last)
| sets `min_sphere` to the \( ms(P)\), where \( P\) is the set of points in the range [`first`,`last`).
void | insert (const Point &p)
| inserts `p` into `min_sphere`.
template<class InputIterator >
void | insert (InputIterator first, InputIterator last)
| inserts the points in the range [`first`,`last`) into `min_sphere` and recomputes the smallest enclosing sphere, by calling `insert` for all points in the range.

## Validity Check
An object `min_sphere` is valid, iff `min_sphere` contains all points of its defining set \( P\), `min_sphere` is the smallest sphere containing its support set \( S\), and \( S\) is minimal, i.e. no support point is redundant. Note Under inexact arithmetic, the result of the validation is not reliable, because the checker itself can suffer from numerical problems.
bool | is_valid (bool verbose=false, int level=0) const
| returns `true`, iff `min_sphere` is valid.

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

## Member Typedef Documentation

## ◆ Point_iterator

template<typename Traits >

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

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

Used to access the points used to build the smallest enclosing sphere.

## ◆ Support_point_iterator

template<typename Traits >

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

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

Used to access the support points defining the smallest enclosing sphere.

## Constructor & Destructor Documentation

## ◆ Min_sphere_d() [1/2]

template<typename Traits >

CGAL::Min_sphere_d< Traits >::Min_sphere_d | ( | const Traits & | traits = `Traits()` | ) |

creates a variable of type `Min_sphere_d` and initializes it to \( ms(\emptyset)\).

If the traits parameter is not supplied, the class `Traits` must provide a default constructor.

## ◆ Min_sphere_d() [2/2]

template<typename Traits >
template<class InputIterator >

CGAL::Min_sphere_d< Traits >::Min_sphere_d | ( | InputIterator | first,
|  | InputIterator | last,
|  | const Traits & | traits = `Traits()`
| ) |  |

creates a variable `min_sphere` of type `Min_sphere_d`.

It is initialized to \( ms(P)\) with \( P\) being the set of points in the range [`first`,`last`).

Template Parameters

  InputIterator | is a model of `InputIterator` with `Point` as value type. If the traits parameter is not supplied, the class `Traits` must provide a default constructor.

Precondition
  All points have the same dimension.

## Member Function Documentation

## ◆ ambient_dimension()

template<typename Traits >

int CGAL::Min_sphere_d< Traits >::ambient_dimension | ( |  | ) | const

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

If `min_sphere` is empty, the ambient dimension is \( -1\).

## ◆ bounded_side()

template<typename Traits >

Bounded_side CGAL::Min_sphere_d< Traits >::bounded_side | ( | const Point & | p | ) | const

returns `CGAL::ON_BOUNDED_SIDE`, `CGAL::ON_BOUNDARY`, or `CGAL::ON_UNBOUNDED_SIDE` iff `p` lies properly inside, on the boundary, or properly outside of `min_sphere`, resp.

Precondition
  If `min_sphere` is not empty, the dimension of \( p\) equals `ambient_dimension()`.

## ◆ center()

template<typename Traits >

const Point & CGAL::Min_sphere_d< Traits >::center | ( |  | ) | const

returns the center of `min_sphere`.

Precondition
  `min_sphere` is not empty.

## ◆ has_on_boundary()

template<typename Traits >

bool CGAL::Min_sphere_d< Traits >::has_on_boundary | ( | const Point & | p | ) | const

returns `true`, iff `p` lies on the boundary of `min_sphere`.

Precondition
  if `min_sphere` is not empty, the dimension of \( p\) equals `ambient_dimension()`.

## ◆ has_on_bounded_side()

template<typename Traits >

bool CGAL::Min_sphere_d< Traits >::has_on_bounded_side | ( | const Point & | p | ) | const

returns `true`, iff `p` lies properly inside `min_sphere`.

Precondition
  If `min_sphere` is not empty, the dimension of \( p\) equals `ambient_dimension()`.

## ◆ has_on_unbounded_side()

template<typename Traits >

bool CGAL::Min_sphere_d< Traits >::has_on_unbounded_side | ( | const Point & | p | ) | const

returns `true`, iff `p` lies properly outside of `min_sphere`.

Precondition
  If `min_sphere` is not empty, the dimension of \( p\) equals `ambient_dimension()`.

## ◆ insert() [1/2]

template<typename Traits >

void CGAL::Min_sphere_d< Traits >::insert | ( | const Point & | p | ) |

inserts `p` into `min_sphere`.

If `p` lies inside the current sphere, this is a constant-time operation, otherwise it might take longer, but usually substantially less than recomputing the smallest enclosing sphere from scratch.

Precondition
  The dimension of `p` equals `ambient_dimension()` if `min_sphere` is not empty.

## ◆ insert() [2/2]

template<typename Traits >
template<class InputIterator >

void CGAL::Min_sphere_d< Traits >::insert | ( | InputIterator | first,
|  | InputIterator | last
| ) |  |

inserts the points in the range [`first`,`last`) into `min_sphere` and recomputes the smallest enclosing sphere, by calling `insert` for all points in the range.

Template Parameters

  InputIterator | is a model of `InputIterator` with `Point` as value type.

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

## ◆ is_valid()

template<typename Traits >

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

returns `true`, iff `min_sphere` 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.

## ◆ set()

template<typename Traits >
template<class InputIterator >

void CGAL::Min_sphere_d< Traits >::set | ( | InputIterator | first,
|  | InputIterator | last
| ) |  |

sets `min_sphere` to the \( ms(P)\), where \( P\) is the set of points in the range [`first`,`last`).

Template Parameters

  InputIterator | is a model of `InputIterator` with `Point` as value type.

Precondition
  All points have the same dimension.

## ◆ squared_radius()

template<typename Traits >

FT CGAL::Min_sphere_d< Traits >::squared_radius | ( |  | ) | const

returns the squared radius of `min_sphere`.

Precondition
  `min_sphere` is not empty.

## Friends And Related Function Documentation

## ◆ operator<<()

template<typename Traits >

std::ostream & operator<< | ( | std::ostream & | os,
|  | const Min_sphere_d< Traits > & | min_sphere
| ) |  |
| related

writes `min_sphere` to output stream `os`.

An overload of `operator<<` must be defined for `Point`.

## ◆ operator>>()

template<typename Traits >

std::istream & operator>> | ( | std::istream & | is,
|  | Min_sphere_d< Traits > min_sphere & |
| ) |  |
| related

reads `min_sphere` from input stream `is`.

An overload of `operator>>` must be defined for `Point`