[bos #35160][EDF](2023-T1) Keyboard shortcuts.

[modules/geom.git] / src / GEOM_PY / geomtools.py

diff --git a/src/GEOM_PY/geomtools.py b/src/GEOM_PY/geomtools.py
index 5a2062330f1375904df887b31a7570d96a071240..f5c61f2460052a4fd1be7a2ccf37097736873dbf 100644 (file)
--- a/src/GEOM_PY/geomtools.py
+++ b/src/GEOM_PY/geomtools.py
@@ -1,11 +1,11 @@
 # -*- coding: utf-8 -*-
 #
 # -*- coding: utf-8 -*-
 #

-# Copyright (C) 2007-2012  CEA/DEN, EDF R&D, OPEN CASCADE
+# Copyright (C) 2007-2024  CEA, EDF, OPEN CASCADE

 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
 # License as published by the Free Software Foundation; either
 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
 # License as published by the Free Software Foundation; either

-# version 2.1 of the License.
+# version 2.1 of the License, or (at your option) any later version.

 #
 # This library is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 #
 # This library is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of


@@ -18,6 +18,14 @@
 #
 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
 #
 #
 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
 #

+
+## \defgroup geomtools geomtools - Tools to access GEOM engine and objects 
+#  \{ 
+#  \details
+#  This module provides tools to facilitate the use of geom engine and geom
+#  objects in Salome.
+#  \}
+

 """
 This module provides tools to facilitate the use of geom engine and geom
 objects in Salome.
 """
 This module provides tools to facilitate the use of geom engine and geom
 objects in Salome.


@@ -30,40 +38,29 @@ from salome.kernel.logger import Logger
 from salome.kernel import termcolor
 logger = Logger("salome.geom.geomtools", color = termcolor.RED)
 
 from salome.kernel import termcolor
 logger = Logger("salome.geom.geomtools", color = termcolor.RED)
 

-from salome.kernel.studyedit import getActiveStudyId, getStudyEditor
+from salome.kernel.studyedit import getStudyEditor

 from salome.kernel.services import IDToObject, IDToSObject
 from salome.kernel.services import IDToObject, IDToSObject

+from salome.kernel.deprecation import is_called_by_sphinx
+from salome.geom import geomBuilder
+

 try:
 try:

-    from salome.gui import helper as guihelper
+    if not is_called_by_sphinx():
+        from salome.gui import helper as guihelper
+        pass
+    pass

 except:
     pass
 
 except:
     pass
 

-_geompys = {}
+_geompy = geomBuilder.New()

 
 

-def getGeompy(studyId = None):
+## Return an object behaving exactly like geompy module.
+#  \ingroup geomtools
+def getGeompy():

     """
     """

-    Return an object behaving exactly like geompy module, except that it is
-    associated with the study `studyId`. If `studyId` is :const:`None`, return
-    a pseudo geompy object for the current study.
+    Return an object behaving exactly like geompy module.

     """
     """

-    # We can't use geompy module because it initializes GEOM with
-    # salome.myStudy, which may not exist. So we use this trick to create
-    # a pseudo geompy module. 

     salome.salome_init()
     salome.salome_init()

-    if studyId is None:
-        studyId = getActiveStudyId()
-    if not _geompys.has_key(studyId):
-        import geompyDC
-        _geompys[studyId] = salome.lcc.FindOrLoadComponent("FactoryServer",
-                                                           "GEOM")
-        _geompys[studyId].ShapeType = geompyDC.ShapeType
-        _geompys[studyId].GEOM = geompyDC.GEOM
-        _geompys[studyId].kind = geompyDC.kind
-        _geompys[studyId].info = geompyDC.info
-        _geompys[studyId].PackData = geompyDC.PackData
-        _geompys[studyId].ReadTexture = geompyDC.ReadTexture
-        study = salome.myStudyManager.GetStudyByID(studyId)
-        _geompys[studyId].init_geom(study)
-    return _geompys[studyId]
+    return _geompy

 
 
 ModeWireFrame = 0
 
 
 ModeWireFrame = 0


@@ -71,6 +68,16 @@ ModeShading = 1
 DisplayMode=ModeShading
 PreviewColor=[236,163,255]
 
 DisplayMode=ModeShading
 PreviewColor=[236,163,255]
 

+## This class provides several methods to manipulate geom objects in Salome study. 
+#  The parameter <em>studyEditor</em> defines a \b StudyEditor
+#  object used to access the study. If \b None, the method returns a 
+#  \b StudyEditor object on the current study.
+#
+#  \b editor  
+# 
+#  This instance attribute contains the underlying \b StudyEditor object. 
+#  It can be used to access the study but the attribute itself should not be modified.
+#  \ingroup geomtools

 class GeomStudyTools:
     """
     This class provides several methods to manipulate geom objects in Salome
 class GeomStudyTools:
     """
     This class provides several methods to manipulate geom objects in Salome


@@ -98,6 +105,16 @@ class GeomStudyTools:
     # ======================================================================
     # Helper functions to add/remove a geometrical shape in/from the study
     # ======================================================================
     # ======================================================================
     # Helper functions to add/remove a geometrical shape in/from the study
     # ======================================================================

+    ## Add a GEOM shape in the study. It returns the associated entry
+    #  that corresponds to the identifier of the entry in the study. This
+    #  entry can be used to retrieve an object in the study. A folderName
+    #  can be specified. In this case, a folder with this name is first
+    #  created in the Geometry part of the study, and the shape study
+    #  object is stored in this folder of the study. 
+    #
+    #    \param  shape (GEOM object) the GEOM object defining the shape
+    #    \param  shapeName (string) the name for this shape in the study 
+    #    \param  folderName (string) the name of a folder in the GEOM part of the study

     def addShapeToStudy(self, shape,shapeName,folderName=None):
         """
         Add a GEOM shape in the study. It returns the associated entry
     def addShapeToStudy(self, shape,shapeName,folderName=None):
         """
         Add a GEOM shape in the study. It returns the associated entry


@@ -117,8 +134,7 @@ class GeomStudyTools:
         :param  folderName: the name of a folder in the GEOM part of the study
         """
         study   = self.editor.study
         :param  folderName: the name of a folder in the GEOM part of the study
         """
         study   = self.editor.study

-        studyId = study._get_StudyId()
-        geompy  = getGeompy(studyId)
+        geompy  = getGeompy()

 
         if folderName is None:
             # Insert the shape in the study by the standard way
 
         if folderName is None:
             # Insert the shape in the study by the standard way


@@ -141,7 +157,11 @@ class GeomStudyTools:
             entry = shapeStudyObject.GetID()
 
         return entry
             entry = shapeStudyObject.GetID()
 
         return entry

-
+    
+    ## This removes the specified entry from the study. Note that this
+    #  operation does not destroy the underlying GEOM object, neither
+    #  erase the drawing in the viewer.
+    #  The underlying GEOM object is returned (so that it can be destroyed)

     def removeFromStudy(self, shapeStudyEntry):
         """
         This removes the specified entry from the study. Note that this
     def removeFromStudy(self, shapeStudyEntry):
         """
         This removes the specified entry from the study. Note that this


@@ -150,7 +170,6 @@ class GeomStudyTools:
         The underlying GEOM object is returned (so that it can be destroyed)
         """
         study = self.editor.study
         The underlying GEOM object is returned (so that it can be destroyed)
         """
         study = self.editor.study

-        studyId = study._get_StudyId()

         shape = self.getGeomObjectFromEntry(shapeStudyEntry)    
         studyObject = IDToSObject(shapeStudyEntry)
         self.editor.removeItem(studyObject,True)
         shape = self.getGeomObjectFromEntry(shapeStudyEntry)    
         studyObject = IDToSObject(shapeStudyEntry)
         self.editor.removeItem(studyObject,True)


@@ -166,6 +185,11 @@ class GeomStudyTools:
     # python source code). 
     # ======================================================================
 
     # python source code). 
     # ======================================================================
 

+    ## Display the geometrical shape whose name in the study is <em>shapeName</em>. 
+    #
+    #  \param shapeName (string) name of the geometrical shape
+    #  \param color (tuple) RGB components of the color of the shape
+    #  \return True if the shape was found, False otherwise

     def displayShapeByName(self, shapeName, color = None, fit=True):
         """
         Display the geometrical shape whose name in the study is `shapeName`.
     def displayShapeByName(self, shapeName, color = None, fit=True):
         """
         Display the geometrical shape whose name in the study is `shapeName`.


@@ -190,11 +214,15 @@ class GeomStudyTools:
                     return self.displayShapeByEntry(entry,color,fit)
         return False
 
                     return self.displayShapeByEntry(entry,color,fit)
         return False
 

+    ## Display the geometrical shape whose entry is given by \em entry. 
+    #  You should prefer use this function instead of the
+    #  displayShapeByName() which can have an unpredictable behavior in 
+    #  the case where several objects exist with the same name in the study.

     def displayShapeByEntry(self, shapeStudyEntry, color = None, fit=True):
         """
         Display the geometrical shape whose entry is given by
         `entry`. You should prefer use this function instead of the
     def displayShapeByEntry(self, shapeStudyEntry, color = None, fit=True):
         """
         Display the geometrical shape whose entry is given by
         `entry`. You should prefer use this function instead of the

-        displayShapeByName which can have an unpredictible behavior in
+        displayShapeByName which can have an unpredictable behavior in

         the case where several objects exist with the same name in the
         study.
         """
         the case where several objects exist with the same name in the
         study.
         """


@@ -208,6 +236,10 @@ class GeomStudyTools:
             geomgui.setColor(shapeStudyEntry, color[0], color[1], color[2])
         return True
 
             geomgui.setColor(shapeStudyEntry, color[0], color[1], color[2])
         return True
 

+    ## Erase the geometrical shape whose entry is given by \em entry. 
+    #  Please note that the shape is just erased from the
+    #  viewer. The associated study object still exists in the study,
+    #  and the geom object still exists in the GEOM engine.

     def eraseShapeByEntry(self, shapeStudyEntry):
         """
         Erase the geometrical shape whose entry is given by
     def eraseShapeByEntry(self, shapeStudyEntry):
         """
         Erase the geometrical shape whose entry is given by


@@ -225,9 +257,16 @@ class GeomStudyTools:
     # Helper functions for a complete suppression of a shape from the
     # SALOME session.
     # ======================================================================
     # Helper functions for a complete suppression of a shape from the
     # SALOME session.
     # ======================================================================

+    ## This completely deletes a geom shape.
+    #  \warning Please be aware that to delete a geom object, 
+    #  you have three operations to perform:
+    #    
+    #  1. erase the shape from the viewers
+    #  2. remove the entry from the study
+    #  3. destroy the underlying geom object

     def deleteShape(self,shapeStudyEntry):
         """
     def deleteShape(self,shapeStudyEntry):
         """

-        This completly deletes a geom shape.
+        This completely deletes a geom shape.

         
         WARNING: please be aware that to delete a geom object, you have
         three operations to perform:
         
         WARNING: please be aware that to delete a geom object, you have
         three operations to perform:


@@ -243,19 +282,22 @@ class GeomStudyTools:
     # ======================================================================
     # Helper functions for interactivity with the object browser
     # ======================================================================
     # ======================================================================
     # Helper functions for interactivity with the object browser
     # ======================================================================

+    ## Returns the GEOM object currently selected in the objects browser.

     def getGeomObjectSelected(self):
     def getGeomObjectSelected(self):

-        '''
+        """

         Returns the GEOM object currently selected in the objects browser.
         Returns the GEOM object currently selected in the objects browser.

-        '''
+        """

         sobject, entry = guihelper.getSObjectSelected()
         geomObject = self.getGeomObjectFromEntry(entry)
         return geomObject
 
         sobject, entry = guihelper.getSObjectSelected()
         geomObject = self.getGeomObjectFromEntry(entry)
         return geomObject
 

+    ## Returns the GEOM object associated to the specified entry,
+    #  (the entry is the identifier of an item in the active study)

     def getGeomObjectFromEntry(self,entry):
     def getGeomObjectFromEntry(self,entry):

-        '''
+        """

         Returns the GEOM object associated to the specified entry,
         (the entry is the identifier of an item in the active study)
         Returns the GEOM object associated to the specified entry,
         (the entry is the identifier of an item in the active study)

-        '''
+        """

         if entry is None:
             return None
         geomObject=IDToObject(entry, self.editor.study)
         if entry is None:
             return None
         geomObject=IDToObject(entry, self.editor.study)


@@ -281,14 +323,21 @@ def TEST_createBox():
     box = geompy.MakeBoxDXDYDZ(200, 200, 200)
     geompy.addToStudy( box, 'box' )    
     if salome.sg.hasDesktop():
     box = geompy.MakeBoxDXDYDZ(200, 200, 200)
     geompy.addToStudy( box, 'box' )    
     if salome.sg.hasDesktop():

-        salome.sg.updateObjBrowser(1)
+        salome.sg.updateObjBrowser()

 
 
 def TEST_getGeomObjectSelected():
     tool = GeomStudyTools()
     myGeomObject = tool.getGeomObjectSelected()
 
 
 def TEST_getGeomObjectSelected():
     tool = GeomStudyTools()
     myGeomObject = tool.getGeomObjectSelected()

-    print myGeomObject
-
+    print(myGeomObject)
+
+## This test is a simple use case that illustrates how to create a
+#  GEOM shape in a SALOME session (create the GEOM object, put in in
+#  the study, and display the shape in a viewer) and delete a shape
+#  from a SALOME session (erase the shape from the viewer, delete the
+#  entry from the study, and finally destroy the underlying GEOM
+#  object).
+#  \ingroup geomtools

 def TEST_createAndDeleteShape():
     """
     This test is a simple use case that illustrates how to create a
 def TEST_createAndDeleteShape():
     """
     This test is a simple use case that illustrates how to create a


@@ -301,13 +350,12 @@ def TEST_createAndDeleteShape():
     import salome
     salome.salome_init()
     study   = salome.myStudy
     import salome
     salome.salome_init()
     study   = salome.myStudy

-    studyId = salome.myStudyId

 
     from salome.geom import geomtools
 
     from salome.geom import geomtools

-    geompy = geomtools.getGeompy(studyId)
+    geompy = geomtools.getGeompy()

     
     from salome.kernel.studyedit import getStudyEditor
     
     from salome.kernel.studyedit import getStudyEditor

-    studyEditor = getStudyEditor(studyId)
+    studyEditor = getStudyEditor()

 
     gst = geomtools.GeomStudyTools(studyEditor)
 
 
     gst = geomtools.GeomStudyTools(studyEditor)
 


@@ -353,14 +401,14 @@ def TEST_createAndDeleteShape():
     gst.eraseShapeByEntry(sphereStudyEntry)
 
     # --------------------------------------------------
     gst.eraseShapeByEntry(sphereStudyEntry)
 
     # --------------------------------------------------

-    # In this last example, we completly delete an object from the
+    # In this last example, we completely delete an object from the

     # SALOME session (erase from viewer, remove from study and finnaly
     # destroy the object). This is done by a simple call to
     # deleteShape().
     gst.deleteShape(cylinderStudyEntry)
 
     # --------------------------------------------------
     # SALOME session (erase from viewer, remove from study and finnaly
     # destroy the object). This is done by a simple call to
     # deleteShape().
     gst.deleteShape(cylinderStudyEntry)
 
     # --------------------------------------------------

-    # At the end of the executioon of this test, you should have in
+    # At the end of the execution of this test, you should have in

     # the SALOME session:
     # - the box, in a dedicated folder of the study, and displayed in the viewer
     # - the sphere, in the standard place of the study, and not displayed 
     # the SALOME session:
     # - the box, in a dedicated folder of the study, and displayed in the viewer
     # - the sphere, in the standard place of the study, and not displayed