Merge pull request #11478 from pieterhijma/missing-api-doc-py-hlr

[Part] Missing API documentaton Python HLR

src/Mod/Part/App/HLRBRep/HLRBRep_AlgoPy.xml

@@ -14,93 +14,171 @@
       Delete="false">
     <Documentation>
           <Author Licence="LGPL" Name="Werner Mayer" EMail="wmayer[at]users.sourceforge.net" />
-          <UserDocu>Describes functions to use HLR algorithm.</UserDocu>
+          <UserDocu>Algo() -> HLRBRep_Algo
+
+A framework to compute a shape as seen in a projection
+plane. This is done by calculating the visible and the hidden parts
+of the shape. HLRBRep_Algo works with three types of entity:
+
+- shapes to be visualized
+- edges in these shapes (these edges are the basic entities which will be
+  visualized or hidden), and
+- faces in these shapes which hide the edges.
+
+HLRBRep_Algo is based on the principle of comparing each edge of the shape to
+be visualized with each of its faces, and calculating the visible and the
+hidden parts of each edge. For a given projection, HLRBRep_Algo calculates a
+set of lines characteristic of the object being represented. It is also used in
+conjunction with the HLRBRep_HLRToShape extraction utilities, which reconstruct
+a new, simplified shape from a selection of calculation results. This new shape
+is made up of edges, which represent the shape visualized in the
+projection. HLRBRep_Algo takes the shape itself into account whereas
+HLRBRep_PolyAlgo works with a polyhedral simplification of the shape. When you
+use HLRBRep_Algo, you obtain an exact result, whereas, when you use
+HLRBRep_PolyAlgo, you reduce computation time but obtain polygonal segments. In
+the case of complicated shapes, HLRBRep_Algo may be time-consuming. An
+HLRBRep_Algo object provides a framework for:
+
+- defining the point of view
+- identifying the shape or shapes to be visualized
+- calculating the outlines
+- calculating the visible and hidden lines of the shape. Warning
+- Superimposed lines are not eliminated by this algorithm.
+- There must be no unfinished objects inside the shape you wish to visualize.
+- Points are not treated.
+- Note that this is not the sort of algorithm used in generating shading, which
+  calculates the visible and hidden parts of each face in a shape to be
+  visualized by comparing each face in the shape with every other face in the
+  same shape.
+	  </UserDocu>
     </Documentation>
     <Methode Name="add">
         <Documentation>
-            <UserDocu>
+            <UserDocu>add(S, nbIso=0)
+
+Adds the shape S to this framework, and specifies the number of isoparameters
+nbiso desired in visualizing S.  You may add as many shapes as you wish.  Use
+the function add once for each shape.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="remove">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>remove(i)
+
+Remove the shape of index i from this framework.
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="index">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>index(S) ->  int
+
+Return the index of the Shape S and return 0 if the Shape S is not found.
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="outLinedShapeNullify">
         <Documentation>
-            <UserDocu>
+            <UserDocu>outlinedShapeNullify()
+
+Nullify all the results of OutLiner from HLRTopoBRep.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="setProjector" Keyword="true">
         <Documentation>
-            <UserDocu>
+            <UserDocu>setProjector(Origin=(0, 0, 0), ZDir=(0,0,0), XDir=(0,0,0), focus=NaN)
+
+Set the projector.  With focus left to NaN, an axonometric projector is
+created.  Otherwise, a perspective projector is created with focus focus.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="nbShapes">
         <Documentation>
-            <UserDocu>
+            <UserDocu>nbShapes()
+
+Returns the number of shapes in the collection.  It does not modify the
+object's state and is used to retrieve the count of shapes.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="showAll">
         <Documentation>
-            <UserDocu>
+            <UserDocu>showAll(i=-1)
+
+If i &lt; 1, then set all the edges to visible.
+Otherwise, set to visible all the edges of the shape of index i.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="hide">
         <Documentation>
-            <UserDocu>
+            <UserDocu>hide(i=-1, j=-1)
+
+If i &lt; 1, hide all of the datastructure.
+Otherwise, if j &lt; 1, hide the shape of index i.
+Otherwise, hide the shape of index i by the shape of index j.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="hideAll">
         <Documentation>
-            <UserDocu>
+            <UserDocu>hideAll(i=-1)
+
+If i &lt; 1, hide all the edges.
+Otherwise, hide all the edges of shape of index i.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="partialHide">
         <Documentation>
-            <UserDocu>
+            <UserDocu>partialHide()
+
+Own hiding of all the shapes of the DataStructure without hiding by each other.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="select">
         <Documentation>
-            <UserDocu>
+            <UserDocu>select(i=-1)
+
+If i &lt; 1, select all the DataStructure.
+Otherwise, only select the shape of index i.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="selectEdge">
         <Documentation>
-            <UserDocu>
+            <UserDocu>selectEdge(i)
+
+Select only the edges of the shape of index i.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="selectFace">
         <Documentation>
-            <UserDocu>
+            <UserDocu>selectFace(i)
+		
+Select only the faces of the shape of index i.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="initEdgeStatus">
         <Documentation>
-            <UserDocu>
+            <UserDocu>initEdgeStatus()
+
+Init the status of the selected edges depending of the back faces of a closed
+shell.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="update">
         <Documentation>
-            <UserDocu>
+            <UserDocu>update()
+		
+Update the DataStructure.
             </UserDocu>
         </Documentation>
     </Methode>

src/Mod/Part/App/HLRBRep/HLRBRep_PolyAlgoPy.xml

@@ -14,102 +14,164 @@
       Delete="false">
     <Documentation>
           <Author Licence="LGPL" Name="Werner Mayer" EMail="wmayer[at]users.sourceforge.net" />
-          <UserDocu>Describes functions to use HLR algorithm.</UserDocu>
+          <UserDocu>PolyAlgo() -> HLRBRep_PolyAlgo
+
+A framework to compute the shape as seen in a projection
+plane. This is done by calculating the visible and the hidden parts of the
+shape. HLRBRep_PolyAlgo works with three types of entity:
+
+- shapes to be visualized (these shapes must have already been triangulated.)
+- edges in these shapes (these edges are defined as polygonal lines on the
+  triangulation of the shape, and are the basic entities which will be visualized
+  or hidden), and
+- triangles in these shapes which hide the edges.
+
+HLRBRep_PolyAlgo is based on the principle of comparing each edge of the shape
+to be visualized with each of the triangles produced by the triangulation of
+the shape, and calculating the visible and the hidden parts of each edge. For a
+given projection, HLRBRep_PolyAlgo calculates a set of lines characteristic of
+the object being represented. It is also used in conjunction with the
+HLRBRep_PolyHLRToShape extraction utilities, which reconstruct a new,
+simplified shape from a selection of calculation results. This new shape is
+made up of edges, which represent the shape visualized in the
+projection. HLRBRep_PolyAlgo works with a polyhedral simplification of the
+shape whereas HLRBRep_Algo takes the shape itself into account. When you use
+HLRBRep_Algo, you obtain an exact result, whereas, when you use
+HLRBRep_PolyAlgo, you reduce computation time but obtain polygonal segments. An
+HLRBRep_PolyAlgo object provides a framework for:
+
+- defining the point of view
+- identifying the shape or shapes to be visualized
+- calculating the outlines
+- calculating the visible and hidden lines of the shape. Warning
+- Superimposed lines are not eliminated by this algorithm.
+- There must be no unfinished objects inside the shape you wish to visualize.
+- Points are not treated.
+- Note that this is not the sort of algorithm used in generating shading, which
+  calculates the visible and hidden parts of each face in a shape to be
+  visualized by comparing each face in the shape with every other face in the
+  same shape.
+
+	  </UserDocu>
     </Documentation>
     <Methode Name="load">
         <Documentation>
-            <UserDocu>
+            <UserDocu>load(S)
+
+Loads the shape S into this framework. Warning S must have already been triangulated.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="remove">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>remove(i)
+
+Remove the shape of index i from this framework.
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="nbShapes">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>nbShapes()
+
+Returns the number of shapes in the collection.  It does not modify the
+object's state and is used to retrieve the count of shapes.
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="shape">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>shape(i) -> TopoShape
+
+Return the shape of index i.
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="index">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>index(S) ->  int
+
+Return the index of the Shape S.
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="setProjector" Keyword="true">
         <Documentation>
-            <UserDocu>
+            <UserDocu>setProjector(Origin=(0, 0, 0), ZDir=(0,0,0), XDir=(0,0,0), focus=NaN)
+
+Set the projector.  With focus left to NaN, an axonometric projector is
+created.  Otherwise, a perspective projector is created with focus focus.
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="update">
         <Documentation>
-            <UserDocu>
-            </UserDocu>
+            <UserDocu>update()
+
+Launches calculation of outlines of the shape visualized by this
+framework. Used after setting the point of view and defining the shape or
+shapes to be visualized.
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="initHide">
-        <Documentation>
-            <UserDocu>
+        <Documentation><!-- OCCT has no further documentation -->
+            <UserDocu>initHide()
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="moreHide">
-        <Documentation>
-            <UserDocu>
+        <Documentation><!-- OCCT has no further documentation -->
+            <UserDocu>moreHide()
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="nextHide">
-        <Documentation>
-            <UserDocu>
+        <Documentation><!-- OCCT has no further documentation -->
+            <UserDocu>nextHide()
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="initShow">
-        <Documentation>
-            <UserDocu>
+        <Documentation><!-- OCCT has no further documentation -->
+            <UserDocu>initShow()
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="moreShow">
-        <Documentation>
-            <UserDocu>
+        <Documentation><!-- OCCT has no further documentation -->
+            <UserDocu>moreShow()
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="nextShow">
-        <Documentation>
-            <UserDocu>
+        <Documentation><!-- OCCT has no further documentation -->
+            <UserDocu>nextShow()
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="outLinedShape">
         <Documentation>
-            <UserDocu>
+            <UserDocu>outLinedShape(S) -> TopoShape
+
+Make a shape with the internal outlines in each face of shape S.
             </UserDocu>
         </Documentation>
     </Methode>
     <Attribute Name="Angle">
-        <Documentation>
+        <Documentation><!-- OCCT has no further documentation -->
             <UserDocu></UserDocu>
         </Documentation>
         <Parameter Name="Angle" Type="Float"/>
     </Attribute>
     <Attribute Name="TolAngular">
-        <Documentation>
+        <Documentation><!-- OCCT has no further documentation -->
             <UserDocu></UserDocu>
         </Documentation>
         <Parameter Name="TolAngular" Type="Float"/>
     </Attribute>
     <Attribute Name="TolCoef">
-        <Documentation>
+        <Documentation><!-- OCCT has no further documentation -->
             <UserDocu></UserDocu>
         </Documentation>
         <Parameter Name="TolCoef" Type="Float"/>

src/Mod/Part/App/HLRBRep/HLRBRep_PolyAlgoPyImp.cpp

@@ -86,7 +86,7 @@ PyObject* HLRBRep_PolyAlgoPy::setProjector(PyObject *args, PyObject *kwds)
     PyObject* xd = nullptr;
     double focus = std::numeric_limits<double>::quiet_NaN();
 
-    static const std::array<const char *, 4> kwlist {"Origin", "ZDir", "XDir", nullptr};
+    static const std::array<const char *, 5> kwlist {"Origin", "ZDir", "XDir", "focus", nullptr};
     if (Base::Wrapped_ParseTupleAndKeywords(args, kwds, "|O!O!O!d", kwlist,
                                             &Base::VectorPy::Type, &ps,
                                             &Base::VectorPy::Type, &zd,

src/Mod/Part/App/HLRBRep/HLRToShapePy.xml

@@ -14,75 +14,140 @@
       Delete="true">
     <Documentation>
           <Author Licence="LGPL" Name="Werner Mayer" EMail="wmayer[at]users.sourceforge.net" />
-          <UserDocu>Describes functions to use HLR algorithm.</UserDocu>
+          <UserDocu>HLRToShape(algo: HLRBRep_Algo) -> HLRBRep_HLRToShape
+
+A framework for filtering the computation results of an HLRBRep_Algo algorithm
+by extraction. From the results calculated by the algorithm on a shape, a
+filter returns the type of edge you want to identify. You can choose any of the
+following types of output:
+- visible sharp edges
+- hidden sharp edges
+- visible smooth edges
+- hidden smooth edges
+- visible sewn edges
+- hidden sewn edges
+- visible outline edges
+- hidden outline edges
+- visible isoparameters and
+- hidden isoparameters.
+
+Sharp edges present a C0 continuity (non G1). Smooth edges present a G1
+continuity (non G2). Sewn edges present a C2 continuity. The result is composed
+of 2D edges in the projection plane of the view which the algorithm has worked
+with. These 2D edges are not included in the data structure of the visualized
+shape. In order to obtain a complete image, you must combine the shapes given
+by each of the chosen filters. The construction of the shape does not call a
+new computation of the algorithm, but only reads its internal results. The
+methods of this shape are almost identic to those of the HLRBrep_PolyHLRToShape
+class.
+	  </UserDocu>
     </Documentation>
     <Methode Name="vCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>vCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for visible sharp edges for either shape Shape or
+for all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="Rg1LineVCompound">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>Rg1LineVCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for visible smooth edges for either shape Shape or
+for all added shapes (Shape=None).
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="RgNLineVCompound">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>RgNLineVCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for visible sewn edges for either shape Shape or for
+all added shapes (Shape=None).
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="outLineVCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>outLineVCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for visible outline edges for either shape Shape or
+for all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="outLineVCompound3d">
         <Documentation>
-            <UserDocu>
+            <UserDocu>outLineVCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for visible outline edges in 3D for either shape
+Shape or for all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="isoLineVCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>isoLineVCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for visible isoparameters for either shape Shape or
+for all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="hCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>hCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for hidden sharp edges for either shape Shape or for
+all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="Rg1LineHCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>Rg1LineHCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for hidden smooth edges for either shape Shape or
+for all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="RgNLineHCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>RgNLineHCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for hidden sewn edges for either shape Shape or for
+all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="outLineHCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>outLineHCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for hidden outline edges for either shape Shape or
+for all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="isoLineHCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>isoLineHCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for hidden isoparameters for either shape Shape or
+for all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="compoundOfEdges" Keyword="true">
         <Documentation>
-            <UserDocu>
+            <UserDocu>compoundOfEdges(Type: int, Visible: bool, In3D: bool, Shape=None) -> TopoShape
+
+Returns compound of resulting edges of required type and visibility, taking
+into account the kind of space (2d or 3d).  If Shape=None, return it for all
+added shapes, otherwise return it for shape Shape.
             </UserDocu>
         </Documentation>
     </Methode>

src/Mod/Part/App/HLRBRep/PolyHLRToShapePy.xml

@@ -14,69 +14,119 @@
       Delete="true">
     <Documentation>
           <Author Licence="LGPL" Name="Werner Mayer" EMail="wmayer[at]users.sourceforge.net" />
-          <UserDocu>Describes functions to use HLR algorithm.</UserDocu>
+          <UserDocu>PolyHLRToShape(algo: HLRBRep_PolyAlgo) -> HLRBRep_PolyHLRToShape
+
+A framework for filtering the computation results of an HLRBRep_PolyAlgo
+algorithm by extraction.  From the results calculated by the algorithm on a
+shape, a filter returns the type of edge you want to identify.  You can choose
+any of the following types of output:
+- visible sharp edges
+- hidden sharp edges
+- visible smooth edges
+- hidden smooth edges
+- visible sewn edges
+- hidden sewn edges
+- visible outline edges
+- hidden outline edges
+- visible isoparameters and
+- hidden isoparameters.
+
+Sharp edges present a C0 continuity (non G1). Smooth edges present a G1
+continuity (non G2). Sewn edges present a C2 continuity. The result is composed
+of 2D edges in the projection plane of the view which the algorithm has worked
+with. These 2D edges are not included in the data structure of the visualized
+shape. In order to obtain a complete image, you must combine the shapes given
+by each of the chosen filters. The construction of the shape does not call a
+new computation of the algorithm, but only reads its internal results.
+	  </UserDocu>
     </Documentation>
     <Methode Name="update">
-        <Documentation>
-            <UserDocu>
+        <Documentation><!-- OCCT has no further documentation -->
+            <UserDocu>update(algo: HLRBRep_PolyAlgo)
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="show">
-        <Documentation>
-            <UserDocu>
+        <Documentation><!-- OCCT has no further documentation -->
+            <UserDocu>show()
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="hide">
-        <Documentation>
-            <UserDocu>
+        <Documentation><!-- OCCT has no further documentation -->
+            <UserDocu>hide()
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="vCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>vCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for visible sharp edges for either shape Shape or
+for all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="Rg1LineVCompound">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>Rg1LineVCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for visible smooth edges for either shape Shape or
+for all added shapes (Shape=None).
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="RgNLineVCompound">
         <Documentation>
-            <UserDocu></UserDocu>
+            <UserDocu>RgNLineVCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for visible sewn edges for either shape Shape or for
+all added shapes (Shape=None).
+	    </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="outLineVCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>outLineVCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for visible outline edges for either shape Shape or
+for all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="hCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>hCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for hidden sharp edges for either shape Shape or for
+all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="Rg1LineHCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>Rg1LineHCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for hidden smooth edges for either shape Shape or
+for all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="RgNLineHCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>RgNLineHCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for hidden sewn edges for either shape Shape or for
+all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>
     <Methode Name="outLineHCompound">
         <Documentation>
-            <UserDocu>
+            <UserDocu>outLineHCompound(Shape=None) -> TopoShape
+
+Sets the extraction filter for hidden outline edges for either shape Shape or
+for all added shapes (Shape=None).
             </UserDocu>
         </Documentation>
     </Methode>