diff --git a/AABB_tree/doc/AABB_tree/Concepts/AABBPrimitive.h b/AABB_tree/doc/AABB_tree/Concepts/AABBPrimitive.h index bd92056f409..43ae5fd38b7 100644 --- a/AABB_tree/doc/AABB_tree/Concepts/AABBPrimitive.h +++ b/AABB_tree/doc/AABB_tree/Concepts/AABBPrimitive.h @@ -6,14 +6,17 @@ The concept `AABBPrimitive` describes the requirements for the primitives stored in the AABB tree data structure. The concept encapsulates a type for the input datum (a geometric object) and an identifier (id) type through which those primitives are referred to. The concept `AABBPrimitive` also refines the concepts DefaultConstructible and Assignable. \sa `CGAL::AABB_tree` +\sa `AABBPrimitiveWithSharedData` ### Example ### The `Primitive` type can be, e.g., a wrapper around a `Handle`. Assume for instance that the input objects are the triangle faces of a mesh stored as a `CGAL::Polyhedron_3`. The `Datum` would be a `Triangle_3` and the `Id` would be a polyhedron `Face_handle`. Method `datum()` can return either a `Triangle_3` constructed on the fly from the face handle or a `Triangle_3` stored internally. This provides a way for the user to trade memory for efficiency. -\cgalHasModel `CGAL::AABB_polyhedron_triangle_primitive` -\cgalHasModel `CGAL::AABB_polyhedron_segment_primitive` - +\cgalHasModel `CGAL::AABB_primitive` +\cgalHasModel `CGAL::AABB_segment_primitive` +\cgalHasModel `CGAL::AABB_triangle_primitive` +\cgalHasModel `CGAL::AABB_HalfedgeGraph_segment_primitive` +\cgalHasModel `CGAL::AABB_FaceGraph_triangle_primitive` */ class AABBPrimitive { @@ -32,6 +35,16 @@ Type of input datum. */ typedef unspecified_type Datum; +/*! +Point reference type returned by the function `point()`. It is convertible to the type `Point`. + */ +typedef unspecified_type Point_reference; + +/*! +Datum reference type returned by the function `datum()`. It is convertible to the type `Datum`. +*/ +typedef unspecified_type Datum_reference; + /*! Type of identifiers through which the input objects are referred to. It must be a model of the concepts DefaultConstructible and Assignable. */ @@ -45,7 +58,7 @@ typedef unspecified_type Id; /*! Returns the datum (geometric object) represented by the primitive. */ -Datum datum(); +Datum_reference datum(); /*! Returns the corresponding identifier. This identifier is only used as a reference for the objects in the output of the `AABB_tree` methods. @@ -55,7 +68,7 @@ Id id(); /*! Returns a 3D point located on the geometric object represented by the primitive. This function is used to sort the primitives during the AABB tree construction as well as to construct the search KD-tree internal to the AABB tree used to accelerate distance queries. */ -Point reference_point(); +Point_reference reference_point(); /// @} diff --git a/AABB_tree/doc/AABB_tree/Concepts/AABBPrimitiveWithSharedData.h b/AABB_tree/doc/AABB_tree/Concepts/AABBPrimitiveWithSharedData.h new file mode 100644 index 00000000000..ad0ff9772db --- /dev/null +++ b/AABB_tree/doc/AABB_tree/Concepts/AABBPrimitiveWithSharedData.h @@ -0,0 +1,85 @@ +/*! +\ingroup PkgAABB_treeConcepts +\cgalConcept + +The concept `AABBPrimitiveWithSharedData` describes the requirements for the primitives +stored in the AABB tree data structure. The concept encapsulates a type for the input +datum (a geometric object) and an identifier (id) type through which those primitives +are referred to. The concept `AABBPrimitiveWithSharedData` also refines the concepts +`DefaultConstructible` and `Assignable`. +The concept is similar to `AABBPrimitive` except that some data stored outside +of the primitives are required to access the datum and the reference point. + +\sa `CGAL::AABB_tree` +\sa `AABBPrimitive` + +### Example ### + +The `Primitive` type can be a wrapper around an integer that refers to the position +of an object in a vector. Assume for instance that the input objects are some triangles. +The `Datum` would be a `Triangle_3` and the `Id` a `std::size_t`. The shared data here is a +`std::vector`. +The method `datum(const Shared_data&)` then returns a triangle from the vector. + +\cgalHasModel `CGAL::AABB_primitive` +\cgalHasModel `CGAL::AABB_HalfedgeGraph_segment_primitive` +\cgalHasModel `CGAL::AABB_FaceGraph_triangle_primitive` +*/ + +class AABBPrimitiveWithSharedData { +public: + +/// \name Types +/// @{ +/*! +3D point type. +*/ +typedef unspecified_type Point; + +/*! +Type of input datum. +*/ +typedef unspecified_type Datum; + +/*! +Point reference type returned by the function `point(const Shared_data&)`. It is convertible to the type `Point`. + */ +typedef unspecified_type Point_reference; + +/*! +Datum reference type returned by the function `datum(const Shared_data&)`. It is convertible to the type `Datum`. +*/ +typedef unspecified_type Datum_reference; + +/*! +Type of identifiers through which the input objects are referred to. It must be a model of the concepts DefaultConstructible and Assignable. +*/ +typedef unspecified_type Id; +/// @} + +/// \name Operations +/// @{ +/*! +Returns the datum (geometric object) represented by the primitive. +*/ +Datum_reference datum(const Shared_data& data); + +/*! +Returns the corresponding identifier. This identifier is only used as a reference for the objects in the output of the `AABB_tree` methods. +*/ +Id id(); + +/*! +Returns a 3D point located on the geometric object represented by the primitive. This function is used to sort the primitives during the AABB tree construction as well as to construct the search KD-tree internal to the AABB tree used to accelerate distance queries. +*/ +Point_reference reference_point(const Shared_data& data); + +/*! +A static function responsible for the creation of the shared data of a primitive. +The parameter pack is such that there exists a constructor `template AABBPrimitiveWithSharedData (T1,T...)`. +*/ +template +static Shared_data construct_shared_data(T ... t); +/// @} + +}; diff --git a/AABB_tree/doc/AABB_tree/Concepts/AABBTraits.h b/AABB_tree/doc/AABB_tree/Concepts/AABBTraits.h index e269418ba85..b2a37c88fe4 100644 --- a/AABB_tree/doc/AABB_tree/Concepts/AABBTraits.h +++ b/AABB_tree/doc/AABB_tree/Concepts/AABBTraits.h @@ -3,13 +3,13 @@ \ingroup PkgAABB_treeConcepts \cgalConcept -The concept `AABBTraits` provides the geometric primitive types and methods for the class `CGAL::AABB_tree`. +The concept `AABBTraits` provides the geometric primitive types and methods for the class `CGAL::AABB_tree`. \cgalHasModel `CGAL::AABB_traits` -\sa `CGAL::AABB_traits` -\sa `CGAL::AABB_tree` -\sa `AABBPrimitive` +\sa `CGAL::AABB_traits` +\sa `CGAL::AABB_tree` +\sa `AABBPrimitive` */ class AABBTraits { @@ -30,7 +30,7 @@ typedef unspecified_type Point_3; /*! Type of primitive. -Must be a model of the concept `AABBPrimitive`. +Must be a model of the concepts `AABBPrimitive` or `AABBPrimitiveWithSharedData`. */ typedef unspecified_type Primitive; @@ -201,8 +201,30 @@ Returns the squared distance functor. */ Squared_distance squared_distance_object(); +/// @} + +/// \name Primitive with Shared Data +/// In addition, if `Primitive` is a model of the concept `AABBPrimitiveWithSharedData`, +/// the following functions are part of the concept: +/// @{ + +/*! +the signature of that function must be the same as the static function `Primitive::construct_shared_data`. +The type `Primitive` expects that the data constructed by a call to `Primitive::construct_shared_data(t...)` +is the one given back when accessing the reference point and the datum of a primitive. +*/ +template +void set_shared_data(T ... t); +{} + +/*! +Returns the shared data of the primitive constructed after a call to `set_shared_data`. +If no call to `set_shared_data` has been done, `Primitive::Shared_data()` is returned. +*/ +const Primitive::Shared_data& shared_data() const; /// @} + }; /* end AABBTraits */ diff --git a/AABB_tree/doc/AABB_tree/PackageDescription.txt b/AABB_tree/doc/AABB_tree/PackageDescription.txt index 724e1277519..e3deffb0050 100644 --- a/AABB_tree/doc/AABB_tree/PackageDescription.txt +++ b/AABB_tree/doc/AABB_tree/PackageDescription.txt @@ -24,6 +24,7 @@ ## Concepts ## - `AABBPrimitive` +- `AABBPrimitiveWithSharedData` - `AABBTraits` - `AABBGeomTraits` @@ -31,4 +32,10 @@ - `CGAL::AABB_traits` - `CGAL::AABB_tree` +## Primitives ## +- `CGAL::AABB_triangle_primitive` +- `CGAL::AABB_segment_primitive` +- `CGAL::AABB_primitive` +- `CGAL::AABB_HalfedgeGraph_segment_primitive` +- `CGAL::AABB_FaceGraph_triangle_primitive` */ diff --git a/AABB_tree/doc/AABB_tree/examples.txt b/AABB_tree/doc/AABB_tree/examples.txt index 9dca501c3b2..b143f69c39c 100644 --- a/AABB_tree/doc/AABB_tree/examples.txt +++ b/AABB_tree/doc/AABB_tree/examples.txt @@ -9,4 +9,5 @@ \example AABB_tree/AABB_polyhedron_facet_intersection_example.cpp \example AABB_tree/AABB_segment_3_example.cpp \example AABB_tree/AABB_triangle_3_example.cpp +\example AABB_tree/AABB_HalfedgeGraph_edge_example.cpp */ diff --git a/AABB_tree/doc_tex/AABB_tree_ref/AABB_polyhedron_segment_primitive.tex b/AABB_tree/doc_tex/AABB_tree_ref/AABB_polyhedron_segment_primitive.tex index d9678cb54d3..5746a4e090f 100644 --- a/AABB_tree/doc_tex/AABB_tree_ref/AABB_polyhedron_segment_primitive.tex +++ b/AABB_tree/doc_tex/AABB_tree_ref/AABB_polyhedron_segment_primitive.tex @@ -17,7 +17,7 @@ %% \ccHtmlCrossLink{} %% add further rules for cross referencing links %% \ccHtmlIndexC[class]{} %% add further index entries -This class is deprecated since \cgal\ 4.2, the class \ccc{CGAL::AABB_HalfedgeGraph_segment_primitive} should be used instead. +This class is deprecated since \cgal\ 4.3, the class \ccc{CGAL::AABB_HalfedgeGraph_segment_primitive} should be used instead. \begin{ccDeprecated} diff --git a/AABB_tree/doc_tex/AABB_tree_ref/AABB_polyhedron_triangle_primitive.tex b/AABB_tree/doc_tex/AABB_tree_ref/AABB_polyhedron_triangle_primitive.tex index ae1b42fe9c7..a2a7314420e 100644 --- a/AABB_tree/doc_tex/AABB_tree_ref/AABB_polyhedron_triangle_primitive.tex +++ b/AABB_tree/doc_tex/AABB_tree_ref/AABB_polyhedron_triangle_primitive.tex @@ -18,7 +18,7 @@ %% \ccHtmlCrossLink{} %% add further rules for cross referencing links %% \ccHtmlIndexC[class]{} %% add further index entries -This class is deprecated since \cgal\ 4.2, the class \ccc{CGAL::AABB_FaceGraph_triangle_primitive} should be used instead. +This class is deprecated since \cgal\ 4.3, the class \ccc{CGAL::AABB_FaceGraph_triangle_primitive} should be used instead. \begin{ccDeprecated} \ccDefinition diff --git a/AABB_tree/include/CGAL/AABB_FaceGraph_triangle_primitive.h b/AABB_tree/include/CGAL/AABB_FaceGraph_triangle_primitive.h index bc1e18984dd..98f419cf8e4 100644 --- a/AABB_tree/include/CGAL/AABB_FaceGraph_triangle_primitive.h +++ b/AABB_tree/include/CGAL/AABB_FaceGraph_triangle_primitive.h @@ -18,10 +18,6 @@ // // Author(s) : Sebastien Loriot // -//****************************************************************************** -// File Description : -// -//****************************************************************************** #ifndef CGAL_AABB_FACEGRAPH_TRIANGLE_PRIMITIVE_H #define CGAL_AABB_FACEGRAPH_TRIANGLE_PRIMITIVE_H @@ -32,41 +28,101 @@ namespace CGAL { - +/*! + * \ingroup PkgAABB_tree + * Primitive type for a facet of a polyhedral surface. + * If `OneFaceGraphPerTree` is `CGAL::Tag_false`, the class is a model of the concept `AABBPrimitive`. + * If `OneFaceGraphPerTree` is `CGAL::Tag_true`, the class is a model of the concept `AABBPrimitiveWithSharedData`. + * It wraps a `face_descriptor` of a class model of `FaceGraph` to a 3D triangle. + * The class model of `FaceGraph` from which the primitive is built should not be deleted + * while the AABB tree holding the primitive is in use. + * + *\tparam FaceGraph is a model of the face graph concept. + *\tparam OneFaceGraphPerTree is either `CGAL::Tag_true` or `CGAL::Tag_false`. In the former case, + * we guarantee that all the primitives will be from a common `FaceGraph` and some data + * will be factorized so that the size of the primitive is reduced. In the latter case, + * the primitives can be from different graphs and extra storage is required in the primitives. + * The default is `CGAL::Tag_true`. + *\tparam cache_datum is either `CGAL::Tag_true` or `CGAL::Tag_false`. In the former case, the datum is stored + * in the primitive, while in the latter it is constructed on the fly to reduce the memory footprint. + * The default is `CGAL::Tag_false` (datum is not stored). + *\sa `AABBPrimitive` + *\sa `AABB_primitive` + *\sa `AABB_HalfedgeGraph_segment_primitive` + */ template < class FaceGraph, class OneFaceGraphPerTree=Tag_true, class cache_datum=Tag_false, class Id_=typename FaceGraph::Face_handle //this one should be autodetected using face_descriptor > - -class AABB_FaceGraph_triangle_primitive : public AABB_primitive< Id_, - Triangle_from_facet_handle_property_map, - One_point_from_facet_handle_property_map, - OneFaceGraphPerTree, - cache_datum > +class AABB_FaceGraph_triangle_primitive +#ifndef DOXYGEN_RUNNING +: public AABB_primitive< Id_, + Triangle_from_facet_handle_property_map, + One_point_from_facet_handle_property_map, + OneFaceGraphPerTree, + cache_datum > +#endif { typedef Triangle_from_facet_handle_property_map Triangle_property_map; typedef One_point_from_facet_handle_property_map Point_property_map; - + typedef AABB_primitive< Id_, Triangle_property_map, Point_property_map, Tag_true, cache_datum > Base; - -public: - // constructors - AABB_FaceGraph_triangle_primitive(Id_ it) : Base(it){} - template - AABB_FaceGraph_triangle_primitive(Iterator it) : Base( it->second, - Triangle_property_map((it->first)), - Point_property_map((it->first)) ){} - static typename Base::Shared_data construct_shared_data() {return typename Base::Shared_data();} +public: + #ifdef DOXYGEN_RUNNING + /// \name Types + /// @{ + /*! + The point type. + */ + typedef boost::property_traits< boost::property_map< FaceGraph, vertex_point_t>::type >::value_type Point; + /*! + Geometric data type. + */ + typedef Kernel_traits::Kernel::Triangle_3 Datum; + /*! + Id type. + */ + typedef boost::graph_traits::face_descriptor Id; + /// @} + #endif + + // constructors + /*! + \tparam Iterator an input iterator with `Id` as value type. + Constructs a primitive. + */ + template + AABB_FaceGraph_triangle_primitive(Iterator it, const FaceGraph& graph) + : Base( Id_(*it), + Triangle_property_map(&graph), + Point_property_map(&graph) ){} + + //for backward-compatibility with AABB_polyhedron_triangle_primitive + AABB_FaceGraph_triangle_primitive(Id_ id) + : Base( id, + Triangle_property_map(NULL), + Point_property_map(NULL) ){} + + static typename Base::Shared_data construct_shared_data( const FaceGraph& graph ) + { + return Base::construct_shared_data(Triangle_property_map(&graph), Point_property_map(&graph)); + } + + //for backward-compatibility with AABB_polyhedron_triangle_primitive + static typename Base::Shared_data construct_shared_data() + { + return Base::construct_shared_data(Triangle_property_map(NULL), Point_property_map(NULL)); + } + }; } // end namespace CGAL - #endif // CGAL_AABB_FACEGRAPH_TRIANGLE_PRIMITIVE_H diff --git a/AABB_tree/include/CGAL/AABB_HalfedgeGraph_segment_primitive.h b/AABB_tree/include/CGAL/AABB_HalfedgeGraph_segment_primitive.h index 6cd0315161b..9c9e090836c 100644 --- a/AABB_tree/include/CGAL/AABB_HalfedgeGraph_segment_primitive.h +++ b/AABB_tree/include/CGAL/AABB_HalfedgeGraph_segment_primitive.h @@ -18,10 +18,6 @@ // // Author(s) : Sebastien Loriot // -//****************************************************************************** -// File Description : -// -//****************************************************************************** #ifndef CGAL_AABB_HALFEDGEGRAPH_SEGMENT_PRIMITIVE_H #define CGAL_AABB_HALFEDGEGRAPH_SEGMENT_PRIMITIVE_H @@ -38,29 +34,80 @@ #include namespace CGAL { - + + +/*! + * \ingroup PkgAABB_tree + * Primitive type for a facet of a polyhedral surface. + * If `OneHalfedgeGraphPerTree is `CGAL::Tag_false, the class is a model of the concept `AABBPrimitive`. + * If `OneHalfedgeGraphPerTree` is `CGAL::Tag_true`, the class is a model of the concept `AABBPrimitiveWithSharedData`. + * It wraps an `edge_descriptor` into a 3D segment. + * The class model of `HalfedgeGraph` from which the primitive is built should not be deleted + * while the AABB tree holding the primitive is in use. + * + * \tparam HalfedgeGraph is a model of the halfedge graph concept. + * \tparam OneHalfedgeGraphPerTree is either `CGAL::Tag_true or `CGAL::Tag_false`. + * In the former case, we guarantee that all the primitives will be from a + * common `HalfedgeGraph` and some data will be factorized so that the size of + * the primitive is reduced. In the latter case, the primitives can be from + * different graphs and extra storage is required in the primitives. The default is `CGAL::Tag_true`. + * \tparam cache_datum is either `CGAL::Tag_true` or `CGAL::Tag_false`. In the former case, the datum is + * stored in the primitive, while in the latter it is constructed on the fly to reduce + * the memory footprint. The default is `CGAL::Tag_false` (datum is not stored). + * + * \sa `AABBPrimitive` + * \sa `AABB_primitive` + * \sa `AABB_FaceGraph_triangle_primitive` + */ template < class HalfedgeGraph, class OneHalfedgeGraphPerTree=Tag_true, class cache_datum=Tag_false, class Id_=typename boost::graph_traits::edge_descriptor > -class AABB_HalfedgeGraph_segment_primitive : public AABB_primitive< Id_, - Segment_from_edge_descriptor_property_map, - Source_point_from_edge_descriptor, - OneHalfedgeGraphPerTree, - cache_datum > +class AABB_HalfedgeGraph_segment_primitive +#ifndef DOXYGEN_RUNNING + : public AABB_primitive< Id_, + Segment_from_edge_descriptor_property_map, + Source_point_from_edge_descriptor, + OneHalfedgeGraphPerTree, + cache_datum > +#endif { typedef Segment_from_edge_descriptor_property_map Triangle_property_map; typedef Source_point_from_edge_descriptor Point_property_map; - + typedef AABB_primitive< Id_, Segment_property_map, Point_property_map, Tag_true, cache_datum > Base; - + public: - // constructors + +#ifdef DOXYGEN_RUNNING + /// \name Types + /// @{ + /*! + The point type. + */ + typedef boost::property_traits< boost::property_map< HalfedgeGraph, vertex_point_t>::type >::value_type Point; + /*! + Geometric data type. + */ + typedef Kernel_traits::Kernel::Segment_3 Datum; + /*! + Id type. + */ + typedef boost::graph_traits::edge_descriptor Id; + /// @} +#endif + + /*! + Constructs a primitive. + \tparam Iterator is an input iterator with `Id` as value type. + The example \ref AABB_HalfedgeGraph_edge_example.cpp gives a way to call this constructor + using the the insert-by-range method of the class `AABB_tree`. + */ template AABB_HalfedgeGraph_segment_primitive(Iterator it, const HalfedgeGraph& graph) : Base( Id_(*it), @@ -72,12 +119,12 @@ public: : Base( id, Segment_property_map(NULL), Point_property_map(NULL) ){} - + static typename Base::Shared_data construct_shared_data( const HalfedgeGraph& graph ) { return Base::construct_shared_data(Segment_property_map(&graph), Point_property_map(&graph)); } - + //for backward-compatibility with AABB_polyhedron_segment_primitive static typename Base::Shared_data construct_shared_data() { diff --git a/AABB_tree/include/CGAL/AABB_polyhedron_segment_primitive.h b/AABB_tree/include/CGAL/AABB_polyhedron_segment_primitive.h index c97cbbe9d89..491d9832680 100644 --- a/AABB_tree/include/CGAL/AABB_polyhedron_segment_primitive.h +++ b/AABB_tree/include/CGAL/AABB_polyhedron_segment_primitive.h @@ -34,7 +34,9 @@ namespace CGAL { /// \addtogroup PkgAABB_tree /// @{ - + /// \deprecated This class is deprecated since \cgal 4.3, the class + /// `AABB_HalfedgeGraph_segment_primitive` should be used instead. + /// /// The class AABB_polyhedron_segment_primitive is a model of the /// concept \ref AABBPrimitive. It wraps a halfedge handle of a /// polyhedron, which is used as id, and allows the construction @@ -46,8 +48,8 @@ namespace CGAL { /// \tparam GeomTraits must provide a \c %Point_3 /// type, used as \c Point, and a \c %Segment_3 type, used as \c /// Datum and constructible from two arguments of type \c - /// Point. - /// \tparam Polyhedron must be a + /// Point. + /// \tparam Polyhedron must be a /// \c CGAL::Polyhedron_3 whose points have type \c Point. /// /// \sa `AABBPrimitive` @@ -79,7 +81,7 @@ namespace CGAL { : m_halfedge_handle(*ptr) { }; template AABB_polyhedron_segment_primitive( Iterator it, - typename boost::enable_if< + typename boost::enable_if< boost::is_same >::type* =0 ) : m_halfedge_handle(*it) { } diff --git a/AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h b/AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h index f93bfd8a827..c46a1f32548 100644 --- a/AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h +++ b/AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h @@ -18,10 +18,6 @@ // // Author(s) : Stéphane Tayeb, Pierre Alliez // -//****************************************************************************** -// File Description : -// -//****************************************************************************** #ifndef CGAL_AABB_POLYHEDRON_TRIANGLE_PRIMITIVE_H_ #define CGAL_AABB_POLYHEDRON_TRIANGLE_PRIMITIVE_H_ @@ -30,9 +26,11 @@ #define CGAL_REPLACEMENT_HEADER "" #include - namespace CGAL { /// \ingroup PkgAABB_tree + /// \deprecated This class is deprecated since \cgal 4.3, the class + /// `AABB_HalfedgeGraph_triangle_primitive` should be used instead. + /// /// The class AABB_polyhedron_triangle_primitive is a model of the concept /// \ref AABBPrimitive. It wraps a facet handle of a polyhedron, /// which is used as id, and allows the construction of the datum on @@ -79,7 +77,7 @@ namespace CGAL { : m_facet_handle(*ptr) { }; template AABB_polyhedron_triangle_primitive( Iterator it, - typename boost::enable_if< + typename boost::enable_if< boost::is_same >::type* =0 ) : m_facet_handle(*it) { } diff --git a/AABB_tree/include/CGAL/AABB_primitive.h b/AABB_tree/include/CGAL/AABB_primitive.h index d67d49e241d..e938dbaa97c 100644 --- a/AABB_tree/include/CGAL/AABB_primitive.h +++ b/AABB_tree/include/CGAL/AABB_primitive.h @@ -18,10 +18,6 @@ // // Author(s) : Sebastien Loriot // -//****************************************************************************** -// File Description : -// -//****************************************************************************** #ifndef CGAL_AABB_PRIMITIVE_H #define CGAL_AABB_PRIMITIVE_H @@ -49,11 +45,81 @@ protected: public: // constructors AABB_primitive_base(Id id) : m_id(id) {} - + Id id() const {return m_id;} }; +#ifdef DOXYGEN_RUNNING +/*! + * \ingroup PkgAABB_tree + * Generic primitive class. + * If `ExternalPropertyMaps` is `CGAL::Tag_false`, the class is a model of the concept `AABBPrimitive`. + * If `ExternalPropertyMaps` is `CGAL::Tag_true`, the class is a model of the concept `AABBPrimitiveWithSharedData`. + * The two property maps which are template parameters of the class enable to get the datum and the reference point of + * the primitive from the identifier. The last template parameter controls whether the primitive class holds a copy of the datum. + * + * \tparam ObjectPropertyMap is a model of `ReadablePropertyMap`with `Id` as + * `key_type`. It must be default constructible. + * \tparam PointPropertyMap is a model of `ReadablePropertyMap` with `Id` as + * `key_type`. It must be default constructible. + * \tparam ExternalPropertyMaps either `CGAL::Tag_true` or `CGAL::Tag_false`. In the former + * case, the property maps will be stored in the traits class, while + * in the latter they will be stored in the primitive + * (which increases the size of each primitive). + * \tparam cache_datum either `CGAL::Tag_true` or `CGAL::Tag_false`. In the former case, + * the datum is stored in the primitive, while in the latter + * it is constructed on the fly to reduce the memory footprint. + * The default is `CGAL::Tag_false` (datum is not stored). + * + * \sa `AABBPrimitive` + * \sa `AABB_segment_primitive` + * \sa `AABB_triangle_primitive` + * \sa `AABB_HalfedgeGraph_segment_primitive` + * \sa `AABB_FaceGraph_triangle_primitive` + */ +template < class Id, + class ObjectPropertyMap, + class PointPropertyMap, + class ExternalPropertyMaps, + class cache_datum> +struct AABB_primitive +{ + /// \name Types + /// @{ + /*! + The datum type. + */ + typedef boost::property_traits< ObjectPropertyMap >::value_type Datum; + /*! + The point type. + */ + typedef boost::property_traits< PointPropertyMap >::value_type Point; + + /*! + The reference datum type. + */ + typedef boost::property_traits< ObjectPropertyMap >::reference Datum_reference; + + /*! + The reference point type. + */ + typedef boost::property_traits< PointPropertyMap >::reference Point_reference; + + /*! + Id type. + */ + typedef Id Id; + /// @} + + /*! + Constructs a primitive and initializes the property maps. + */ + AABB_primitive(Id id, + ObjectPropertyMap o_pmap=ObjectPropertyMap(), + PointPropertyMap p_pmap=PointPropertyMap()); +}; +#else template < class Id, class ObjectPropertyMap, class PointPropertyMap, @@ -65,7 +131,7 @@ struct AABB_primitive; //no caching, property maps internally stored template < class Id, class ObjectPropertyMap, - class PointPropertyMap > + class PointPropertyMap > class AABB_primitive : public AABB_primitive_base { @@ -75,10 +141,10 @@ class AABB_primitivem_id); } - + typename Base::Point_reference reference_point() const { return get(m_pt_pmap,this->m_id); } }; @@ -86,7 +152,7 @@ public: //caching, property maps internally stored template < class Id, class ObjectPropertyMap, - class PointPropertyMap > + class PointPropertyMap > class AABB_primitive : public AABB_primitive_base { @@ -98,10 +164,10 @@ public: AABB_primitive(Id id, ObjectPropertyMap obj_pmap=ObjectPropertyMap(), PointPropertyMap pt_pmap=PointPropertyMap()) : Base(id), m_datum( get(obj_pmap,id) ), m_pt_pmap(pt_pmap){} - - + + Datum_reference datum() const { return m_datum; } - + typename Base::Point_reference reference_point() const { return get(m_pt_pmap,this->m_id); } }; @@ -109,7 +175,7 @@ public: //no caching, property maps are stored outside the class template < class Id, class ObjectPropertyMap, - class PointPropertyMap > + class PointPropertyMap > class AABB_primitive : public AABB_primitive_base { @@ -119,13 +185,13 @@ public: AABB_primitive(Id id, ObjectPropertyMap=ObjectPropertyMap(), PointPropertyMap=PointPropertyMap()) : Base(id) {} - + typename Base::Datum_reference datum(const Shared_data& data) const { return get(data.first,this->m_id); } - + typename Base::Point_reference reference_point(const Shared_data& data) const { return get(data.second,this->m_id); } - + static Shared_data construct_shared_data(ObjectPropertyMap obj, PointPropertyMap pt) {return Shared_data(obj,pt);} }; @@ -133,7 +199,7 @@ public: //caching, property map is stored outside the class template < class Id, class ObjectPropertyMap, - class PointPropertyMap > + class PointPropertyMap > class AABB_primitive : public AABB_primitive_base { @@ -145,14 +211,16 @@ public: AABB_primitive(Id id, ObjectPropertyMap obj_pmap=ObjectPropertyMap(), PointPropertyMap=PointPropertyMap()) : Base(id), m_datum( get(obj_pmap,id) ) {} - + Datum_reference datum(Shared_data) const { return m_datum; } - + typename Base::Point_reference reference_point(const Shared_data& data) const { return get(data,this->m_id); } - + static Shared_data construct_shared_data(ObjectPropertyMap, PointPropertyMap pt) {return pt;} -}; +}; + +#endif //DOXYGEN_RUNNING } // end namespace CGAL diff --git a/AABB_tree/include/CGAL/AABB_segment_primitive.h b/AABB_tree/include/CGAL/AABB_segment_primitive.h index f86256e20ef..5859c5fa831 100644 --- a/AABB_tree/include/CGAL/AABB_segment_primitive.h +++ b/AABB_tree/include/CGAL/AABB_segment_primitive.h @@ -18,10 +18,7 @@ // // Author(s) : Sebastien Loriot // -//****************************************************************************** -// File Description : -// -//****************************************************************************** + #ifndef CGAL_AABB_SEGMENT_PRIMITIVE_H_ #define CGAL_AABB_SEGMENT_PRIMITIVE_H_ @@ -42,7 +39,7 @@ namespace internal { typedef const typename GeomTraits::Point_3& reference; typedef boost::readable_property_map_tag category; }; - + //get function for property map template inline @@ -54,13 +51,36 @@ namespace internal { }//namespace internal +/*! + * \ingroup PkgAABB_tree + * The class AABB_segment_primitive is a model of the concept `AABBPrimitive`. + * An iterator with a 3D segment as `value_type}` is used as identifier. + * The iterator from which the primitive is built should not be invalided + * while the AABB tree holding the primitive is in use. + * + * \tparam Iterator is a model of `ForwardIterator`, with `Segment_3` + * as value type + * \tparam cache_datum is either `CGAL::Tag_true` or `CGAL::Tag_false`. In the former case, + * the datum is stored in the primitive, while in the latter it is + * constructed on the fly to reduce the memory footprint. + * The default is `CGAL::Tag_false` (datum is not stored). + * + * \sa `AABBPrimitive` + * \sa `AABB_primitive` + * \sa `AABB_triangle_primitive` + * \sa `AABB_HalfedgeGraph_segment_primitive` + * \sa `AABB_FaceGraph_triangle_primitive` + */ template < class Iterator, class cache_datum=Tag_false> -class AABB_segment_primitive : public AABB_primitive< Iterator, - Input_iterator_property_map, - internal::Source_of_segment_3_iterator_property_map, - Tag_true, - cache_datum > +class AABB_segment_primitive +#ifndef DOXYGEN_RUNNING + : public AABB_primitive< Iterator, + Input_iterator_property_map, + internal::Source_of_segment_3_iterator_property_map, + Tag_true, + cache_datum > +#endif { typedef AABB_primitive< Iterator, Input_iterator_property_map, @@ -68,9 +88,9 @@ class AABB_segment_primitive : public AABB_primitive< Iterator, Tag_true, cache_datum > Base; public: - // constructors + ///Constructor from an iterator AABB_segment_primitive(Iterator it) : Base(it){} - + static typename Base::Shared_data construct_shared_data() {return typename Base::Shared_data();} }; diff --git a/AABB_tree/include/CGAL/AABB_traits.h b/AABB_tree/include/CGAL/AABB_traits.h index f6b4bd8a9c9..c53359b31af 100644 --- a/AABB_tree/include/CGAL/AABB_traits.h +++ b/AABB_tree/include/CGAL/AABB_traits.h @@ -18,10 +18,6 @@ // // Author(s) : Stéphane Tayeb, Pierre Alliez, Camille Wormser // -//****************************************************************************** -// File Description : -// -//****************************************************************************** #ifndef CGAL_AABB_TRAITS_H_ #define CGAL_AABB_TRAITS_H_ @@ -46,22 +42,22 @@ struct Remove_optional { typedef T type; }; template struct Remove_optional< ::boost::optional > { typedef T type; }; -//helper controlling whether extra data should be stored in the AABB_tree traits class +//helper controlling whether extra data should be stored in the AABB_tree traits class template ::value> struct AABB_traits_base; - + template struct AABB_traits_base{}; template struct AABB_traits_base{ typename Primitive::Shared_data m_primitive_data; - + #ifndef CGAL_CFG_NO_CPP0X_VARIADIC_TEMPLATES template void set_shared_data(T ... t){ m_primitive_data=PrimitiveType::construct_shared_data(t...); - } + } #else template void set_shared_data(){ @@ -72,7 +68,7 @@ struct AABB_traits_base{ void set_shared_data(T1 t1){ m_primitive_data=PrimitiveType::construct_shared_data(t1); } - + template void set_shared_data(T1 t1,T2 t2,T3 t3){ m_primitive_data=PrimitiveType::construct_shared_data(t1,t2,t3); @@ -82,7 +78,7 @@ struct AABB_traits_base{ void set_shared_data(T1 t1,T2 t2,T3 t3,T4 t4){ m_primitive_data=PrimitiveType::construct_shared_data(t1,t2,t3,t4); } - + template void set_shared_data(T1 t1,T2 t2,T3 t3,T4 t4,T5 t5){ m_primitive_data=PrimitiveType::construct_shared_data(t1,t2,t3,t4,t5); @@ -102,15 +98,16 @@ struct AABB_traits_base{ /// constructions are implemented. It handles points, rays, lines and /// segments as query types for intersection detection and /// computations, and it handles points as query type for distance -/// queries. +/// queries. /// \tparam GeomTraits must be a model of the concept \ref AABBGeomTraits, /// snd provide the geometric types as well as the intersection tests and computations. -/// \tparam Primitive must be a model of the concept \ref AABBPrimitive and provide the -/// type of primitives stored in the AABB_tree. +/// \tparam Primitive provide the type of primitives stored in the AABB_tree. +/// It is a model of the concept `AABBPrimitive` or `AABBPrimitiveWithSharedData`. /// /// \sa `AABBTraits` /// \sa `AABB_tree` /// \sa `AABBPrimitive` +/// \sa `AABBPrimitiveWithSharedData` template class AABB_traits: public internal::AABB_tree::AABB_traits_base @@ -136,7 +133,7 @@ public: typename GeomTraits::Intersect_3(Query, typename Primitive::Datum) >::type Intersection_type; - typedef std::pair< + typedef std::pair< typename internal::AABB_tree::Remove_optional::type, typename Primitive::Id > Type; }; @@ -152,20 +149,20 @@ public: /// \bug This is not documented for now in the AABBTraits concept. typedef typename GeomTraits::Iso_cuboid_3 Iso_cuboid_3; - /// + /// typedef typename CGAL::Bbox_3 Bounding_box; /// @} typedef typename GeomTraits::Sphere_3 Sphere_3; - typedef typename GeomTraits::Cartesian_const_iterator_3 Cartesian_const_iterator_3; + typedef typename GeomTraits::Cartesian_const_iterator_3 Cartesian_const_iterator_3; typedef typename GeomTraits::Construct_cartesian_const_iterator_3 Construct_cartesian_const_iterator_3; typedef typename GeomTraits::Construct_center_3 Construct_center_3; typedef typename GeomTraits::Compute_squared_radius_3 Compute_squared_radius_3; typedef typename GeomTraits::Construct_min_vertex_3 Construct_min_vertex_3; - typedef typename GeomTraits::Construct_max_vertex_3 Construct_max_vertex_3; + typedef typename GeomTraits::Construct_max_vertex_3 Construct_max_vertex_3; typedef typename GeomTraits::Construct_iso_cuboid_3 Construct_iso_cuboid_3; - + /// Default constructor. AABB_traits() { }; @@ -190,7 +187,7 @@ public: public: Sort_primitives(const AABB_traits& traits) : m_traits(traits) {} - + template void operator()(PrimitiveIterator first, PrimitiveIterator beyond, @@ -228,7 +225,7 @@ public: public: Compute_bbox(const AABB_traits& traits) :m_traits (traits) {} - + template typename AT::Bounding_box operator()(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond) const @@ -339,7 +336,7 @@ Intersection intersection_object() const {return Intersection(*this);} return GeomTraits().do_intersect_3_object() (GeomTraits().construct_sphere_3_object()(p, sq_distance), pr) ? - CGAL::SMALLER : + CGAL::SMALLER : CGAL::LARGER; } }; diff --git a/AABB_tree/include/CGAL/AABB_tree.h b/AABB_tree/include/CGAL/AABB_tree.h index 412e6d1f291..c3eafc7eafb 100644 --- a/AABB_tree/include/CGAL/AABB_tree.h +++ b/AABB_tree/include/CGAL/AABB_tree.h @@ -48,6 +48,7 @@ namespace CGAL { * of 3D geometric objects, and can receive intersection and distance * queries, provided that the corresponding predicates are * implemented in the traits class AABBTraits. + * An instance of the class `AABBTraits` is internally stored. * * \sa `AABBTraits` * \sa `AABBPrimitive` @@ -104,37 +105,36 @@ namespace CGAL { /// \name Creation ///@{ - /// Constructs an empty tree. + /// Constructs an empty tree, and initializes the internally stored traits + /// class using `traits`. AABB_tree(const AABBTraits& traits); - /** + /** * @brief Builds the datastructure from a sequence of primitives. * @param first iterator over first primitive to insert * @param beyond past-the-end iterator * + * It is equivalent to constructing an empty tree and calling `insert(first,last,t...)`. + * For compilers that do not support variadic templates, overloads up to + * 5 template arguments are provided. * The tree stays empty if the memory allocation is not successful. - * \tparam ConstPrimitiveIterator can be - * any const iterator on a container of - * AABB_tree::Primitive::id_type such that AABB_tree::Primitive - * has a constructor taking a ConstPrimitiveIterator as - * argument. */ #ifndef CGAL_CFG_NO_CPP0X_VARIADIC_TEMPLATES - template - AABB_tree(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T...); + template + AABB_tree(InputIterator first, InputIterator beyond,T...); #else - template - AABB_tree(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond); - template - AABB_tree(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T1); - template - AABB_tree(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T1,T2); - template - AABB_tree(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T1,T2,T3); - template - AABB_tree(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T1,T2,T3,T4); - template - AABB_tree(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T1,T2,T3,T4,T5); + template + AABB_tree(InputIterator first, InputIterator beyond); + template + AABB_tree(InputIterator first, InputIterator beyond,T1); + template + AABB_tree(InputIterator first, InputIterator beyond,T1,T2); + template + AABB_tree(InputIterator first, InputIterator beyond,T1,T2,T3); + template + AABB_tree(InputIterator first, InputIterator beyond,T1,T2,T3,T4); + template + AABB_tree(InputIterator first, ConstPrimitiveIterator beyond,T1,T2,T3,T4,T5); #endif ///@} @@ -142,8 +142,9 @@ namespace CGAL { /// \name Operations ///@{ - /// Clears the current tree and rebuilds it from scratch. See - /// constructor above for the parameters. + /// Equivalent to calling `clear()` and then `insert(first,last,t...)`. + /// For compilers that do not support variadic templates, overloads up + /// to 5 template arguments are provided. #ifndef CGAL_CFG_NO_CPP0X_VARIADIC_TEMPLATES template void rebuild(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T...); @@ -163,27 +164,31 @@ namespace CGAL { #endif - /// Adds a sequence of primitives to the set of primitives of the - /// tree. \tparam ConstPrimitiveIterator can be any const iterator - /// such that `AABB_tree::Primitive` has a constructor taking an - /// ConstPrimitiveIterator as argument. - template + /// Add a sequence of primitives to the set of primitives of the AABB tree. + /// `%InputIterator` is any iterator and the parameter pack `T` are any types + /// such that `Primitive` has a constructor with the following signature: + /// `Primitive(%InputIterator, T...)`. If `Primitive` is a model of the concept + /// `AABBPrimitiveWithSharedData`, a call to `AABBTraits::set_shared_data(t...)` + /// is made using the internally stored traits. + /// For compilers that do not support variadic templates, + /// overloads up to 5 template arguments are provided. + template #ifndef CGAL_CFG_NO_CPP0X_VARIADIC_TEMPLATES - template - void insert(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T...); + template + void insert(InputIterator first, InputIterator beyond,T...); #else - template - void insert(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond); - template - void insert(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T1); - template - void insert(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T1,T2); - template - void insert(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T1,T2,T3); - template - void insert(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T1,T2,T3,T4); - template - void insert(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond,T1,T2,T3,T4,T5); + template + void insert(InputIterator first, InputIterator beyond); + template + void insert(InputIterator first, InputIterator beyond,T1); + template + void insert(InputIterator first, InputIterator beyond,T1,T2); + template + void insert(InputIterator first, InputIterator beyond,T1,T2,T3); + template + void insert(InputIterator first, InputIterator beyond,T1,T2,T3,T4); + template + void insert(InputIterator first, ConstPrimitiveIterator beyond,T1,T2,T3,T4,T5); #endif /// Adds a primitive to the set of primitives of the tree. @@ -194,7 +199,7 @@ namespace CGAL { { clear(); } - + /// Returns a const reference to the internally stored traits class. const AABBTraits& traits() const{ return m_traits; } diff --git a/AABB_tree/include/CGAL/AABB_triangle_primitive.h b/AABB_tree/include/CGAL/AABB_triangle_primitive.h index db9865b4880..872e99a87b9 100644 --- a/AABB_tree/include/CGAL/AABB_triangle_primitive.h +++ b/AABB_tree/include/CGAL/AABB_triangle_primitive.h @@ -18,10 +18,7 @@ // // Author(s) : Sebastien Loriot // -//****************************************************************************** -// File Description : -// -//****************************************************************************** + #ifndef CGAL_AABB_TRIANGLE_PRIMITIVE_H_ #define CGAL_AABB_TRIANGLE_PRIMITIVE_H_ @@ -41,7 +38,7 @@ namespace internal { typedef const typename GeomTraits::Point_3& reference; typedef boost::readable_property_map_tag category; }; - + //get function for property map template inline @@ -53,13 +50,36 @@ namespace internal { }//namespace internal +/*! + * \ingroup PkgAABB_tree + * The class AABB_triangle_primitive is a model of the concept `AABBPrimitive`. + * An iterator with a 3D triangle as `value_type}` is used as identifier. + * The iterator from which the primitive is built should not be invalided + * while the AABB tree holding the primitive is in use. + * + * \tparam Iterator is a model of `ForwardIterator`, with `Triangle_3` + * as value type + * \tparam cache_datum is either `CGAL::Tag_true` or `CGAL::Tag_false`. In the former case, + * the datum is stored in the primitive, while in the latter it is + * constructed on the fly to reduce the memory footprint. + * The default is `CGAL::Tag_false` (datum is not stored). + * + * \sa `AABBPrimitive` + * \sa `AABB_primitive` + * \sa `AABB_segment_primitive` + * \sa `AABB_HalfedgeGraph_segment_primitive` + * \sa `AABB_FaceGraph_triangle_primitive` + */ template < class Iterator, class cache_datum=Tag_false> -class AABB_triangle_primitive : public AABB_primitive< Iterator, - Input_iterator_property_map, - internal::Point_from_triangle_3_iterator_property_map, - Tag_true, - cache_datum > +class AABB_triangle_primitive +#ifndef DOXYGEN_RUNNING + : public AABB_primitive< Iterator, + Input_iterator_property_map, + internal::Point_from_triangle_3_iterator_property_map, + Tag_true, + cache_datum > +#endif { typedef AABB_primitive< Iterator, Input_iterator_property_map, @@ -69,7 +89,7 @@ class AABB_triangle_primitive : public AABB_primitive< Iterator, public: // constructors AABB_triangle_primitive(Iterator it) : Base(it){} - + static typename Base::Shared_data construct_shared_data() {return typename Base::Shared_data();} };