Merge pull request #366 from SimonRohou/codac2_dev

Quentin's PR (visibility contractor) + updates + binding of contractors + Polygon

Author: SimonRohou

doc/CMakeLists.txt

@@ -6,11 +6,11 @@
 
   if(WITH_PYTHON)
 
-    find_package(Doxygen)
+    find_package(Doxygen 1.16.1 QUIET)
 
     if(NOT DOXYGEN_FOUND)
 
-      message(STATUS "Doxygen not found, not able to generate/install the API documentation.")
+      message(STATUS "The required version of Doxygen has not been found, the API documentation will not be generated.")
 
     else()
 

doc/manual/index.rst

@@ -248,6 +248,7 @@ User manual
    * Geometric contractors
       * :ref:`sec-ctc-geom-ctcdist`
       * :ref:`sec-ctc-geom-ctcpolar`
+      * :ref:`sec-ctc-geom-ctcvisible`
       * CtcSegment
       * CtcPolygon
       * CtcPointCloud
@@ -286,6 +287,7 @@ User manual
       * SepInverse
       * SepTransform
    * Geometrical separators
+      * SepVisible
       * SepPolarCart or SepCartPolar
       * SepPolygon
       * SepEllipse

doc/manual/manual/contractors/geometric/ctcnovisible.png

@@ -0,0 +1,165 @@
+.. _sec-ctc-geom-ctcvisible:
+
+The CtcVisible and CtcNoVisible contractors
+===========================================
+
+  Main authors: `Quentin Brateau <https://teusner.github.io/>`_ 
+
+The visibility constraint characterizes the set of points :math:`\mathbf{x} \in \mathbb{R}^2` that are visible from an observation point :math:`\mathbf{a}` given an obstacle segment :math:`[\mathbf{e}_1\mathbf{e}_2]`. 
+
+This constraint is based on the work of **Rémy Guyonneau** (see [Guyonneau2013]_). A point :math:`\mathbf{x}` is considered visible if the segment :math:`[\mathbf{a}\mathbf{x}]` does not intersect the obstacle segment :math:`[\mathbf{e}_1\mathbf{e}_2]`. This creates a "shadow cone" originating from :math:`\mathbf{a}`.
+
+.. image:: visibility.png
+   :alt: Illustration of the visibility constraint from an observation point [Guyonneau2013]_
+   :width: 250px
+
+.. image:: novisibility.png
+   :alt: Illustration of the non-visibility constraint from an observation point [Guyonneau2013]_
+   :width: 250px
+
+.. doxygenclass:: codac2::CtcVisible
+  :project: codac
+
+.. doxygenclass:: codac2::CtcNoVisible
+  :project: codac
+
+.. note::
+    Current implementations assume a thin (degenerated) observation point :math:`\mathbf{a}`. Future versions will support visibility from **observation lines**, set defined by **convex polygons**, and from any **set** defined by a Separator.
+
+Methods
+-------
+
+.. doxygenfunction:: codac2::CtcVisible::contract(IntervalVector&) const
+  :project: codac
+
+.. doxygenfunction:: codac2::CtcNoVisible::contract(IntervalVector&) const
+  :project: codac
+
+
+
+Example of use: Characterizing the set of visible and non-visible points from an observation point
+--------------------------------------------------------------------------------------------------
+
+In this example, we characterize the visible and hidden areas from an observer at the origin :math:`\mathbf{a}=(0,0)^\intercal` facing a wall represented by a segment from :math:`(2, -1)` to :math:`(2, 1)`.
+
+.. tabs::
+
+  .. group-tab:: Python
+
+    .. literalinclude:: src.py
+      :language: py
+      :start-after: [ctcvisible-beg]
+      :end-before: [ctcvisible-end]
+      :dedent: 4
+
+  .. group-tab:: C++
+
+    .. literalinclude:: src.cpp
+      :language: c++
+      :start-after: [ctcvisible-beg]
+      :end-before: [ctcvisible-end]
+      :dedent: 4
+
+.. figure:: ctcvisible.png
+  :width: 400px
+
+.. tabs::
+
+  .. group-tab:: Python
+
+    .. literalinclude:: src.py
+      :language: py
+      :start-after: [ctcnovisible-beg]
+      :end-before: [ctcnovisible-end]
+      :dedent: 4
+
+  .. group-tab:: C++
+
+    .. literalinclude:: src.cpp
+      :language: c++
+      :start-after: [ctcnovisible-beg]
+      :end-before: [ctcnovisible-end]
+      :dedent: 4
+
+  Characterization of the visibility area. The points that are not visible are out of the visibility region and belongs to the blue area. The uncertain region is represented in yellow.
+
+.. figure:: ctcnovisible.png
+  :width: 400px
+
+  Characterization of the non-visibility area. The points that are visible are out of the non-visibility region and belongs to the blue area. The uncertain region is represented in yellow.
+
+Separator on the Visibility Constraint
+---------------------------------------
+
+The visibility constraint can also be applied as a separator, which allows us to characterize the set of points that are visible or not visible from an observation point. This is particularly useful for applications such as path planning, where one needs to determine the regions that are accessible or hidden from a certain viewpoint.
+
+.. tabs::
+
+  .. group-tab:: Python
+
+    .. literalinclude:: src.py
+      :language: py
+      :start-after: [sepvisible_list-begin]
+      :end-before: [sepvisible_list-end]
+      :dedent: 4
+
+  .. group-tab:: C++
+
+    .. literalinclude:: src.cpp
+      :language: c++
+      :start-after: [sepvisible_list-begin]
+      :end-before: [sepvisible_list-end]
+      :dedent: 4
+
+
+.. figure:: sepvisible_segments.png
+  :width: 400px
+
+  Characterization of the visibility area relative to a list of obstacle segments. The green area is visible from the observation point, while blue area is not visible. The uncertain region is represented in yellow.
+
+.. tabs::
+
+  .. group-tab:: Python
+
+    .. literalinclude:: src.py
+      :language: py
+      :start-after: [sepvisible_polygon-begin]
+      :end-before: [sepvisible_polygon-end]
+      :dedent: 4
+
+  .. group-tab:: C++
+
+    .. literalinclude:: src.cpp
+      :language: c++
+      :start-after: [sepvisible_polygon-begin]
+      :end-before: [sepvisible_polygon-end]
+      :dedent: 4
+
+
+.. figure:: sepvisible_polygon.png
+  :width: 400px
+
+  Characterization of the visibility area relative to a polygon obstacle. The green area is visible from the observation point, while blue area is not visible. The uncertain region is represented in yellow.
+
+.. note::
+
+  When implementing visibility over a union of segments, **fake boundaries** are appearing. These occur when the intersection of several visibility contractors creates "uncertain" regions that do not correspond to actual physical visibility limits. This is particularly visible on the two Figures that show a line of yellow boxes in the blue area. For a detailed discussion on handling these in interval analysis, see [Brateau2025]_.
+
+Related content
+---------------
+
+.. |visibility-pdf| replace:: **Download the manuscript**
+.. _visibility-pdf: https://theses.hal.science/tel-00961501/file/these_remy_guyonneau.pdf
+
+.. |fake_boundaries-pdf| replace:: **Download the paper**
+.. _fake_boundaries-pdf: https://cyber.bibl.u-szeged.hu/index.php/actcybern/article/view/4560
+
+.. admonition:: References
+
+  .. [Guyonneau2013] \ R. Guyonneau. *Modélisation et exploitation d'incertitudes pour la robotique mobile à l'aide de l'analyse par intervalles*. PhD Thesis, 2013. |visibility-pdf|_
+
+  .. [Brateau2025] \ Q. Brateau, et al. *Considering Adjacent Sets for Computing the Visibility Region*. Acta Cybernetica, 2025. |fake_boundaries-pdf|_
+
+.. admonition:: Technical documentation
+
+  See the `C++ API documentation of CtcVisible <../../api/html/classcodac2_1_1_ctc_visible.html>`_.

doc/manual/manual/contractors/geometric/ctcvisible.png

@@ -5,6 +5,7 @@ Geometric contractors
 
    ctcdist.rst
    ctcpolar.rst
+   ctcvisible.rst
    CtcSegment <http://codac.io>
    CtcPolygon <http://codac.io>
    CtcEllipse <http://codac.io>

doc/manual/manual/contractors/geometric/ctcvisible.rst

@@ -11,6 +11,8 @@
 #include <codac2_CtcDist.h>
 #include <codac2_CtcPolar.h>
 #include <codac2_CtcProj.h>
+#include <codac2_CtcVisible.h>
+#include <codac2_SepVisible.h>
 #include <codac2_Approx.h>
 #include <codac2_cart_prod.h>
 #include <codac2_CtcInter.h>
@@ -86,4 +88,59 @@ TEST_CASE("CtcPolar - manual")
     // x = [1.5, 2.5] ; y = [6.53834, 7.85812] ; rho = [7, 8] ; theta = [1.20558, 1.38218]
     // [ctcpolar-2-end]
   }
+}
+
+TEST_CASE("CtcVisible - manual")
+{
+  {
+    // [ctcvisible-beg]
+    Vector a({1, 1});
+    Segment s({1, 4}, {3, 2});
+    CtcVisible ctc(a, s);
+    DefaultFigure::pave(
+      {{-1,6},{-1,6}},
+      ctc,
+      0.1
+    );
+    // [ctcvisible-end]
+  }
+
+  {
+    // [ctcnovisible-beg]
+    Vector a({1, 1});
+    Segment s({1, 4}, {3, 2});
+    CtcNoVisible ctc(a, s);
+    DefaultFigure::pave(
+      {{-1,6},{-1,6}},
+      ctc,
+      0.1
+    );
+    // [ctcnovisible-end]
+  }
+
+  {
+    // [sepvisible_list-begin]
+    Vector a({1, 1});
+    std::vector<Segment> l = {{{1,4}, {2, 3}}, {{2, 3}, {2.5,1}}, {{4, 0.5}, {3.5, -0.5}}};
+    SepVisible sep(a, l);
+    DefaultFigure::pave(
+      {{-1,6},{-1,6}},
+      sep,
+      1e-1
+    );
+    // [sepvisible_list-end]
+  }
+
+  {
+    // [sepvisible_polygon-begin]
+    Vector a({1, 1});
+    Polygon p({{2.5,3}, {2, 2}, {3,1}, {4, 1.5}, {4, 3}});
+    SepVisible sep(a, p);
+    DefaultFigure::pave(
+      {{-1,6},{-1,6}},
+      sep,
+      1e-1
+    );
+    // [sepvisible_polygon-end]
+  }
 }