New package: Feature graph

Feature_graph/doc/Feature_graph/CGAL/AmbrosioTortorelli_on_image.h

@@ -0,0 +1,72 @@
+namespace CGAL {
+
+/*!
+* \ingroup PkgFeatureGraphRef
+*
+* \brief Class that evaluates the Ambriosio-Tortorelli normals and sharpness measure from an image.
+* Two functors can then be retrieved to access the estimations.
+*
+* \tparam Vector_3 the type of the normal vector model of `Kernel::Vector_3`.
+*
+* \cgalModels{NormalEstimator}
+*/
+template <typename Vector_3>
+struct AmbrosioTortorelli_on_image
+{
+public:
+  /// \name Types
+  /// @{
+
+  /*!
+  * The type of the normal vector.
+  */
+  typedef Vector_3 Normal_type;
+
+  /*!
+  * The type of the functor that allows to retrieve the sharpness values.
+  * \cgalModels{SharpnessEstimator}
+  */
+  typedef unspecified_type Sharpness_functor;
+  /*!
+  * The type of the functor that allows to retrieve the normals.
+  * \cgalModels{NormalEstimator}
+  */
+  typedef unspecified_type Normal_functor;
+
+  ///@}
+
+  /// \name Constructor
+  /// @{
+
+  /*!
+  * evaluates the normal and sharpness values using the Ambrosio-Tortorelli energy optimization.
+  *
+  * \tparam Image the image type model of `FeatureImage_3`
+  * \tparam FT a model of `RealEmbeddable`
+  *
+  * \param image the image.
+  * \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 Image, typename FT = Sharpness_functor::Sharpness_value_type>
+  AmbrosioTortorelli_on_image(const Image& image, const FT& selection_threshold = FT(0.25));
+
+  // @}
+
+  /// \name Functor Accessors
+  /// @{
+
+  /*!
+  * returns the functor that allows to retrieve the sharpness values.
+  */
+  Sharpness_functor get_sharpness_functor() const;
+  /*!
+  * returns the functor that allows to retrieve the normals.
+  */
+  Normal_functor get_normal_functor() const;
+
+  ///@}
+};
+
+} /* namespace CGAL */

Feature_graph/doc/Feature_graph/CGAL/Normal_estimator/Normal_estimator_on_surface.h

@@ -0,0 +1,64 @@
+namespace CGAL {
+
+namespace Normal_estimator
+{
+
+/*!
+* \ingroup PkgFeatureGraphNormalEstimator
+*
+* \brief Functor 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 Normal_estimator_on_surface
+{
+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 Surface a model of `FaceListGraph` that represents a surface mesh.
+  *
+  * \param surface the surface where the normals are evaluated.
+  */
+  template <typename Surface>
+  Normal_estimator_on_surface(const Surface& surface);
+
+  // @}
+
+  /// \name Functor
+  /// @{
+
+  /*!
+  * returns the normal vector of the surface element described by a type and an index.
+  *
+  * \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 Index the type of index of the element to evaluate.
+  *
+  * \param element_index the index of the element to evaluate.
+  */
+  template <typename DimensionTag, typename Index>
+  Normal_type operator()(const Index& element_index) const;
+
+  /// @}
+};
+
+} /* namespace Normal_estimator */
+
+} /* namespace CGAL */

Feature_graph/doc/Feature_graph/CGAL/Sharpness_estimator/Sharpness_estimator_on_surface.h

@@ -0,0 +1,65 @@
+namespace CGAL {
+
+namespace Sharpness_estimator
+{
+
+/*!
+* \ingroup PkgFeatureGraphSharpnessEstimator
+*
+* \brief Functor that assign a sharpness value on elements of a surface.
+*
+* \cgalModels{SharpnessEstimator}
+*/
+struct Sharpness_estimator_on_surface
+{
+public:
+  /// \name Types
+  /// @{
+
+  /*!
+  * The type of of the sharpness value.
+  */
+  typedef double Sharpness_value_type;
+
+  ///@}
+
+  /// \name Constructor
+  /// @{
+
+  /*!
+  * Constructor that pre-computes the normals on the surface.
+  *
+  * \tparam Surface a model of `FaceListGraph` that represents a surface mesh.
+  * \tparam FT a model of `RealEmbeddable`
+  *
+  * \param surface 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 Surface, typename FT = Sharpness_value_type>
+  Sharpness_estimator_on_surface(const Surface& surface, const FT& selection_threshold);
+
+  // @}
+
+  /// \name Functor
+  /// @{
+
+  /*!
+  * returns the sharpness value of the surface element described by a type and an index.
+  *
+  * \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 Index the type of index of the element to evaluate.
+  *
+  * \param element_index the index of the element to evaluate.
+  */
+  template <typename DimensionTag, typename Index>
+  Sharpness_value_type operator()(const Index& element_index) const;
+
+  /// @}
+};
+
+} /* namespace Sharpness_estimator */
+
+} /* namespace CGAL */

Feature_graph/doc/Feature_graph/CGAL/detect_sharp_features.h

@@ -0,0 +1,131 @@
+namespace CGAL {
+
+/*!
+* \ingroup PkgFeatureGraphDetector
+*
+* Functor for sharp feature detection in labeled images.
+*/
+struct Detect_sharp_features_on_labeled_image
+{
+  /*!
+  * \brief detects and constructs the feature graph from a labeled image
+  *
+  * The feature graph has polylines that lie on the
+  * sharp features of the surface defined by the image's subdomains.
+  * Each subdomain inside the bounding box
+  * of the input labeled image is defined as the set of voxels
+  * with the same value. The outside of the bounding box
+  * of the image is considered as a subdomain with voxel value `value_outside`.
+  *
+  * \tparam Point_3 class model of `Kernel::Point_3`.
+  * It defines the feature graph point type.
+  *
+  * \tparam Image class model of `FeatureImage_3`.
+  * It represent a labeled image.
+  *
+  * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
+  *
+  * \param image the input image
+  *
+  * \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below:
+  * \cgalNamedParamsBegin
+  *   \cgalParamSectionBegin{sharpness_estimator}
+  *     \cgalParamDescription{a functor model of `SharpnessEstimator`.
+  *       See \ref PkgFeatureGraphSharpnessEstimator for available functors.}
+  *     \cgalParamDefault{`CGAL::AmbrosioTortorelli_on_image(image).get_sharpness_functor()`}
+  *   \cgalParamSectionEnd
+  *   \cgalParamSectionBegin{regularization_parameters}
+  *     \cgalParamDescription{an instance of `CGAL::Regularization_parameters`.
+  *       It describes the parameters for the regularization step.}
+  *     \cgalParamDefault{`CGAL::Regularization_parameters_on_image()`}
+  *   \cgalParamSectionEnd
+  *   \cgalParamSectionBegin{do_optimize}
+  *     \cgalParamDescription{a boolean indicating if the optimization step is called.}
+  *     \cgalParamDefault{`true`}
+  *   \cgalParamSectionEnd
+  *   \cgalParamSectionBegin{optimization_parameters}
+  *     \cgalParamDescription{an instance of `CGAL::Optimization_parameters`.
+  *       It describe the parameters for the optimization step.}
+  *     \cgalParamDefault{`CGAL::Optimization_parameters_on_image<>()`}
+  *   \cgalParamSectionEnd
+  *   \cgalParamSectionBegin{point_to_element_output_map}
+  *     \cgalParamDescription{an output property map that will be filled if supplied.
+    *     It allows to retrieve the surface element where a feature graph point is embedded.
+    *     It must be a model of `WritablePropertyMap`,
+    *     so it must implement `put(output_pmap, point_index, element_index)`
+    *     where the key type is the point index type and the value type the element index type.
+    *     The element index correspond to surface element with the tag `CGAL::DimensionTag<2>`}
+  *     \cgalParamDefault{`parameters::default()`}
+  *   \cgalParamSectionEnd
+  * \cgalNamedParamsEnd
+  *
+  * \returns a graph model of `VertexAndEdgeListGraph`
+  * containing the constructed features.
+  *
+  * \sa `Detect_sharp_features_on_surface::oprator()()`
+  */
+  template<typename Point_3, typename Image, typename CGAL_NP_TEMPLATE_PARAMETERS>
+  unspecified_type operator()(const Image& image, const CGAL_NP_CLASS& np = parameters::default_values()) const;
+};
+
+/*!
+* \ingroup PkgFeatureGraphDetector
+*
+* Functor for sharp feature detection in surfaces.
+*/
+struct Detect_sharp_features_on_surface
+{
+  /*!
+  * \brief detects and constructs the feature graph from a surface
+  *
+  * The feature graph has polylines that lie on the
+  * sharp features of the surface.
+  *
+  * \tparam Point_3 a model of `Kernel::Point_3`.
+  * It defines the feature graph point type.
+  *
+  * \tparam Surface a model of `FaceListGraph` that represents a surface mesh.
+  *
+  * \param surface the input surface
+  *
+  * \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below:
+  * \cgalNamedParamsBegin
+  *   \cgalParamSectionBegin{sharpness_estimator}
+  *     \cgalParamDescription{a functor model of `SharpnessEstimator`.
+  *       See \ref PkgFeatureGraphSharpnessEstimator for available functors.}
+  *     \cgalParamDefault{`CGAL::Sharpness_estimator::Sharpness_estimator_on_surface(surface)`}
+  *   \cgalParamSectionEnd
+  *   \cgalParamSectionBegin{regularization_parameters}
+  *     \cgalParamDescription{an instance of `CGAL::Regularization_parameters`.
+  *       It describes the parameters for the regularization step.}
+  *     \cgalParamDefault{`CGAL::Regularization_parameters_on_surface()`}
+  *   \cgalParamSectionEnd
+  *   \cgalParamSectionBegin{do_optimize}
+  *     \cgalParamDescription{a boolean indicating if the optimization step is called.}
+  *     \cgalParamDefault{`true`}
+  *   \cgalParamSectionEnd
+  *   \cgalParamSectionBegin{optimization_parameters}
+  *     \cgalParamDescription{an instance of `Optimization_parameters`.
+  *     It describe the parameters for the optimization step.}
+  *     \cgalParamDefault{`CGAL::Optimization_parameters_on_surface<>()`}
+  *   \cgalParamSectionEnd
+  *   \cgalParamSectionBegin{point_to_element_output_map}
+  *     \cgalParamDescription{an output property map that will be filled if supplied.
+  *     It allows to retrieve the surface element where a feature graph point is embedded.
+  *     It must be a model of `WritablePropertyMap`,
+  *     so it must implement `put(output_pmap, point_index, element_index)`
+  *     where the key type is the point index type and the value type the element index type.
+  *     The element index correspond to surface element with the tag `CGAL::DimensionTag<2>`}
+  *     \cgalParamDefault{`parameters::default()`}
+  *   \cgalParamSectionEnd
+  * \cgalNamedParamsEnd
+  *
+  * \returns a graph model of `VertexAndEdgeListGraph`
+  * containing the constructed features.
+  */
+  template<typename Point_3, typename Surface, typename CGAL_NP_TEMPLATE_PARAMETERS>
+  unspecified_type operator()(const Surface& surface, const CGAL_NP_CLASS& np = parameters::default_values()) const;
+};
+
+
+} /* namespace CGAL */