GitHub-Proxy/eigen
1
0
Fork 0
mirror of https://gitlab.com/libeigen/eigen.git synced 2025-06-20 11:56:17 +08:00
Code Issues Packages Projects Releases Wiki Activity

bug #999: clarify that behavior of empty AlignedBoxes is undefined, and further improvements in documentation

Browse Source
This commit is contained in:
Christoph Hertzberg 2015-04-30 19:30:36 +02:00
parent da2baf685d
commit 173b34e9ab
2 changed files with 54 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
Eigen/src/Geometry/AlignedBox.h
View File

@ -19,10 +19,12 @@ namespace Eigen {
* *
* \brief An axis aligned box * \brief An axis aligned box
* *
* \param _Scalar the type of the scalar coefficients * \tparam _Scalar the type of the scalar coefficients
* \param _AmbientDim the dimension of the ambient space, can be a compile time value or Dynamic. * \tparam _AmbientDim the dimension of the ambient space, can be a compile time value or Dynamic.
* *
* This class represents an axis aligned box as a pair of the minimal and maximal corners. * This class represents an axis aligned box as a pair of the minimal and maximal corners.
* \warning The result of most methods is undefined when applied to an empty box. You can check for empty boxes using isEmpty().
* \sa alignedboxtypedefs
*/ */
template <typename _Scalar, int _AmbientDim> template <typename _Scalar, int _AmbientDim>
class AlignedBox class AlignedBox
@ -40,18 +42,21 @@ EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF_VECTORIZABLE_FIXED_SIZE(_Scalar,_AmbientDim)
/** Define constants to name the corners of a 1D, 2D or 3D axis aligned bounding box */ /** Define constants to name the corners of a 1D, 2D or 3D axis aligned bounding box */
enum CornerType enum CornerType
{ {
/** 1D names */ /** 1D names @{ */
Min=0, Max=1, Min=0, Max=1,
/** @} */
/** Added names for 2D */ /** Identifier for 2D corner @{ */
BottomLeft=0, BottomRight=1, BottomLeft=0, BottomRight=1,
TopLeft=2, TopRight=3, TopLeft=2, TopRight=3,
/** @} */
/** Added names for 3D */ /** Identifier for 3D corner @{ */
BottomLeftFloor=0, BottomRightFloor=1, BottomLeftFloor=0, BottomRightFloor=1,
TopLeftFloor=2, TopRightFloor=3, TopLeftFloor=2, TopRightFloor=3,
BottomLeftCeil=4, BottomRightCeil=5, BottomLeftCeil=4, BottomRightCeil=5,
TopLeftCeil=6, TopRightCeil=7 TopLeftCeil=6, TopRightCeil=7
/** @} */
}; };
@ -63,34 +68,33 @@ EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF_VECTORIZABLE_FIXED_SIZE(_Scalar,_AmbientDim)
inline explicit AlignedBox(Index _dim) : m_min(_dim), m_max(_dim) inline explicit AlignedBox(Index _dim) : m_min(_dim), m_max(_dim)
{ setEmpty(); } { setEmpty(); }
/** Constructs a box with extremities \a _min and \a _max. */ /** Constructs a box with extremities \a _min and \a _max.
* \warning If either component of \a _min is larger than the same component of \a _max, the constructed box is empty. */
template<typename OtherVectorType1, typename OtherVectorType2> template<typename OtherVectorType1, typename OtherVectorType2>
inline AlignedBox(const OtherVectorType1& _min, const OtherVectorType2& _max) : m_min(_min), m_max(_max) {} inline AlignedBox(const OtherVectorType1& _min, const OtherVectorType2& _max) : m_min(_min), m_max(_max) {}
/** Constructs a box containing a single point \a p. */ /** Constructs a box containing a single point \a p. */
template<typename Derived> template<typename Derived>
inline explicit AlignedBox(const MatrixBase<Derived>& a_p) inline explicit AlignedBox(const MatrixBase<Derived>& p) : m_min(p), m_max(m_min)
{ { }
typename internal::nested_eval<Derived,2>::type p(a_p.derived());
m_min = p;
m_max = p;
}
~AlignedBox() {} ~AlignedBox() {}
/** \returns the dimension in which the box holds */ /** \returns the dimension in which the box holds */
inline Index dim() const { return AmbientDimAtCompileTime==Dynamic ? m_min.size() : Index(AmbientDimAtCompileTime); } inline Index dim() const { return AmbientDimAtCompileTime==Dynamic ? m_min.size() : Index(AmbientDimAtCompileTime); }
/** \deprecated use isEmpty */ /** \deprecated use isEmpty() */
inline bool isNull() const { return isEmpty(); } inline bool isNull() const { return isEmpty(); }
/** \deprecated use setEmpty */ /** \deprecated use setEmpty() */
inline void setNull() { setEmpty(); } inline void setNull() { setEmpty(); }
/** \returns true if the box is empty. */ /** \returns true if the box is empty.
* \sa setEmpty */
inline bool isEmpty() const { return (m_min.array() > m_max.array()).any(); } inline bool isEmpty() const { return (m_min.array() > m_max.array()).any(); }
/** Makes \c *this an empty box. */ /** Makes \c *this an empty box.
* \sa isEmpty */
inline void setEmpty() inline void setEmpty()
{ {
m_min.setConstant( ScalarTraits::highest() ); m_min.setConstant( ScalarTraits::highest() );
@ -175,31 +179,34 @@ EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF_VECTORIZABLE_FIXED_SIZE(_Scalar,_AmbientDim)
/** \returns true if the point \a p is inside the box \c *this. */ /** \returns true if the point \a p is inside the box \c *this. */
template<typename Derived> template<typename Derived>
inline bool contains(const MatrixBase<Derived>& a_p) const inline bool contains(const MatrixBase<Derived>& p) const
{ {
typename internal::nested<Derived,2>::type p(a_p.derived()); typename internal::nested<Derived,2>::type p_n(p.derived());
return (m_min.array()<=p.array()).all() && (p.array()<=m_max.array()).all(); return (m_min.array()<=p_n.array()).all() && (p_n.array()<=m_max.array()).all();
} }
/** \returns true if the box \a b is entirely inside the box \c *this. */ /** \returns true if the box \a b is entirely inside the box \c *this. */
inline bool contains(const AlignedBox& b) const inline bool contains(const AlignedBox& b) const
{ return (m_min.array()<=(b.min)().array()).all() && ((b.max)().array()<=m_max.array()).all(); } { return (m_min.array()<=(b.min)().array()).all() && ((b.max)().array()<=m_max.array()).all(); }
/** \returns true if the box \a b is intersecting the box \c *this. */ /** \returns true if the box \a b is intersecting the box \c *this.
* \sa intersection, clamp */
inline bool intersects(const AlignedBox& b) const inline bool intersects(const AlignedBox& b) const
{ return (m_min.array()<=(b.max)().array()).all() && ((b.min)().array()<=m_max.array()).all(); } { return (m_min.array()<=(b.max)().array()).all() && ((b.min)().array()<=m_max.array()).all(); }
/** Extends \c *this such that it contains the point \a p and returns a reference to \c *this. */ /** Extends \c *this such that it contains the point \a p and returns a reference to \c *this.
* \sa extend(const AlignedBox&) */
template<typename Derived> template<typename Derived>
inline AlignedBox& extend(const MatrixBase<Derived>& a_p) inline AlignedBox& extend(const MatrixBase<Derived>& p)
{ {
typename internal::nested<Derived,2>::type p(a_p.derived()); typename internal::nested<Derived,2>::type p_n(p.derived());
m_min = m_min.cwiseMin(p); m_min = m_min.cwiseMin(p_n);
m_max = m_max.cwiseMax(p); m_max = m_max.cwiseMax(p_n);
return *this; return *this;
} }
/** Extends \c *this such that it contains the box \a b and returns a reference to \c *this. */ /** Extends \c *this such that it contains the box \a b and returns a reference to \c *this.
* \sa merged, extend(const MatrixBase&) */
inline AlignedBox& extend(const AlignedBox& b) inline AlignedBox& extend(const AlignedBox& b)
{ {
m_min = m_min.cwiseMin(b.m_min); m_min = m_min.cwiseMin(b.m_min);
@ -207,7 +214,9 @@ EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF_VECTORIZABLE_FIXED_SIZE(_Scalar,_AmbientDim)
return *this; return *this;
} }
/** Clamps \c *this by the box \a b and returns a reference to \c *this. */ /** Clamps \c *this by the box \a b and returns a reference to \c *this.
* \note If the boxes don't intersect, the resulting box is empty.
* \sa intersection(), intersects() */
inline AlignedBox& clamp(const AlignedBox& b) inline AlignedBox& clamp(const AlignedBox& b)
{ {
m_min = m_min.cwiseMax(b.m_min); m_min = m_min.cwiseMax(b.m_min);
@ -215,11 +224,15 @@ EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF_VECTORIZABLE_FIXED_SIZE(_Scalar,_AmbientDim)
return *this; return *this;
} }
/** Returns an AlignedBox that is the intersection of \a b and \c *this */ /** Returns an AlignedBox that is the intersection of \a b and \c *this
* \note If the boxes don't intersect, the resulting box is empty.
* \sa intersects(), clamp, contains() */
inline AlignedBox intersection(const AlignedBox& b) const inline AlignedBox intersection(const AlignedBox& b) const
{return AlignedBox(m_min.cwiseMax(b.m_min), m_max.cwiseMin(b.m_max)); } {return AlignedBox(m_min.cwiseMax(b.m_min), m_max.cwiseMin(b.m_max)); }
/** Returns an AlignedBox that is the union of \a b and \c *this */ /** Returns an AlignedBox that is the union of \a b and \c *this.
* \note Merging with an empty box may result in a box bigger than \c *this.
* \sa extend(const AlignedBox&) */
inline AlignedBox merged(const AlignedBox& b) const inline AlignedBox merged(const AlignedBox& b) const
{ return AlignedBox(m_min.cwiseMin(b.m_min), m_max.cwiseMax(b.m_max)); } { return AlignedBox(m_min.cwiseMin(b.m_min), m_max.cwiseMax(b.m_max)); }
@ -235,20 +248,20 @@ EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF_VECTORIZABLE_FIXED_SIZE(_Scalar,_AmbientDim)
/** \returns the squared distance between the point \a p and the box \c *this, /** \returns the squared distance between the point \a p and the box \c *this,
* and zero if \a p is inside the box. * and zero if \a p is inside the box.
* \sa exteriorDistance() * \sa exteriorDistance(const MatrixBase&), squaredExteriorDistance(const AlignedBox&)
*/ */
template<typename Derived> template<typename Derived>
inline Scalar squaredExteriorDistance(const MatrixBase<Derived>& a_p) const; inline Scalar squaredExteriorDistance(const MatrixBase<Derived>& p) const;
/** \returns the squared distance between the boxes \a b and \c *this, /** \returns the squared distance between the boxes \a b and \c *this,
* and zero if the boxes intersect. * and zero if the boxes intersect.
* \sa exteriorDistance() * \sa exteriorDistance(const AlignedBox&), squaredExteriorDistance(const MatrixBase&)
*/ */
inline Scalar squaredExteriorDistance(const AlignedBox& b) const; inline Scalar squaredExteriorDistance(const AlignedBox& b) const;
/** \returns the distance between the point \a p and the box \c *this, /** \returns the distance between the point \a p and the box \c *this,
* and zero if \a p is inside the box. * and zero if \a p is inside the box.
* \sa squaredExteriorDistance() * \sa squaredExteriorDistance(const MatrixBase&), exteriorDistance(const AlignedBox&)
*/ */
template<typename Derived> template<typename Derived>
inline NonInteger exteriorDistance(const MatrixBase<Derived>& p) const inline NonInteger exteriorDistance(const MatrixBase<Derived>& p) const
@ -256,7 +269,7 @@ EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF_VECTORIZABLE_FIXED_SIZE(_Scalar,_AmbientDim)
/** \returns the distance between the boxes \a b and \c *this, /** \returns the distance between the boxes \a b and \c *this,
* and zero if the boxes intersect. * and zero if the boxes intersect.
* \sa squaredExteriorDistance() * \sa squaredExteriorDistance(const AlignedBox&), exteriorDistance(const MatrixBase&)
*/ */
inline NonInteger exteriorDistance(const AlignedBox& b) const inline NonInteger exteriorDistance(const AlignedBox& b) const
{ using std::sqrt; return sqrt(NonInteger(squaredExteriorDistance(b))); } { using std::sqrt; return sqrt(NonInteger(squaredExteriorDistance(b))); }

12
doc/Doxyfile.in
View File

@ -317,7 +317,7 @@ IDL_PROPERTY_SUPPORT = YES
# member in the group (if any) for the other members of the group. By default # member in the group (if any) for the other members of the group. By default
# all members of a group must be documented explicitly. # all members of a group must be documented explicitly.
DISTRIBUTE_GROUP_DOC = NO DISTRIBUTE_GROUP_DOC = YES
# Set the SUBGROUPING tag to YES (the default) to allow class member groups of # Set the SUBGROUPING tag to YES (the default) to allow class member groups of
# the same type (for instance a group of public functions) to be put as a # the same type (for instance a group of public functions) to be put as a
@ -367,7 +367,7 @@ TYPEDEF_HIDES_STRUCT = NO
# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, # 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0,
# corresponding to a cache size of 2^16 = 65536 symbols. # corresponding to a cache size of 2^16 = 65536 symbols.
SYMBOL_CACHE_SIZE = 0 # SYMBOL_CACHE_SIZE = 0
# Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be # Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be
# set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given # set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given
@ -564,7 +564,7 @@ GENERATE_BUGLIST = ${EIGEN_DOXY_INTERNAL}
# disable (NO) the deprecated list. This list is created by putting # disable (NO) the deprecated list. This list is created by putting
# \deprecated commands in the documentation. # \deprecated commands in the documentation.
GENERATE_DEPRECATEDLIST= ${EIGEN_DOXY_INTERNAL} GENERATE_DEPRECATEDLIST= YES
# The ENABLED_SECTIONS tag can be used to enable conditional # The ENABLED_SECTIONS tag can be used to enable conditional
# documentation sections, marked by \if sectionname ... \endif. # documentation sections, marked by \if sectionname ... \endif.
@ -1467,13 +1467,13 @@ XML_OUTPUT = xml
# which can be used by a validating XML parser to check the # which can be used by a validating XML parser to check the
# syntax of the XML files. # syntax of the XML files.
XML_SCHEMA = # XML_SCHEMA =
# The XML_DTD tag can be used to specify an XML DTD, # The XML_DTD tag can be used to specify an XML DTD,
# which can be used by a validating XML parser to check the # which can be used by a validating XML parser to check the
# syntax of the XML files. # syntax of the XML files.
XML_DTD = # XML_DTD =
# If the XML_PROGRAMLISTING tag is set to YES Doxygen will # If the XML_PROGRAMLISTING tag is set to YES Doxygen will
# dump the program listings (including syntax highlighting # dump the program listings (including syntax highlighting
@ -1700,7 +1700,7 @@ DOT_NUM_THREADS = 0
# the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the # the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the
# directory containing the font. # directory containing the font.
DOT_FONTNAME = FreeSans DOT_FONTNAME =
# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. # The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs.
# The default size is 10pt. # The default size is 10pt.