From 42c5470ae5b1b735388a8f235a00ae0707b349d5 Mon Sep 17 00:00:00 2001 From: skv Date: Wed, 3 Aug 2016 21:19:48 +0300 Subject: [PATCH] 0023309: [EDF 12969] Clarify sorting algorithm of SubShapeAllSortedCentres function --- doc/salome/gui/GEOM/input/faq.doc | 1 + .../gui/GEOM/input/tui_sorting_shapes.doc | 78 +++++++++++++++++++ src/GEOM_SWIG/geomBuilder.py | 10 ++- 3 files changed, 86 insertions(+), 3 deletions(-) create mode 100644 doc/salome/gui/GEOM/input/tui_sorting_shapes.doc diff --git a/doc/salome/gui/GEOM/input/faq.doc b/doc/salome/gui/GEOM/input/faq.doc index 3976f44ea..11daeb882 100644 --- a/doc/salome/gui/GEOM/input/faq.doc +++ b/doc/salome/gui/GEOM/input/faq.doc @@ -7,6 +7,7 @@ Here you can find the answers to some frequently asked questions: diff --git a/doc/salome/gui/GEOM/input/tui_sorting_shapes.doc b/doc/salome/gui/GEOM/input/tui_sorting_shapes.doc new file mode 100644 index 000000000..a97b9a4f0 --- /dev/null +++ b/doc/salome/gui/GEOM/input/tui_sorting_shapes.doc @@ -0,0 +1,78 @@ +/*! + +\page sorting_shapes_page Sorting Shapes Algorithm + +Some algorithms of GEOM module return a list of shapes sorted in accordance +with some criterion. The goal of this sorting is a possibility to obtain +stable result regardless SALOME version being used. + +The algorithm that provides such a possibility consists of the following steps: + +
    +
  1. For each shape a pair of point and number is associated. The point and + number depend on the shape type: + + + + + + + + + + + + + + + + + + + + + + + + +
    Shape TypePointNumber
    VertexVertex isselfOrientation value converted to double
    Edge, WireCenter of massTotal length of edges
    Face, ShellCenter of massTotal area of faces
    OtherCenter of massTotal volume of solids
    +
    2. +
  2. Each point is converted to double using the following expression: + \code point.X() * 999.0 + point.Y() * 99.0 + point.Z() * 0.9 \endcode +
    3. +
  3. The shapes are sorted in ascending order. The shape comparison criterion + is the following. Shape_1 is considered less then Shape_2 if: +
      +
    • Shape_1's double value obtained on the step 2 is less than + the corresponding value of Shape_2.
      + \b Otherwise if they are equal with the confusion tolerance (1.e-7): +
      • +
    • Shape_1's number obtained on the step 1 is less than the + corresponding number of Shape_2.
      + \b Otherwise if they are equal with the confusion tolerance (1.e-7) + and the shapes have either Face or more complex type: +
      • +
    • Shape_1's squared diagonal of bounding box is less than the one + of Shape_2.
      + \b Otherwise if they are equal with the confusion tolerance (1.e-7): +
      • +
    • Get the minimal and maximal values of X, Y and Z coordinates + of bounding boxes for Shape_1 and Shape_2. Compute the following + values for Shape_1 and Shape_2: + \code (aXmin+aXmax) * 999.0 + (aYmin+aYmax) * 99.0 + (aZmin+aZmax) * 0.9 \endcode + Shape_1 is less than Shape_2 if this value for Shape_1 is less + than the value for Shape_2. +
      • +
    +
    4. +
+ +This algorithm is used in the following \ref geomBuilder.geomBuilder "geomBuilder" methods: +- \ref SubShapeAllSortedCentres +- \ref SubShapeAllSortedCentresIDs +- \ref SubShapeSortedCentres +- \ref ExtractShapes + +and as a part of some other algorithms where sorting is required. + +*/ diff --git a/src/GEOM_SWIG/geomBuilder.py b/src/GEOM_SWIG/geomBuilder.py index a54af471d..54b41f5f6 100644 --- a/src/GEOM_SWIG/geomBuilder.py +++ b/src/GEOM_SWIG/geomBuilder.py @@ -6383,7 +6383,8 @@ class geomBuilder(object, GEOM._objref_GEOM_Gen): ## Explode a shape on sub-shapes of a given type. # Sub-shapes will be sorted taking into account their gravity centers, - # to provide stable order of sub-shapes. + # to provide stable order of sub-shapes. Please see + # @ref sorting_shapes_page "Description of Sorting Shapes Algorithm". # If the shape itself matches the type, it is also returned. # @param aShape Shape to be exploded. # @param aType Type of sub-shapes to be retrieved (see ShapeType()) @@ -6420,7 +6421,8 @@ class geomBuilder(object, GEOM._objref_GEOM_Gen): ## Explode a shape on sub-shapes of a given type. # Sub-shapes will be sorted taking into account their gravity centers, - # to provide stable order of sub-shapes. + # to provide stable order of sub-shapes. Please see + # @ref sorting_shapes_page "Description of Sorting Shapes Algorithm". # @param aShape Shape to be exploded. # @param aType Type of sub-shapes to be retrieved (see ShapeType()) # @return List of IDs of sub-shapes. @@ -6446,6 +6448,7 @@ class geomBuilder(object, GEOM._objref_GEOM_Gen): ## Obtain a compound of sub-shapes of aShape, # selected by they indices in sorted list of all sub-shapes of type aType. + # Please see @ref sorting_shapes_page "Description of Sorting Shapes Algorithm". # Each index is in range [1, Nb_Sub-Shapes_Of_Given_Type] # @param aShape Shape to get sub-shape of. # @param ListOfInd List of sub-shapes indices. @@ -6486,7 +6489,8 @@ class geomBuilder(object, GEOM._objref_GEOM_Gen): ## Extract shapes (excluding the main shape) of given type. # @param aShape The shape. # @param aType The shape type (see ShapeType()) - # @param isSorted Boolean flag to switch sorting on/off. + # @param isSorted Boolean flag to switch sorting on/off. Please see + # @ref sorting_shapes_page "Description of Sorting Shapes Algorithm". # @param theName Object name; when specified, this parameter is used # for result publication in the study. Otherwise, if automatic # publication is switched on, default value is used for result name. -- 2.39.2