[graphics] Solving minor graphical issues & improving documentation

.gitignore

@@ -69,6 +69,10 @@ wheelhouse/
 
 # Graphics files
 examples/**/*.xml
+examples/**/*.bmp
+examples/**/*.png
+examples/**/*.jpg
+examples/**/*.svg
 *.ipe
 
 # Matlab files

doc/manual/manual/extensions/capd/capd.rst

@@ -11,6 +11,7 @@ To use CAPD with Codac, you first need to install the CAPD library. You can find
 
 Note that as CAPD is a C++ only library, the content present in this page is **only available in C++**.
 
+.. _subsec-extensions-capd-capd-install:
 
 Installing the ``codac-capd`` extension
 ---------------------------------------

doc/manual/manual/extensions/capd/peibos_capd.rst

@@ -31,7 +31,7 @@ The PEIBOS function takes at least six arguments :
 - The final time for the integration of the ODE.
 - A timestep to get intermediate states.
 - The inverse chart for the gnomonic atlas (an analytic function).
-- The list of symmetries for the gnomonic atlas. Note that each symmetry is represented as a hyperoctahedral symmetry, see :ref:`sec-actions-octasym`.
+- The list of symmetries for the gnomonic atlas. Note that each symmetry is represented as a hyperoctahedral symmetry, see :ref:`sec-tools-octasym`.
 - A resolution :math:`\epsilon`. The initial box :math:`\left[-1,1\right]^m` will initiallly be splitted in boxes with a diameter smaller than :math:`\epsilon`.
 - Eventually an offset vector can be specified if the initial set is not centered around the origin.
 - Eventually a flag can be set to True to get the verbose.

doc/manual/manual/functions/peibos/peibos.rst

@@ -13,6 +13,7 @@ Let us consider an initial set :math:`\mathbb{X}_0 \subset \mathbb{R}^n` with it
 Considering a function :math:`\mathbf{f}:\mathbb{R}^n \to \mathbb{R}^p`, :math:`n \leq p`, the PEIBOS tool allows to compute the set :math:`\mathbf{Y}=\left\{ \mathbf{f}(\mathbf{x}) \mid \mathbf{x} \in \partial \mathbb{X}_0 \right\}`.
 
 .. _subsec-functions-peibos-gnomonic-atals:
+
 Gnomonic atlas
 --------------
 
@@ -60,7 +61,7 @@ The PEIBOS function takes at least four arguments :
 
 - The studied analytic function.
 - The inverse chart for the gnomonic atlas (an analytic function).
-- The list of symmetries for the gnomonic atlas. Note that each symmetry is represented as a hyperoctahedral symmetry, see :ref:`sec-actions-octasym`.
+- The list of symmetries for the gnomonic atlas. Note that each symmetry is represented as a hyperoctahedral symmetry, see :ref:`sec-tools-octasym`.
 - A resolution :math:`\epsilon`. The initial box :math:`\left[-1,1\right]^m` will initiallly be splitted in boxes with a diameter smaller than :math:`\epsilon`.
 - Eventually an offset vector can be specified if the initial set is not centered around the origin.
 - Eventually a flag can be set to True to get the verbose.

doc/manual/manual/visualization/2d_example.rst

@@ -0,0 +1,10 @@
+.. _sec-graphics-2d-example:
+
+2D graphical example
+====================
+
+Below is an example covering a wide variety of drawing functions, colors, styles etc.
+
+* `Python version <https://github.com/codac-team/codac/blob/codac2/examples/00_graphics/graphic_examples.py>`_
+* `C++ version <https://github.com/codac-team/codac/blob/codac2/examples/00_graphics/graphic_examples.cpp>`_
+* `Matlab version <https://github.com/codac-team/codac/blob/codac2/examples/00_graphics/graphic_examples.m>`_

doc/manual/manual/visualization/3d_example.rst

@@ -0,0 +1,11 @@
+.. _sec-graphics-3d-example:
+
+3D graphical example
+====================
+
+Below is an example covering a wide variety of drawing functions, colors, styles etc.
+
+* `Python version <https://github.com/codac-team/codac/blob/codac2_dev/examples/06_graphics_3D/main.py>`_
+* `C++ version <https://github.com/codac-team/codac/blob/codac2_dev/examples/06_graphics_3D/main.cpp>`_
+* `Matlab version <https://github.com/codac-team/codac/blob/codac2_dev/examples/06_graphics_3D/main.m>`_
+

doc/manual/manual/visualization/3d_visualization.rst

@@ -36,86 +36,139 @@ Drawing functions
 Below are the detailled available drawing functions. The shapes that can be drawn are:
 
 Geometric shapes
-  - Triangle
-  - Parallelogram
-  - Star-shaped polygon
   - Box
-  - Parallelepiped
-  - Zonotope
+  - Sphere
   - Arrow
+  - Zonotope
+  - Parallelepiped
+  - Parallelogram
+  - Triangle
+  - Star-shaped polygon
   - Parametric surface
-  - Sphere
+
+Vehicles
+  - Car
+  - Plane
 
 Paving
   - PavingOut (Paving with contractors)
   - PavingInOut (Paving with separators)
   - Subpaving
 
-Vehicles
-  - Car
-  - Plane
-
-In addition, a function ``draw_axes`` is available to draw the three axes of the 3D space.
 
-.. doxygenfunction:: codac2::Figure3D::draw_axes(double)
-  :project: codac
 
 Note that only the stroke color is used in all of the supported drawing functions.
 
+In addition, a function ``draw_axes`` is available to draw the three axes of the 3D space. It can take two arguments :
+
+- float : the size of the axes
+- Vector : the origin of the axes
+
+
 Geometric shapes
 ----------------
 
-.. doxygenfunction:: codac2::Figure3D::draw_triangle(const Vector&, const Matrix&, const Vector&, const Vector&, const Vector&, const StyleProperties&)
-  :project: codac
+All the drawable geometric objects can take a last optionnal argument to set up their stroke color. 
+For further details, refer to :ref:`subsec-graphics-colors-style-properties`. 
 
-.. doxygenfunction:: codac2::Figure3D::draw_triangle(const Vector&, const Vector&, const Vector&, const StyleProperties&)
-  :project: codac
+The geometric shapes that can be drawn and their arguments are listed below :
+
+- draw_box
+
+  - IntervalVector : the box to draw
+
+- draw_sphere
+
+  - Vector : the center of the sphere
+  - Matrix : the scaling matrix
+
+- draw_arrow
+
+  - Vector : start of the arrow
+  - Matrix : orientation of the arrow (first column)
+
+- draw_zonotope
+
+  - Zonotope: the zonotope to draw
+
+- draw_parallelepiped
+
+  - Parallelepiped : the parallelepiped to draw
+
+- draw_parallelogram (defined by :math:`c + A (p + [-1,1]*v1 + [-1,1]*v2)`)
+
+  - Vector : c, the translation
+  - Matrix : A, the scaling
+  - Vector : p, base point
+  - Vector : v1, first generator
+  - Vector : v2, second generator
+
+- draw_triangle
+
+  - Vector : first point
+  - Vector : second point
+  - Vector : third point
+
+- draw_triangle
+
+  - Vector : translation applied to the triangle
+  - Matrix : scaling matrix applied to the triangle
+  - Vector : first point
+  - Vector : second point
+  - Vector : third point
 
 The ``draw_polygon`` can be used to draw a `star-shaped polygon <https://en.wikipedia.org/wiki/Star-shaped_polygon>`_ when the vectors are coplanar, and more
 generally a sequence of adjacent triangles sharing a same vertex.
 
-.. doxygenfunction:: codac2::Figure3D::draw_polygon(const Vector&, const Matrix&, const std::vector<Vector>&, const StyleProperties&)
-  :project: codac
+- draw_polygon
 
-.. doxygenfunction:: codac2::Figure3D::draw_box(const IntervalVector&, const StyleProperties&)
-  :project: codac
+  - Vector : translation applied to the polygon
+  - Matrix : scaling matrix applied to the polygon
+  - vector<Vector> : vector where each element is a point of the polygon to draw
 
-.. doxygenfunction:: codac2::Figure3D::draw_parallelogram(const Vector&, const Matrix&, const Vector&, const Vector&, const Vector&, const StyleProperties&)
-  :project: codac
+- draw_surface
 
-.. doxygenfunction:: codac2::Figure3D::draw_parallelepiped(const Parallelepiped&, const StyleProperties&)
-  :project: codac
+  - Vector : the translation applied to the surface
+  - Matrix : scaling applied to the surface
+  - Interval : bounds of p1
+  - double : incrementation for p1
+  - Interval : bounds of p2
+  - double : incrementation for p2
+  - function<double, double> -\> Vector : the function of the surface, linking each (p1,p2) to a 3D point
 
-.. doxygenfunction:: codac2::Figure3D::draw_zonotope(const Zonotope&, const StyleProperties&)
-  :project: codac
+Vehicles
+--------
 
-.. doxygenfunction:: codac2::Figure3D::draw_arrow(const Vector&, const Matrix& A, const StyleProperties&)
-  :project: codac
+All the drawable vehicles can take a last optionnal argument to set up their stroke color. 
+For further details, refer to :ref:`subsec-graphics-colors-style-properties`. 
 
-.. doxygenfunction:: codac2::Figure3D::draw_surface(const Vector&, const Matrix&, const Interval&, double, const Interval&, double, std::function<Vector(double,double)>, const StyleProperties&)
-  :project: codac
+The vehicles that can be drawn and their arguments are listed below :
 
-.. doxygenfunction:: codac2::Figure3D::draw_sphere(const Vector&, const Matrix&, const StyleProperties&)
-  :project: codac
+- draw_car
+
+  - Vector : center of the car
+  - Matrix : orientation of the car
+
+- draw_plane
+
+  - Vector : center of the plane
+  - Matrix : orientation of the plane
+  - bool : (optionnal) defines if the yaw axis is up, default to true
 
 Paving
 ------
 
-.. doxygenfunction:: codac2::Figure3D::draw_paving(const PavingOut& p, const StyleProperties&)
-  :project: codac
+When a paving is drawn, only the inside and boundary boxes are drawn. This is done to avoid outside boxes masking them.
 
-.. doxygenfunction:: codac2::Figure3D::draw_paving(const PavingInOut& p, const StyleProperties&, const StyleProperties&)
-  :project: codac
+If only one type of paving is drawn (for example a paving with contractors), only one :ref:`subsec-graphics-colors-style-properties` can be defined to choose its edge color.
+If two types are drawn (boundary and inside), two :ref:`subsec-graphics-colors-style-properties` can be passed to select both colors.
 
-.. doxygenfunction:: codac2::Figure3D::draw_subpaving(const Subpaving<P>&, const StyleProperties&)
-  :project: codac
+The paving that can be drawn and their arguments are listed below :
 
-Vehicles
---------
+- draw_paving
 
-.. doxygenfunction:: codac2::Figure3D::draw_car(const Vector&, const Matrix&, const StyleProperties&)
-  :project: codac
+  - PavingOut | PavingInOut : the paving to draw
 
-.. doxygenfunction:: codac2::Figure3D::draw_plane(const Vector&, const Matrix&, bool, const StyleProperties&)
-  :project: codac
+- draw_subpaving
 
+  - Subpaving : the subpaving to draw

doc/manual/manual/visualization/colors.rst

@@ -128,7 +128,7 @@ Additionnal methods are available for any useful purpose:
     fig.draw_box(IntervalVector({{2.6,3.1},{2.6,3.1}}),StyleProperties({Color({108,90,78},Model().HSV),Color({108,90,78,20},Model().HSV)}));
 
 
-
+.. _subsec-graphics-colors-style-properties:
 StyleProperties
 ---------------
 
@@ -208,6 +208,48 @@ For more information, see :ref:`subsec-graphics-colors-optional-arguments`.
     fig.draw_box(IntervalVector({{2,5},{2,5}}), StyleProperties(Color().red(), "..", "layer1", "w:0.1", "z:1.5"));
     % Red edge, dotted line, line width of 0.1, z-value of 1.5 and on layer1
 
+.. _subsec-graphics-colors-paving-style:
+Paving style
+------------
+
+To change the color used to draw a paving, the ``draw_paving`` functions can take an optional argument which is the ``PavingStyle``.
+Predefined styles are
+
+- blue_green (default_style)
+- blue_white
+- blue_pink
+- black_white
+
+A custom ``PavingStyle`` can also be created from three ``StyleProperties`` : the boundary, the outside and the inside. 
+Below is an example of the different possibilities.
+
+.. tabs::
+
+  .. code-tab:: py
+
+    DefaultFigure.draw_paving(p)  # default style, blue_green
+    DefaultFigure.draw_paving(p,PavingStyle.blue_pink())  #blue_pink style
+    # orange boundary, purple outside and blue inside
+    paving_style = PavingStyle([Color.dark_orange(),Color.orange()],[Color.dark_purple(),Color.purple()],[Color.dark_blue(),Color.blue()])
+    DefaultFigure.draw_paving(p,paving_style)
+
+
+
+  .. code-tab:: c++
+
+    DefaultFigure::draw_paving(p);
+    DefaultFigure::draw_paving(p,PavingStyle::blue_pink());
+    // orange boundary, purple outside and blue inside
+    PavingStyle paving_style ({Color::dark_orange(),Color::orange()},{Color::dark_purple(),Color::purple()},{Color::dark_blue(),Color::blue()});
+    DefaultFigure::draw_paving(p,paving_style);
+
+  .. code-tab:: matlab
+
+    DefaultFigure().draw_paving(p);
+    DefaultFigure().draw_paving(p,PavingStyle().blue_pink());
+    % orange boundary, purple outside and blue inside
+    paving_style = PavingStyle(StyleProperties({Color().dark_orange(),Color().orange()}),StyleProperties({Color().dark_purple(),Color().purple()}),StyleProperties({Color().dark_blue(),Color().blue()}));
+    DefaultFigure().draw_paving(p,paving_style);
 
 Color maps
 ----------
@@ -299,6 +341,7 @@ You can also create your own color map :
 
 Note that you can add RGB and HSV colors to the same color map. The model of the color map will define the interpolation space.
 
+.. _subsec-graphics-colors-style-gradient-properties:
 StyleGradientProperties
 -----------------------
 

doc/manual/manual/visualization/figures.rst

@@ -156,4 +156,5 @@ VIBes only
 Some methods are exclusive to the real-time display with VIBes :
 
 - center_viewbox : takes two Vector as arguments, the center and radius of each axis
-- auto_scale : takes no argument, the figure will be automatically scaled to fit the window
+- auto_scale : takes no argument, the figure will be automatically scaled to fit the window
+- save : takes the name of the file as argument and saves the current state of the VIBes window to the file. Allowed formats are png, jpg, bmp and svg.