New package: Feature graph

Documentation/doc/Documentation/packages.txt

@@ -128,6 +128,7 @@
 \package_listing{Surface_mesh_approximation}
 \package_listing{Heat_method_3}
 \package_listing{Surface_mesh_topology}
+\package_listing{Feature_graph}
 
 \cgalPackageSection{PartPointSetProcessing,Point Set Processing}
 

Feature_graph/doc/Feature_graph/CGAL/Feature_graph/Image_AmbrosioTortorelli.h

@@ -0,0 +1,71 @@
+namespace CGAL {
+
+namespace Feature_graph {
+
+/*!
+* \ingroup PkgFeatureGraphNormalEstimator, PkgFeatureGraphSharpnessEstimator
+*
+* \brief Class that evaluates the Ambriosio-Tortorelli normals and sharpness measure from an image.
+* Two estimators can then be retrieved to access the normal and sharpness estimations.
+*
+* \tparam Vector_3 the type of the normal vector model of `Kernel::Vector_3`.
+*
+*/
+template <typename Vector_3>
+struct Image_AmbrosioTortorelli
+{
+public:
+  /// \name Types
+  /// @{
+
+  /*!
+  * The type of the normal vector.
+  */
+  typedef Vector_3 Normal_type;
+
+  /*!
+  * The type of the estimator that allow the user to retrieve the sharpness values.
+  * \cgalModels{SharpnessEstimator}
+  */
+  typedef unspecified_type Sharpness_estimator;
+  /*!
+  * The type of the estimator that allow the user to retrieve the normals.
+  * \cgalModels{NormalEstimator}
+  */
+  typedef unspecified_type Normal_estimator;
+
+  /// @}
+
+  /// \name Constructor
+  /// @{
+
+  /*!
+  * evaluates the normal and sharpness values using the Ambrosio-Tortorelli energy optimization.
+  *
+  * \param image the image domain.
+  * \param selection_threshold a threshold on the sharpness value.
+  *     Elements with a sharpness value lower than this threshold are considered flat
+  *     and will be given a negative value.
+  */
+  Image_AmbrosioTortorelli(const CGAL::Image_3& image, const Sharpness_estimator::Sharpness_number_type& selection_threshold = Sharpness_estimator::Sharpness_number_type(0.25));
+
+  /// @}
+
+  /// \name Estimators
+  /// @{
+
+  /*!
+  * returns the estimator that allow the user to retrieve the sharpness values.
+  */
+  Sharpness_estimator sharpness_estimator() const;
+  /*!
+  * returns the estimator that allow the user to retrieve the normals.
+  */
+  Normal_estimator normal_estimator() const;
+
+  /// @}
+};
+
+} /* namespace Feature_graph */
+
+} /* namespace CGAL */

Feature_graph/doc/Feature_graph/CGAL/Feature_graph/Surface_normal_estimator.h

@@ -0,0 +1,71 @@
+namespace CGAL {
+
+namespace Feature_graph {
+
+/*!
+* \ingroup PkgFeatureGraphNormalEstimator
+*
+* \brief Estimator that assign a normal on elements of a surface.
+*
+* \tparam Vector_3 the type of the normal vector model of `Kernel::Vector_3`.
+*
+* \cgalModels{NormalEstimator}
+*/
+template <typename Vector_3>
+struct Surface_normal_estimator
+{
+public:
+  /// \name Types
+  /// @{
+
+  /*!
+  * The type of the normal vector.
+  */
+  typedef Vector_3 Normal_type;
+
+  /// @}
+
+  /// \name Constructor
+  /// @{
+
+  /*!
+  * Constructor that pre-computes the normals on the surface.
+  *
+  * \tparam PolygonMesh a model of `FaceListGraph` that represents a surface mesh.
+  *
+  * \param pmesh the surface where the normals are evaluated.
+  */
+  template <typename PolygonMesh>
+  Surface_normal_estimator(const PolygonMesh& pmesh);
+
+  /// @}
+
+  /// \name Estimator
+  /// @{
+
+  /*!
+  * returns the normal vector of the surface element identified by a dimension and a descriptor.
+  *
+  * \tparam DimensionTag a tag that represent the element type.
+  *         Can be `CGAL::Dimension_tag<0>`, `CGAL::Dimension_tag<1>` or `CGAL::Dimension_tag<2>`
+  * \tparam Descriptor the type of descriptor used to identify the element to evaluate,
+  * which can be a vertex, an edge, or a facet according to the DimensionTag.
+  * If the domain is of type `CGAL::Image_3`, it is a `std::size_t` for element with
+  * dimension 0, 1 and 2. If the domain is a model of `FaceListGraph`, it is a
+  * `vertex_descriptor` (resp. `halfedge_descriptor`; `face_descriptor `) for element with
+  * dimension 0 (resp. 1 ; 2).
+  * \tparam Domain the type of the surface where the element is embedded.
+  * Can be a `CGAL::Image_3`, or a model of `FaceListGraph` that represents a surface mesh.
+  *
+  * \param element_descriptor the descriptor of the element on the surface.
+  * \param domain the domain that contains the elements.
+  */
+  template <typename DimensionTag, typename Descriptor, typename Domain>
+  Normal_type operator()(const Descriptor& element_descriptor, const Domain& domain) const;
+
+  /// @}
+};
+
+} /* namespace Feature_graph */
+
+} /* namespace CGAL */

Feature_graph/doc/Feature_graph/CGAL/Feature_graph/Surface_sharpness_estimator.h

@@ -0,0 +1,72 @@
+namespace CGAL {
+
+namespace Feature_graph {
+
+/*!
+* \ingroup PkgFeatureGraphSharpnessEstimator
+*
+* \brief Estimator that assign a sharpness value on elements of a surface.
+*
+* \cgalModels{SharpnessEstimator}
+*/
+struct Surface_sharpness_estimator
+{
+public:
+  /// \name Types
+  /// @{
+
+  /*!
+  * The type of the sharpness value.
+  */
+  typedef double Sharpness_number_type;
+
+  /// @}
+
+  /// \name Constructor
+  /// @{
+
+  /*!
+  * Constructor that pre-computes the normals on the surface.
+  *
+  * \tparam PolygonMesh a model of `FaceListGraph` that represents a surface.
+  * \tparam FT a model of `RealEmbeddable`
+  *
+  * \param pmesh the surface where the normals are evaluated.
+  * \param selection_threshold a threshold on the sharpness value.
+  *     Elements with a sharpness value lower than this threshold are considered flat
+  *     and will be given a negative value.
+  */
+  template <typename PolygonMesh>
+  Surface_sharpness_estimator(const PolygonMesh& pmesh, const Sharpness_number_type& selection_threshold);
+
+  /// @}
+
+  /// \name Estimator
+  /// @{
+
+  /*!
+  * returns the sharpness value of the surface element described by a type and a descriptor.
+  *
+  * \tparam DimensionTag a tag that represent the element type.
+  *         Can be `CGAL::Dimension_tag<0>`, `CGAL::Dimension_tag<1>` or `CGAL::Dimension_tag<2>`
+  * \tparam Descriptor the type of descriptor used to identify the element to evaluate,
+  * which can be a vertex, an edge, or a facet according to the DimensionTag.
+  * If the domain is of type `CGAL::Image_3`, it is a `std::size_t` for element with
+  * dimension 0, 1 and 2. If the domain is a model of `FaceListGraph`, it is a
+  * `vertex_descriptor` (resp. `halfedge_descriptor`; `face_descriptor `) for element with
+  * dimension 0 (resp. 1 ; 2).
+  * \tparam Domain the type of the surface where the element is embedded.
+  * Can be a `CGAL::Image_3`, or a model of `FaceListGraph` that represents a surface mesh.
+  *
+  * \param element_descriptor the descriptor of the element on the surface.
+  * \param domain the domain that contains the elements.
+  */
+  template <typename DimensionTag, typename Descriptor, typename Domain>
+  Sharpness_number_type operator()(const Descriptor& element_descriptor, const Domain& domain) const;
+
+  /// @}
+};
+
+} /* namespace Feature_graph */
+
+} /* namespace CGAL */