From 8e102c8ec4390e18f20e5bf959542a256def8333 Mon Sep 17 00:00:00 2001 From: mpa Date: Thu, 13 Mar 2014 16:50:55 +0400 Subject: [PATCH] 0021746: EDF 2135 GEOM: Unification of Python documentations --- CMakeLists.txt | 2 - doc/CMakeLists.txt | 1 - doc/docutils/CMakeLists.txt | 35 --- doc/docutils/conf.py.in | 200 ----------------- doc/docutils/docapi.rst | 52 ----- doc/docutils/index.rst | 11 - doc/docutils/overview.rst | 75 ------- doc/salome/gui/GEOM/CMakeLists.txt | 6 +- doc/salome/gui/GEOM/doxyfile_py.in | 2 +- .../images/salome-geom-structuralelements.png | Bin .../gui/GEOM/input/api_documentation.doc | 12 ++ doc/salome/gui/GEOM/input/geompy.doc | 6 +- doc/salome/gui/GEOM/input/index.doc | 4 +- .../gui/GEOM/input/manipulate_object.doc | 30 +++ .../gui/GEOM/input/python_interface.doc | 35 +++ .../GEOM/input/struct_elem_visualisation.doc | 17 ++ src/GEOM_PY/geomtools.py | 76 ++++++- src/GEOM_PY/structelem/__init__.py | 115 +++++++++- src/GEOM_PY/structelem/orientation.py | 48 ++++- src/GEOM_PY/structelem/parts.py | 202 ++++++++++++++++-- src/GEOM_SWIG/geomBuilder.py | 8 +- src/GEOM_SWIG/gsketcher.py | 37 +++- 22 files changed, 563 insertions(+), 411 deletions(-) delete mode 100755 doc/docutils/CMakeLists.txt delete mode 100644 doc/docutils/conf.py.in delete mode 100644 doc/docutils/docapi.rst delete mode 100644 doc/docutils/index.rst delete mode 100644 doc/docutils/overview.rst rename doc/{docutils => salome/gui/GEOM}/images/salome-geom-structuralelements.png (100%) create mode 100644 doc/salome/gui/GEOM/input/api_documentation.doc create mode 100644 doc/salome/gui/GEOM/input/manipulate_object.doc create mode 100644 doc/salome/gui/GEOM/input/python_interface.doc create mode 100644 doc/salome/gui/GEOM/input/struct_elem_visualisation.doc diff --git a/CMakeLists.txt b/CMakeLists.txt index 8500b75c5..511585319 100755 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -111,10 +111,8 @@ ENDIF() IF(SALOME_BUILD_DOC) FIND_PACKAGE(SalomeDoxygen) FIND_PACKAGE(SalomeGraphviz) - FIND_PACKAGE(SalomeSphinx) SALOME_LOG_OPTIONAL_PACKAGE(Doxygen SALOME_BUILD_DOC) SALOME_LOG_OPTIONAL_PACKAGE(Graphviz SALOME_BUILD_DOC) - SALOME_LOG_OPTIONAL_PACKAGE(Sphinx SALOME_BUILD_DOC) ENDIF() # Find GUI (optional) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index fc259fe06..27aa5730a 100755 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -21,4 +21,3 @@ # ADD_SUBDIRECTORY(salome) -ADD_SUBDIRECTORY(docutils) diff --git a/doc/docutils/CMakeLists.txt b/doc/docutils/CMakeLists.txt deleted file mode 100755 index 1cca3b9be..000000000 --- a/doc/docutils/CMakeLists.txt +++ /dev/null @@ -1,35 +0,0 @@ -# Copyright (C) 2012-2014 CEA/DEN, EDF R&D, 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 -# 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 -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# Lesser General Public License for more details. -# -# You should have received a copy of the GNU Lesser General Public -# License along with this library; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -# -# See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com -# - -SALOME_CONFIGURE_FILE(conf.py.in conf.py) - -SET(_cmd_options -c ${CMAKE_CURRENT_BINARY_DIR} -b html -d doctrees -D latex_paper_size=a4 ${CMAKE_CURRENT_SOURCE_DIR} docutils) - -# This macro mainly prepares the environment in which sphinx should run: -# this sets the PYTHONPATH and LD_LIBRARY_PATH to include OMNIORB, DOCUTILS, SETUPTOOLS, etc ... -SALOME_GENERATE_ENVIRONMENT_SCRIPT(_cmd env_script "${SPHINX_EXECUTABLE}" "${_cmd_options}") - -ADD_CUSTOM_TARGET(html_docs COMMAND ${_cmd}) - -INSTALL(CODE "EXECUTE_PROCESS(COMMAND \"${CMAKE_COMMAND}\" --build ${PROJECT_BINARY_DIR} --target html_docs)") -INSTALL(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/docutils DESTINATION ${SALOME_INSTALL_DOC}/tui/GEOM) -INSTALL(FILES ${PROJECT_SOURCE_DIR}/doc/salome/tui/images/head.png DESTINATION ${SALOME_INSTALL_DOC}/tui/GEOM) - -SET(make_clean_files docutils doctrees) -SET_DIRECTORY_PROPERTIES(PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES "${make_clean_files}") \ No newline at end of file diff --git a/doc/docutils/conf.py.in b/doc/docutils/conf.py.in deleted file mode 100644 index 2980f2e06..000000000 --- a/doc/docutils/conf.py.in +++ /dev/null @@ -1,200 +0,0 @@ -# -*- coding: iso-8859-1 -*- -# -# yacs documentation build configuration file, created by -# sphinx-quickstart on Fri Aug 29 09:57:25 2008. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# The contents of this file are pickled, so don't put values in the namespace -# that aren't pickleable (module imports are okay, they're removed automatically). -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If your extensions are in another directory, add it here. If the directory -# is relative to the documentation root, use os.path.abspath to make it -# absolute, like shown here. -#sys.path.append(os.path.abspath('.')) - -# General configuration -# --------------------- - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc'] - -# Uncomment the following line to build the links with Python documentation -# (you might need to set http_proxy environment variable for this to work) -#extensions += ['sphinx.ext.intersphinx'] - -# Intersphinx mapping to add links to modules and objects in the Python -# standard library documentation -intersphinx_mapping = {'http://docs.python.org': None} - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -source_encoding = 'utf-8' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = 'GEOM python packages' -copyright = '2010-2014 EDF R&D' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '@SALOMEGEOM_VERSION@' -# The full version, including alpha/beta/rc tags. -release = '@SALOMEGEOM_VERSION@' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -language = 'en' - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of documents that shouldn't be included in the build. -#unused_docs = [] - -# List of directories, relative to source directory, that shouldn't be searched -# for source files. -exclude_trees = ['.build','ref','images','CVS','.svn'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - - -# Options for HTML output -# ----------------------- - -# The theme to use for HTML and HTML Help pages. Major themes that come with -# Sphinx are currently 'default' and 'sphinxdoc'. -html_theme = 'default' -#html_theme = 'nature' -#html_theme = 'agogo' -#html_theme = 'sphinxdoc' -#html_theme = 'omadoc' - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = ['themes'] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -html_use_modindex = False - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, the reST sources are included in the HTML build as _sources/. -html_copy_source = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = '' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'geompydoc' - - -# Options for LaTeX output -# ------------------------ - -# The paper size ('letter' or 'a4'). -latex_paper_size = 'a4' - -# The font size ('10pt', '11pt' or '12pt'). -latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, document class [howto/manual]). -latex_documents = [ - ('index', 'geompy.tex', 'Documentation of the GEOM python packages', 'EDF R\&D', 'manual') -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -latex_logo = '@CMAKE_CURRENT_SOURCE_DIR@/../salome/tui/images/head.png' - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = True - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -latex_use_modindex = False diff --git a/doc/docutils/docapi.rst b/doc/docutils/docapi.rst deleted file mode 100644 index 6f9140b05..000000000 --- a/doc/docutils/docapi.rst +++ /dev/null @@ -1,52 +0,0 @@ - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - Documentation of the programming interface (API) -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -This section describes the python packages and modules of the -``salome.geom`` python package. The main part is generated from the -code documentation included in source python files. - -:mod:`salome.geom` -- Package containing the GEOM python utilities -================================================================== - -:mod:`geomtools` -- Tools to access GEOM engine and objects ------------------------------------------------------------ - -.. automodule:: salome.geom.geomtools - :members: - -:mod:`sketcher` -- Wrapper to help the creation of simple sketches ------------------------------------------------------------------- - -.. automodule:: salome.geom.sketcher - :members: - -.. autoclass:: Sketcher - :members: - -:mod:`structelem` -- Structural elements package ------------------------------------------------- - -.. automodule:: salome.geom.structelem - -.. autoclass:: StructuralElementManager - :members: - -.. autoclass:: StructuralElement - :members: - -:mod:`structelem.parts` -- Structural element parts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: salome.geom.structelem.parts - :members: - :undoc-members: - :show-inheritance: - -:mod:`structelem.orientation` -- Structural element orientation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: salome.geom.structelem.orientation - :members: - :undoc-members: diff --git a/doc/docutils/index.rst b/doc/docutils/index.rst deleted file mode 100644 index 2a0233d4e..000000000 --- a/doc/docutils/index.rst +++ /dev/null @@ -1,11 +0,0 @@ - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - Documentation of the GEOM python package -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -.. toctree:: - :maxdepth: 3 - - overview.rst - docapi.rst - diff --git a/doc/docutils/overview.rst b/doc/docutils/overview.rst deleted file mode 100644 index c74a0aaed..000000000 --- a/doc/docutils/overview.rst +++ /dev/null @@ -1,75 +0,0 @@ - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -General presentation of the GEOM python package -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -The GEOM python package essentially contains: - -* Utility functions to handle GEOM items in Salome study (see ``geomtools.py``). - - - add a shape to a study, remove from the study - - display a shape in a viewer, erase the shape from the viewers - - completly delete a shape (undisplay, unpublish, and destroy the shape) - - helper functions to manage the selection in the object browser -* Wrapping functions to help the usage of GEOM tools: - - - a sketcher module to create sketches from the python API (see - ``sketcher.py``) -* The visualization of structural elements: a function to create - geometrical 3D representations of mechanical models called - "structural elements" (see package ``structelem``) - -The functions are distributed in the python package -``salome.geom``. The specification of the programming interface of -this package is detailled in the part :doc:`Documentation of the -programming interface (API)` of this documentation. - -.. note:: - The main package ``salome`` contains other sub-packages that are - distributed with the other SALOME modules. For example, the KERNEL - module provides the python package ``salome.kernel`` and SMESH the - package ``salome.smesh``. - -Visualization of structural elements (package ``structelem``) -------------------------------------------------------------- - -The usage of the visualization of structural elements can be -appreciated with this set of instructions: - -.. code-block:: python - - from salome.geom.structelem import TEST_StructuralElement - TEST_StructuralElement() - -This creates the geometrical objects displayed in the study below: - -.. image:: /images/salome-geom-structuralelements.png - :align: center - -Manipulate GEOM object in the study (module ``geomtools``) ----------------------------------------------------------- - -The usage of the ``geomtools`` module can be appreciated with this set -of instructions: - -.. code-block:: python - - from salome.geom.geomtools import TEST_createAndDeleteShape - TEST_createAndDeleteShape() - -This test executes the following procedure: - -* Create, publish, and display a cylinder -* Create, publish, and display a sphere -* Create a box, publish it in a folder "boxset", and display it with a - "pink" color. -* Erase the sphere from the viewer (the sphere still exists in the study) -* Delete the cylinder (the cylinder is no longer displayed and does - not exist any more, neither in the study nor the GEOM componet. - -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 diff --git a/doc/salome/gui/GEOM/CMakeLists.txt b/doc/salome/gui/GEOM/CMakeLists.txt index 455ce44b8..fbe6fd62f 100644 --- a/doc/salome/gui/GEOM/CMakeLists.txt +++ b/doc/salome/gui/GEOM/CMakeLists.txt @@ -32,7 +32,11 @@ ENDIF(WIN32) ADD_CUSTOM_TARGET(usr_docs ${CMAKE_COMMAND} -E make_directory tmp COMMAND ${PYTHON_EXECUTABLE} ${f} -o tmp/geomBuilder.py ${CMAKE_SOURCE_DIR}/src/GEOM_SWIG/geomBuilder.py - COMMAND ${PYTHON_EXECUTABLE} ${f} -o tmp/gsketcher.py ${CMAKE_SOURCE_DIR}/src/GEOM_SWIG/gsketcher.py + COMMAND ${PYTHON_EXECUTABLE} ${f} -o tmp/gsketcher.py ${CMAKE_SOURCE_DIR}/src/GEOM_SWIG/gsketcher.py + COMMAND ${PYTHON_EXECUTABLE} ${f} -o tmp/geomtools.py ${CMAKE_SOURCE_DIR}/src/GEOM_PY/geomtools.py + COMMAND ${PYTHON_EXECUTABLE} ${f} -o tmp/structelem.py ${CMAKE_SOURCE_DIR}/src/GEOM_PY/structelem/__init__.py + COMMAND ${PYTHON_EXECUTABLE} ${f} -o tmp/parts.py ${CMAKE_SOURCE_DIR}/src/GEOM_PY/structelem/parts.py + COMMAND ${PYTHON_EXECUTABLE} ${f} -o tmp/orientation.py ${CMAKE_SOURCE_DIR}/src/GEOM_PY/structelem/orientation.py COMMAND ${DOXYGEN_EXECUTABLE} doxyfile_tui COMMAND ${DOXYGEN_EXECUTABLE} doxyfile_py COMMAND ${DOXYGEN_EXECUTABLE} doxyfile diff --git a/doc/salome/gui/GEOM/doxyfile_py.in b/doc/salome/gui/GEOM/doxyfile_py.in index f45264b79..493b7c65c 100755 --- a/doc/salome/gui/GEOM/doxyfile_py.in +++ b/doc/salome/gui/GEOM/doxyfile_py.in @@ -99,7 +99,7 @@ EXAMPLE_RECURSIVE = NO #--------------------------------------------------------------------------- #Input related options #--------------------------------------------------------------------------- -INPUT = tmp/geomBuilder.py tmp/gsketcher.py @CMAKE_SOURCE_DIR@/idl/GEOM_Gen.idl +INPUT = tmp @CMAKE_SOURCE_DIR@/idl/GEOM_Gen.idl FILE_PATTERNS = IMAGE_PATH = @CMAKE_CURRENT_SOURCE_DIR@/images EXAMPLE_PATH = @CMAKE_SOURCE_DIR@/src/GEOM_SWIG diff --git a/doc/docutils/images/salome-geom-structuralelements.png b/doc/salome/gui/GEOM/images/salome-geom-structuralelements.png similarity index 100% rename from doc/docutils/images/salome-geom-structuralelements.png rename to doc/salome/gui/GEOM/images/salome-geom-structuralelements.png diff --git a/doc/salome/gui/GEOM/input/api_documentation.doc b/doc/salome/gui/GEOM/input/api_documentation.doc new file mode 100644 index 000000000..f66d56023 --- /dev/null +++ b/doc/salome/gui/GEOM/input/api_documentation.doc @@ -0,0 +1,12 @@ +/*! + +\page api_documentation Documentation of the programming interface (API) + +This section describes the python packages and modules of the \b salome.geom python package. +The main part is generated from the code documentation included in source python files. + +salome.geom – Package containing the %GEOM python utilities: +- geomtools +- sketcher +- structelem +*/ diff --git a/doc/salome/gui/GEOM/input/geompy.doc b/doc/salome/gui/GEOM/input/geompy.doc index 43cee55d2..c483ca71c 100644 --- a/doc/salome/gui/GEOM/input/geompy.doc +++ b/doc/salome/gui/GEOM/input/geompy.doc @@ -3,11 +3,11 @@ \page geompy_page Python Interface geomBuilder.py \n Please, see -structured documentation for geomBuilder.py, +structured documentation for geomBuilder.py, where all package functionality is separated in groups by purpose. -\n Also you can find any function in the \ref geomBuilder -"linear documentation for geomBuilder.py". +\n Also you can find any function in the +linear documentation for geomBuilder.py \n With SALOME 7.2, the Python interface for Geometry has been slightly modified to offer new functionality, \n You may have to modify your scripts generated with SALOME 6 or older versions. diff --git a/doc/salome/gui/GEOM/input/index.doc b/doc/salome/gui/GEOM/input/index.doc index 00c1bf700..3a3736940 100644 --- a/doc/salome/gui/GEOM/input/index.doc +++ b/doc/salome/gui/GEOM/input/index.doc @@ -27,9 +27,7 @@ Geometry module preferences are described in the \subpage geometry_preferences_page section of SALOME Geometry Help. Almost all geometry module functionalities are accessible via -\subpage geompy_page "Geometry module Python Interface" - -Other functions are available in salome.geom python package. +\subpage python_interface "Geometry module Python Interface" You can find the answer to some Frequently Asked Questions in this page: - \subpage faq "Frequently Asked Questions" diff --git a/doc/salome/gui/GEOM/input/manipulate_object.doc b/doc/salome/gui/GEOM/input/manipulate_object.doc new file mode 100644 index 000000000..97383f8f0 --- /dev/null +++ b/doc/salome/gui/GEOM/input/manipulate_object.doc @@ -0,0 +1,30 @@ +/*! + +\page manipulate_object Manipulate GEOM object in the study (module geomtools) + +The usage of the geomtools module can be appreciated with this set +of instructions: + +\code +from salome.geom.geomtools import TEST_createAndDeleteShape +TEST_createAndDeleteShape() +\endcode + +This test executes the following procedure: + +- Create, publish, and display a cylinder +- Create, publish, and display a sphere +- Create a box, publish it in a folder "boxset", and display it with a + "pink" color. +- Erase the sphere from the viewer (the sphere still exists in the study) +- Delete the cylinder (the cylinder is no longer displayed and does + not exist any more, neither in the study nor the GEOM componet. + +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 + +*/ diff --git a/doc/salome/gui/GEOM/input/python_interface.doc b/doc/salome/gui/GEOM/input/python_interface.doc new file mode 100644 index 000000000..2711c4a82 --- /dev/null +++ b/doc/salome/gui/GEOM/input/python_interface.doc @@ -0,0 +1,35 @@ +/*! + +\page python_interface Geometry module Python Interface + +The %GEOM python package essentially contains: + +- \subpage geompy_page "Python Interface geomBuilder.py" to perform the following functions: + - Creating geometrical objects + - Importing/exporting geometrical objects + - Transforming geometrical objects + - Using measurement tools + - Field on Geometry +- Utility functions to handle %GEOM items in Salome study (geomtools.py). + See example - \subpage manipulate_object "Manipulate GEOM object in the study". + - add a shape to a study, remove from the study + - display a shape in a viewer, erase the shape from the viewers + - completly delete a shape (undisplay, unpublish, and destroy the shape) + - helper functions to manage the selection in the object browser +- Wrapping functions to help the usage of %GEOM tools: + - a sketcher module to create sketches from the python API (gsketcher.py) +- \subpage struct_elem_visualisation "The visualization of structural elements": a function to create + geometrical 3D representations of mechanical models called + "structural elements" (package \ref structelem.py "structelem") + +The functions are distributed in the python package salome.geom. +The specification of the programming interface of this package +is detailled in the part \subpage api_documentation "Documentation of the programming interface (API)" +of this documentation. + + +\note The main package salome contains other sub-packages that are +distributed with the other SALOME modules. For example, the KERNEL +module provides the python package salome.kernel and SMESH the +package salome.smesh. +*/ diff --git a/doc/salome/gui/GEOM/input/struct_elem_visualisation.doc b/doc/salome/gui/GEOM/input/struct_elem_visualisation.doc new file mode 100644 index 000000000..ffeed3878 --- /dev/null +++ b/doc/salome/gui/GEOM/input/struct_elem_visualisation.doc @@ -0,0 +1,17 @@ +/*! + +\page struct_elem_visualisation Visualization of structural elements (package structelem) + +The usage of the visualization of structural elements can be +appreciated with this set of instructions: + +\code +from salome.geom.structelem import TEST_StructuralElement +TEST_StructuralElement() +\endcode + +This creates the geometrical objects displayed in the study below: + +\image html salome-geom-structuralelements.png + +*/ diff --git a/src/GEOM_PY/geomtools.py b/src/GEOM_PY/geomtools.py index c43c411dd..0e5adbba5 100644 --- a/src/GEOM_PY/geomtools.py +++ b/src/GEOM_PY/geomtools.py @@ -18,6 +18,14 @@ # # 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. @@ -44,6 +52,10 @@ except: _geompys = {} +## Return an object behaving exactly like geompy module, except that it is +# associated with the study \em studyId. If \em studyId is \b None, return +# a pseudo geompy object for the current study. +# \ingroup geomtools def getGeompy(studyId = None): """ Return an object behaving exactly like geompy module, except that it is @@ -68,6 +80,16 @@ ModeShading = 1 DisplayMode=ModeShading PreviewColor=[236,163,255] +## This class provides several methods to manipulate geom objects in Salome study. +# The parameter studyEditor 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 @@ -95,6 +117,16 @@ class GeomStudyTools: # ====================================================================== # 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 @@ -138,7 +170,11 @@ class GeomStudyTools: 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 @@ -163,6 +199,11 @@ class GeomStudyTools: # python source code). # ====================================================================== + ## Display the geometrical shape whose name in the study is shapeName. + # + # \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`. @@ -187,6 +228,10 @@ class GeomStudyTools: 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 unpredictible 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 @@ -205,6 +250,10 @@ class GeomStudyTools: 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 @@ -222,6 +271,13 @@ class GeomStudyTools: # Helper functions for a complete suppression of a shape from the # SALOME session. # ====================================================================== + ## This completly 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): """ This completly deletes a geom shape. @@ -240,19 +296,22 @@ class GeomStudyTools: # ====================================================================== # Helper functions for interactivity with the object browser # ====================================================================== + ## Returns the GEOM object currently selected in the objects browser. def getGeomObjectSelected(self): - ''' + """ Returns the GEOM object currently selected in the objects browser. - ''' + """ 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): - ''' + """ 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) @@ -286,6 +345,13 @@ def TEST_getGeomObjectSelected(): myGeomObject = tool.getGeomObjectSelected() 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 diff --git a/src/GEOM_PY/structelem/__init__.py b/src/GEOM_PY/structelem/__init__.py index e51094d94..d0a3fc4d5 100644 --- a/src/GEOM_PY/structelem/__init__.py +++ b/src/GEOM_PY/structelem/__init__.py @@ -18,6 +18,45 @@ # # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # + +## \defgroup structelem structelem - Structural elements package +# \{ +# \details +# This package is used to create and visualize structural elements. +# It contains three modules: +# - This module \ref structelem "salome.geom.structelem" defines the main classes +# StructuralElement and StructuralElementManager that can be +# directly used to build structural elements. +# - The module \ref parts "salome.geom.structelem.parts" defines +# the classes corresponding to the different parts (beams, grids, etc.) that make up +# a structural element. It is used to build the geometric shapes in the structural element. +# - The module \ref orientation "salome.geom.structelem.orientation" defines +# the classes that are used to compute the orientation of the structural element parts +# and to build the corresponding markers. +# +# A structural element is a set of geometric shapes (beams, grids, etc.) that +# are built semi-automatically along a set of geometric primitives (edges for +# instance). They are visualized with the same color as their base primitives in +# the geom viewer. +# \n Structural elements are generally created by the StructuralElementManager class, +# from a list of commands describing the element to create. +# +# Example: +# \code +# commandList = [('VisuPoutreGenerale', {'Group_Maille': 'Edge_1'}), +# ('VisuBarreCercle', {'R': 30, 'Group_Maille': 'Edge_1', 'EP': 15}), +# ] +# +# structElemManager = StructuralElementManager() +# elem = structElemManager.createElement(commandList) +# elem.display() +# salome.sg.updateObjBrowser(True) +# \endcode +# +# \defgroup orientation +# \defgroup parts +# \} + """ This package is used to create and visualize structural elements. It contains three modules: @@ -70,6 +109,13 @@ from salome.geom.geomtools import getGeompy from salome.geom.structelem import parts from salome.geom.structelem.parts import InvalidParameterError +## This class manages the structural elements in the study. It is used to +# create a new structural element from a list of commands. The parameter +# \em studyId defines the ID of the study in which the manager will create +# structural elements. If it is \b None or not specified, it will use +# the ID of the current study as defined by +# \b salome.kernel.studyedit.getActiveStudyId() function. +# \ingroup structelem class StructuralElementManager: """ This class manages the structural elements in the study. It is used to @@ -82,6 +128,42 @@ class StructuralElementManager: def __init__(self, studyId = None): self._studyEditor = getStudyEditor(studyId) + ## Create a structural element from the list of commands \em commandList. + # Each command in this list represent a part of the structural element, + # that is a specific kind of shape (circular beam, grid, etc.) + # associated with one or several geometrical primitives. A command must + # be a tuple. The first element is the structural element part class + # name or alias name. The second element is a dictionary containing the + # parameters describing the part. Valid class names are all the classes + # defined in the module salome.geom.structelem.parts and inheriting + # parts.StructuralElementPart. There are also several + # aliases for backward compatibility. Here is the complete list: + # - parts.GeneralBeam + # - parts.CircularBeam + # - parts.RectangularBeam + # - parts.ThickShell + # - parts.Grid + # - parts.VisuPoutreGenerale() (alias for parts.GeneralBeam) + # - parts.VisuPoutreCercle() (alias for parts.CircularBeam) + # - parts.VisuPoutreRectangle() (alias for parts.RectangularBeam) + # - parts.VisuBarreGenerale() (alias for parts.GeneralBeam) + # - parts.VisuBarreRectangle() (alias for parts.RectangularBeam) + # - parts.VisuBarreCercle() (alias for parts.CircularBeam) + # - parts.VisuCable() (alias for parts.CircularBeam) + # - parts.VisuCoque() (alias for parts.ThickShell) + # - parts.VisuGrille() (alias for parts.Grid) + # - \b Orientation: This identifier is used to specify the orientation + # of one or several 1D structural element parts (i.e. beams). The + # parameters are described in class orientation.Orientation1D. + # + # The valid parameters in the dictionary depend on the type of the + # structural element part, and are detailed in the documentation of + # the corresponding class. The only parameter that is common to all the + # classes is "MeshGroups" (that can also be named "Group_Maille"). It + # defines the name of the geometrical object(s) in the study that will + # be used as primitives to build the structural element part. This + # parameter can be either a list of strings or a single string with + # comma separated names. def createElement(self, commandList): """ Create a structural element from the list of commands `commandList`. @@ -191,7 +273,12 @@ class StructuralElementManager: element.build() logger.debug("StructuralElementManager.createElement: END") return element - + + ## This method extracts the names of the mesh groups (i.e. the + # geometrical objects used to build the structural element part) in the + # command in parameter. It returns a tuple containing the mesh groups as + # a list of strings and the other parameters of the command as a new + # dictionary. def _extractMeshGroups(self, command): """ This method extracts the names of the mesh groups (i.e. the @@ -227,6 +314,15 @@ class StructuralElementManager: return (meshGroupList, newparams) +## This class represents a structural element, i.e. a set of geometrical +# objects built along geometrical primitives. The parameter \em studyId +# defines the ID of the study that will contain the structural element. If +# it is \b None or not specified, the constructor will use the ID of +# the active study as defined by \b salome.kernel.studyedit.getActiveStudyId +# function. Structural elements are normally created by the class +# StructuralElementManager, so this class should not be +# instantiated directly in the general case. +# \ingroup structelem class StructuralElement: """ This class represents a structural element, i.e. a set of geometrical @@ -256,6 +352,9 @@ class StructuralElement: self._studyEditor.studyId) self._SObject = None + ## Find or create the study object corresponding to the structural + # element. This object is a Geom Folder named "SE_N" where N is a + # numerical ID. def _getSObject(self): """ Find or create the study object corresponding to the structural @@ -273,6 +372,9 @@ class StructuralElement: self._SObject = geompy.NewFolder("SE_" + str(self._id), mainFolder) return self._SObject + ## Add a part to the structural element. + # + # \param newpart (StructuralElementPart) the part to add to the structural element. def addPart(self, newpart): """ Add a part to the structural element. @@ -310,6 +412,13 @@ class StructuralElement: for shape in newshapes: self._shapeDict[shape] = newpart + ## Add orientation information to a part in the structural element. This + # information will be used to build the corresponding markers. + # + # \param meshGroup (string) the name of a geometrical primitive. The orientation + # information will apply to the structural element part built along this primitive. + # \param orientParams (dictionary) parameters defining the orientation of the + # structural element part. Those parameters are detailed in class orientation.Orientation1D. def addOrientation(self, meshGroup, orientParams): """ Add orientation information to a part in the structural element. This @@ -333,6 +442,8 @@ class StructuralElement: logger.warning('Mesh group "%s" not found in structural element, ' 'cannot set orientation.' % meshGroup) + ## Build the geometric shapes and the markers corresponding to the + # different parts of the structural element, and add them to the study. def build(self): """ Build the geometric shapes and the markers corresponding to the @@ -365,6 +476,7 @@ class StructuralElement: geompy.addToStudy(marker, markerSObjName) geompy.PutToFolder(marker, self._getSObject()) + ## Display the structural element in the geom view. def display(self): """ Display the structural element in the geom view. @@ -372,6 +484,7 @@ class StructuralElement: StructuralElement.showElement(self._SObject) @staticmethod + ## Display the structural element corresponding to the study object \b theSObject def showElement(theSObject): """ Display the structural element corresponding to the study object diff --git a/src/GEOM_PY/structelem/orientation.py b/src/GEOM_PY/structelem/orientation.py index c92eea3f3..18978b923 100644 --- a/src/GEOM_PY/structelem/orientation.py +++ b/src/GEOM_PY/structelem/orientation.py @@ -18,6 +18,14 @@ # # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # + +## \defgroup orientation orientation +# \{ +# \details +# This module is used to compute the orientation of the different parts in a +# structural element and to build the corresponding markers (trihedrons). +# \} + """ This module is used to compute the orientation of the different parts in a structural element and to build the corresponding markers (trihedrons). @@ -29,7 +37,9 @@ from salome.kernel.logger import Logger from salome.kernel import termcolor logger = Logger("salome.geom.structelem.orientation", color = termcolor.RED) - +## This class is used to compute the orientation of 1D elements and to build +# the corresponding markers. +# \ingroup orientation class Orientation1D: """ This class is used to compute the orientation of 1D elements and to build @@ -46,6 +56,14 @@ class Orientation1D: del reprdict["geom"] return '%s(%s)' % (self.__class__.__name__, reprdict) + ## Add orientation parameters. \em params is a dictionary containing one or + # several orientation parameters. The valid parameters are: + # - "VECT_Y": Triplet defining the local Y axis (the X axis is the + # main direction of the 1D element). + # - "ANGL_VRIL": Angle of rotation along the X axis to define the local + # coordinate system. + # The parameters can be specified several times. In this case, only the + # last "VECT_Y" or "ANGL_VRIL" is taken into account. def addParams(self, params): """ Add orientation parameters. `params` is a dictionary containing one or @@ -78,7 +96,9 @@ class Orientation1D: if len(mydict) > 0: logger.warning("Invalid orientation parameter(s) (ignored): %s" % str(mydict)) - + ## Get the vectors Y and Z for the default LCS, that use the main + # direction of the 1D object as the local X axis and the global Z axis + # to determine the local Z axis. def _getDefaultVecYZ(self, center, vecX): """ Get the vectors Y and Z for the default LCS, that use the main @@ -100,7 +120,9 @@ class Orientation1D: locPlaneXY = self.geom.MakePlaneThreePnt(center, xPoint, yPoint, 1.0) locZ = self.geom.GetNormal(locPlaneXY) return (locY, locZ) - + + ## Create a marker with origin \em center and X axis \em vecX. + # \em geom is the pseudo-geompy object used to build the geometric shapes. def buildMarker(self, geom, center, vecX): """ Create a marker with origin `center` and X axis `vecX`. `geom` is the @@ -110,6 +132,9 @@ class Orientation1D: marker = geom.MakeMarkerPntTwoVec(center, vecX, locY) return marker + ## Get the vectors Y and Z for the LCS with origin \em center and X axis + # \em vecX. \em geom is the pseudo-geompy object used to build the + # geometric shapes. def getVecYZ(self, geom, center, vecX): """ Get the vectors Y and Z for the LCS with origin `center` and X axis @@ -148,7 +173,11 @@ class Orientation1D: return (locY, locZ) - +## This class is used to compute the orientation of 2D elements and to build +# the corresponding markers. Angles \em alpha and \em beta are used to determine +# the local coordinate system for the 2D element. If \em vect is not +# \b None, it is used instead of \em alpha and \em beta. +# \ingroup orientation class Orientation2D: """ This class is used to compute the orientation of 2D elements and to build @@ -168,6 +197,10 @@ class Orientation2D: del reprdict["geom"] return '%s(%s)' % (self.__class__.__name__, reprdict) + ## Create the default marker, that use the normal vector of the 2D object + # as the local Z axis and the global X axis to determine the local X + # axis. \em warnings can be used to enable or disable the logging of + # warning messages. def _buildDefaultMarker(self, center, normal, warnings = True): """ Create the default marker, that use the normal vector of the 2D object @@ -189,6 +222,8 @@ class Orientation2D: marker = self._buildMarkerRefVecX(center, normal, globalVecX) return marker + ## Create a marker using \em normal as Z axis and \em refVecX + # to determine the X axis. def _buildMarkerRefVecX(self, center, normal, refVecX): """ Create a marker using `normal` as Z axis and `refVecX` to determine @@ -204,6 +239,11 @@ class Orientation2D: marker = self.geom.MakeMarkerPntTwoVec(center, locX, locY) return marker + ## Create a marker with origin \em center and \em normal as Z axis. + # The other axes are computed using the parameters alpha and beta of the + # Orientation2D instance. \em geom is the pseudo-geompy object used to + # build the geometric shapes. \em warnings can be used to enable or + # disable the logging of warning messages. def buildMarker(self, geom, center, normal, warnings = True): """ Create a marker with origin `center` and `normal` as Z axis. The other diff --git a/src/GEOM_PY/structelem/parts.py b/src/GEOM_PY/structelem/parts.py index 9126aca96..d697210f9 100644 --- a/src/GEOM_PY/structelem/parts.py +++ b/src/GEOM_PY/structelem/parts.py @@ -18,6 +18,16 @@ # # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com # + +## \defgroup parts parts +# \{ +# \details +# This module defines the different structural element parts. It is used to +# build the geometric shapes of the structural elements. It should not be used +# directly in the general case. Structural elements should be created by the +# \ref structelem.StructuralElementManager "salome.geom.structelem.StructuralElementManager". +# \} + """ This module defines the different structural element parts. It is used to build the geometric shapes of the structural elements. It should not be used @@ -56,7 +66,9 @@ LIGHT_RED = SALOMEDS.Color(1.0, 0.5, 0.5) PURPLE = SALOMEDS.Color(170.0/255.0, 85.0/255.0, 1.0) ORANGE = SALOMEDS.Color(1.0, 170.0/255.0, 0.0) - +## This exception is raised when an invalid parameter is used to build a +# structural element part. +# \ingroup parts class InvalidParameterError(Exception): """ This exception is raised when an invalid parameter is used to build a @@ -74,7 +86,10 @@ class InvalidParameterError(Exception): self.expression, self.value, self.groupName) - +## This class enables the use of sub-shapes in sets or as dictionary keys. +# It implements __eq__ and __hash__ methods so that sub-shapes with the same +# CORBA object \em mainShape and the same \em id are considered equal. +# \ingroup parts class SubShapeID: """ This class enables the use of sub-shapes in sets or as dictionary keys. @@ -86,6 +101,8 @@ class SubShapeID: self._mainShape = mainShape self._id = id + ## Return the sub-shape (GEOM object). \em geom is a pseudo-geompy object + # used to find the geometrical object. def getObj(self, geom): """ Return the sub-shape (GEOM object). `geom` is a pseudo-geompy object @@ -100,7 +117,16 @@ class SubShapeID: def __hash__(self): return self._mainShape._hash(2147483647) ^ self._id - +## This class is the base class for all structural element parts. It should +# not be instantiated directly (consider it as an "abstract" class). +# \param studyId (integer) the ID of the study in which the part is created. +# \param groupName (string) the name of the underlying geometrical primitive +# in the study. +# \param groupGeomObj (GEOM object) the underlying geometrical primitive. +# \param parameters (dictionary) parameters defining the structural element (see +# subclasses for details). +# \param name (string) name to use for the created object in the study. +# \ingroup parts class StructuralElementPart: """ This class is the base class for all structural element parts. It should @@ -148,6 +174,9 @@ class StructuralElementPart: if self.color is None: self.color = self._groupGeomObj.GetColor() + ## This method finds the value of a parameter in the parameters + # dictionary. The argument is a list because some parameters can have + # several different names. def _getParameter(self, nameList, default = None): """ This method finds the value of a parameter in the parameters @@ -162,6 +191,7 @@ class StructuralElementPart: return self._parameters[name] return default + ## This method finds the user name for a parameter. def _getParamUserName(self, paramName): """ This method finds the user name for a parameter. @@ -183,6 +213,9 @@ class StructuralElementPart: return '%s("%s", %s)' % (self.__class__.__name__, self.groupName, reprdict) + ## Add orientation information to the structural element part. See class + # \ref Orientation1D "salome.geom.structelem.orientation.Orientation1D" + # for the description of the parameters. def addOrientation(self, orientParams): """ Add orientation information to the structural element part. See class @@ -191,6 +224,8 @@ class StructuralElementPart: """ self._orientation.addParams(orientParams) + ## This method checks that some parameters or some expressions involving + # those parameters are greater than a minimum value. def _checkSize(self, value, mindim, expression): """ This method checks that some parameters or some expressions involving @@ -200,6 +235,8 @@ class StructuralElementPart: raise InvalidParameterError(self.groupName, expression, mindim, value) + ## Build the geometric shapes and the markers corresponding to the + # structural element part in the study \em studyId. def build(self): """ Build the geometric shapes and the markers corresponding to the @@ -212,6 +249,8 @@ class StructuralElementPart: marker.SetColor(self.color) return (shape, markers) + ## This abstract method must be implemented in subclasses and should + # create the geometrical shape(s) of the structural element part. def _buildPart(self): """ This abstract method must be implemented in subclasses and should @@ -222,6 +261,9 @@ class StructuralElementPart: "StructuralElementPart subclasses)." % self.__class__.__name__) + ## This abstract method must be implemented in subclasses and should + # create the markers defining the orientation of the structural element + # part. def _buildMarkers(self): """ This abstract method must be implemented in subclasses and should @@ -233,6 +275,7 @@ class StructuralElementPart: "StructuralElementPart subclasses)." % self.__class__.__name__) + ## Find and return the base sub-shapes in the structural element part. def _getSubShapes(self, minDim = MIN_LENGTH_FOR_EXTRUSION): """ Find and return the base sub-shapes in the structural element part. @@ -252,7 +295,10 @@ class StructuralElementPart: subShapes.append(subShape) return subShapes - +## This class is an "abstract" class for all 1D structural element parts. It +# should not be instantiated directly. See class StructuralElementPart +# for the description of the parameters. +# \ingroup parts class Beam(StructuralElementPart): """ This class is an "abstract" class for all 1D structural element parts. It @@ -268,6 +314,9 @@ class Beam(StructuralElementPart): parameters, name, color) self._orientation = orientation.Orientation1D() + ## This method checks if a 1D object is "reversed", i.e. if its + # orientation is different than the orientation of the underlying OCC + # object. def _isReversed(self, path): """ This method checks if a 1D object is "reversed", i.e. if its @@ -280,6 +329,9 @@ class Beam(StructuralElementPart): dist = self.geom.MinDistance(p1, p2) return dist > length / 2 + ## Get a vertex and the corresponding tangent on a wire by parameter. + # This method takes into account the "real" orientation of the wire + # (i.e. the orientation of the underlying OCC object). def _getVertexAndTangentOnOrientedWire(self, path, param): """ Get a vertex and the corresponding tangent on a wire by parameter. @@ -298,6 +350,8 @@ class Beam(StructuralElementPart): tangent = self.geom.MakeTangentOnCurve(path, param) return (vertex, tangent) + ## Create a solid by the extrusion of section \em wire1 to section \em wire2 + # along \em path. def _makeSolidPipeFromWires(self, wire1, wire2, point1, point2, path): """ Create a solid by the extrusion of section `wire1` to section `wire2` @@ -312,6 +366,7 @@ class Beam(StructuralElementPart): solid = self.geom.MakeSolid([closedShell]) return solid + ## Build the structural element part. def _buildPart(self): """ Build the structural element part. @@ -351,6 +406,7 @@ class Beam(StructuralElementPart): else: return self.geom.MakeCompound(listPipes) + ## Build the markers defining the orientation of the structural element part. def _buildMarkers(self): """ Build the markers defining the orientation of the structural element @@ -367,6 +423,18 @@ class Beam(StructuralElementPart): return listMarkers +## This class defines a beam with a circular section. It can be full or +# hollow, and its radius and thickness can vary from one end of the beam to +# the other. The valid parameters for circular beams are: +# - "R1" or "R": radius at the first end of the beam. +# - "R2" or "R": radius at the other end of the beam. +# - "EP1" or "EP" (optional): thickness at the first end of the beam. +# If not specified or equal to 0, the beam is considered full. +# - "EP2" or "EP" (optional): thickness at the other end of the beam. +# If not specified or equal to 0, the beam is considered full. +# +# See class StructuralElementPart for the description of the other parameters. +# \ingroup parts class CircularBeam(Beam): """ This class defines a beam with a circular section. It can be full or @@ -428,6 +496,7 @@ class CircularBeam(Beam): "%s - %s" % (self._getParamUserName("R2"), self._getParamUserName("EP2"))) + ## Create the circular sections used to build the pipe. def _makeSectionWires(self, fPoint, fNormal, lPoint, lNormal): """ Create the circular sections used to build the pipe. @@ -446,6 +515,28 @@ class CircularBeam(Beam): return (outerCircle1, innerCircle1, outerCircle2, innerCircle2) +## This class defines a beam with a rectangular section. It can be full or +# hollow, and its dimensions can vary from one end of the beam to the other. +# The valid parameters for rectangular beams are: +# - "HY1", "HY", "H1" or "H": width at the first end of the beam. +# - "HZ1", "HZ", "H1" or "H": height at the first end of the beam. +# - "HY2", "HY", "H2" or "H": width at the other end of the beam. +# - "HZ2", "HZ", "H2" or "H": height at the other end of the beam. +# - "EPY1", "EPY", "EP1" or "EP" (optional): thickness in the width +# direction at the first end of the beam. If not specified or equal to 0, +# the beam is considered full. +# - "EPZ1", "EPZ", "EP1" or "EP" (optional): thickness in the height +# direction at the first end of the beam. If not specified or equal to 0, +# the beam is considered full. +# - "EPY2", "EPY", "EP2" or "EP" (optional): thickness in the width +# direction at the other end of the beam. If not specified or equal to 0, +# the beam is considered full. +# - "EPZ2", "EPZ", "EP2" or "EP" (optional): thickness in the height +# direction at the other end of the beam. If not specified or equal to 0, +# the beam is considered full. +# +# See class StructuralElementPart for the description of the other parameters. +# \ingroup parts class RectangularBeam(Beam): """ This class defines a beam with a rectangular section. It can be full or @@ -539,6 +630,7 @@ class RectangularBeam(Beam): "%s - 2 * %s" % (self._getParamUserName("HZ2"), self._getParamUserName("EPZ2"))) + ## Create a rectangle in the specified plane. def _makeRectangle(self, HY, HZ, lcs): """ Create a rectangle in the specified plane. @@ -553,6 +645,7 @@ class RectangularBeam(Beam): sketch = self.geom.MakeSketcherOnPlane(sketchStr, lcs) return sketch + ## Create one side of the rectangular sections used to build the pipe. def _makeSectionRectangles(self, point, vecX, HY, HZ, EPY, EPZ): """ Create one side of the rectangular sections used to build the pipe. @@ -568,6 +661,7 @@ class RectangularBeam(Beam): innerRect = None return (outerRect, innerRect) + ## Create the rectangular sections used to build the pipe. def _makeSectionWires(self, fPoint, fNormal, lPoint, lNormal): """ Create the rectangular sections used to build the pipe. @@ -581,6 +675,10 @@ class RectangularBeam(Beam): return (outerRect1, innerRect1, outerRect2, innerRect2) +## This method finds the value of a parameter in the parameters +# dictionary. The argument is a list because some parameters can have +# several different names. +# \ingroup parts def getParameterInDict(nameList, parametersDict, default = None): """ This method finds the value of a parameter in the parameters @@ -592,7 +690,15 @@ def getParameterInDict(nameList, parametersDict, default = None): return parametersDict[name] return default - +## This class defines a beam with a generic section. It is represented as a +# full rectangular beam with the following parameters: +# - HY1 = sqrt(12 * IZ1 / A1) +# - HZ1 = sqrt(12 * IY1 / A1) +# - HY2 = sqrt(12 * IZ2 / A2) +# - HZ2 = sqrt(12 * IY2 / A2) +# +# See StructuralElementPart for the description of the other parameters. +# \ingroup parts class GeneralBeam(RectangularBeam): """ This class defines a beam with a generic section. It is represented as a @@ -629,7 +735,10 @@ class GeneralBeam(RectangularBeam): RectangularBeam.__init__(self, studyId, groupName, groupGeomObj, parameters, name, color) - +## This class is an "abstract" class for all 2D structural element parts. It +# should not be instantiated directly. +# See class StructuralElementPart for the description of the parameters. +# \ingroup parts class StructuralElementPart2D(StructuralElementPart): """ This class is an "abstract" class for all 2D structural element parts. It @@ -649,6 +758,7 @@ class StructuralElementPart2D(StructuralElementPart): self._getParameter(["Vecteur"])) self.offset = self._getParameter(["Excentre"], 0.0) + ## Create a copy of a face at a given offset. def _makeFaceOffset(self, face, offset, epsilon = 1e-6): """ Create a copy of a face at a given offset. @@ -663,6 +773,8 @@ class StructuralElementPart2D(StructuralElementPart): self.geom.ShapeType["FACE"]) return faces[0] + ## Build the markers for the structural element part with a given offset + # from the base face. def _buildMarkersWithOffset(self, offset): """ Build the markers for the structural element part with a given offset @@ -691,7 +803,19 @@ class StructuralElementPart2D(StructuralElementPart): return listMarkers - +## This class defines a shell with a given thickness. It can be shifted from +# the base face. The valid parameters for thick shells are: +# - "Epais": thickness of the shell. +# - "Excentre": offset of the shell from the base face. +# - "angleAlpha": angle used to build the markers (see class +# \ref orientation.Orientation2D "salome.geom.structelem.orientation.Orientation2D") +# - "angleBeta": angle used to build the markers (see class +# \ref orientation.Orientation2D "salome.geom.structelem.orientation.Orientation2D") +# - "Vecteur": vector used instead of the angles to build the markers (see +# \ref orientation.Orientation2D "salome.geom.structelem.orientation.Orientation2D") +# +# See class StructuralElementPart for the description of the other parameters. +# \ingroup parts class ThickShell(StructuralElementPart2D): """ This class defines a shell with a given thickness. It can be shifted from @@ -719,6 +843,7 @@ class ThickShell(StructuralElementPart2D): self.thickness = self._getParameter(["Epais"]) logger.debug(repr(self)) + ## Create the geometrical shapes corresponding to the thick shell. def _buildPart(self): """ Create the geometrical shapes corresponding to the thick shell. @@ -740,6 +865,8 @@ class ThickShell(StructuralElementPart2D): else: return self.geom.MakeCompound(listSolids) + ## Create the geometrical shapes corresponding to the thick shell for a + # given face. def _buildThickShellForFace(self, face): """ Create the geometrical shapes corresponding to the thick shell for a @@ -775,6 +902,7 @@ class ThickShell(StructuralElementPart2D): resultSolid = self.geom.MakeSolid([resultShell]) return resultSolid + ## Remove the side edge in a cylinder. def _removeCylinderExtraEdge(self, wires): """ Remove the side edge in a cylinder. @@ -787,6 +915,7 @@ class ThickShell(StructuralElementPart2D): result.append(edge) return result + ## Build the markers defining the orientation of the thick shell. def _buildMarkers(self): """ Build the markers defining the orientation of the thick shell. @@ -794,7 +923,31 @@ class ThickShell(StructuralElementPart2D): return self._buildMarkersWithOffset(self.offset + self.thickness / 2.0) - +## This class defines a grid. A grid is represented by a 2D face patterned +# with small lines in the main direction of the grid frame. The valid +# parameters for grids are: +# - "Excentre": offset of the grid from the base face. +# - "angleAlpha": angle used to build the markers (see class +# \ref orientation.Orientation2D "salome.geom.structelem.orientation.Orientation2D") +# - "angleBeta": angle used to build the markers (see class +# \ref orientation.Orientation2D "salome.geom.structelem.orientation.Orientation2D") +# - "Vecteur": vector used instead of the angles to build the markers (see +# \ref orientation.Orientation2D "salome.geom.structelem.orientation.Orientation2D") +# - "origAxeX": X coordinate of the origin of the axis used to determine the +# orientation of the frame in the case of a cylindrical grid. +# - "origAxeY": Y coordinate of the origin of the axis used to determine the +# orientation of the frame in the case of a cylindrical grid. +# - "origAxeZ": Z coordinate of the origin of the axis used to determine the +# orientation of the frame in the case of a cylindrical grid. +# - "axeX": X coordinate of the axis used to determine the orientation of +# the frame in the case of a cylindrical grid. +# - "axeY": Y coordinate of the axis used to determine the orientation of +# the frame in the case of a cylindrical grid. +# - "axeZ": Z coordinate of the axis used to determine the orientation of +# the frame in the case of a cylindrical grid. +# +# See class StructuralElementPart for the description of the other parameters. +# \ingroup parts class Grid(StructuralElementPart2D): """ This class defines a grid. A grid is represented by a 2D face patterned @@ -839,6 +992,7 @@ class Grid(StructuralElementPart2D): self.vz = self._getParameter(["axeZ"]) logger.debug(repr(self)) + ## Create the geometrical shapes representing the grid. def _buildPart(self): """ Create the geometrical shapes representing the grid. @@ -867,6 +1021,8 @@ class Grid(StructuralElementPart2D): else: return self.geom.MakeCompound(listGridShapes) + ## Create the geometrical shapes representing the grid for a given + # non-cylindrical face. def _buildGridForNormalFace(self, face): """ Create the geometrical shapes representing the grid for a given @@ -902,6 +1058,8 @@ class Grid(StructuralElementPart2D): grid = self.geom.MakeCompound(gridList) return grid + ## Create the geometrical shapes representing the grid for a given + # cylindrical face. def _buildGridForCylinderFace(self, face): """ Create the geometrical shapes representing the grid for a given @@ -941,13 +1099,15 @@ class Grid(StructuralElementPart2D): grid = self.geom.MakeCompound(gridList) return grid + ## Create the markers defining the orientation of the grid. def _buildMarkers(self): """ Create the markers defining the orientation of the grid. """ return self._buildMarkersWithOffset(self.offset) - +## Alias for class GeneralBeam. +# \ingroup parts def VisuPoutreGenerale(studyId, groupName, groupGeomObj, parameters, name = "POUTRE"): """ @@ -955,20 +1115,26 @@ def VisuPoutreGenerale(studyId, groupName, groupGeomObj, parameters, """ return GeneralBeam(studyId, groupName, groupGeomObj, parameters, name) +## Alias for class CircularBeam. +# \ingroup parts def VisuPoutreCercle(studyId, groupName, groupGeomObj, parameters, name = "POUTRE"): """ Alias for class :class:`CircularBeam`. """ return CircularBeam(studyId, groupName, groupGeomObj, parameters, name) - + +## Alias for class RectangularBeam. +# \ingroup parts def VisuPoutreRectangle(studyId, groupName, groupGeomObj, parameters, name = "POUTRE"): """ Alias for class :class:`RectangularBeam`. """ return RectangularBeam(studyId, groupName, groupGeomObj, parameters, name) - + +## Alias for class GeneralBeam. +# \ingroup parts def VisuBarreGenerale(studyId, groupName, groupGeomObj, parameters, name = "BARRE"): """ @@ -976,7 +1142,9 @@ def VisuBarreGenerale(studyId, groupName, groupGeomObj, parameters, """ return GeneralBeam(studyId, groupName, groupGeomObj, parameters, name, color = ORANGE) - + +## Alias for class RectangularBeam. +# \ingroup parts def VisuBarreRectangle(studyId, groupName, groupGeomObj, parameters, name = "BARRE"): """ @@ -985,6 +1153,8 @@ def VisuBarreRectangle(studyId, groupName, groupGeomObj, parameters, return RectangularBeam(studyId, groupName, groupGeomObj, parameters, name, color = ORANGE) +## Alias for class CircularBeam. +# \ingroup parts def VisuBarreCercle(studyId, groupName, groupGeomObj, parameters, name = "BARRE"): """ @@ -993,6 +1163,8 @@ def VisuBarreCercle(studyId, groupName, groupGeomObj, parameters, return CircularBeam(studyId, groupName, groupGeomObj, parameters, name, color = ORANGE) +## Alias for class CircularBeam. +# \ingroup parts def VisuCable(studyId, groupName, groupGeomObj, parameters, name = "CABLE"): """ Alias for class :class:`CircularBeam`. @@ -1000,12 +1172,16 @@ def VisuCable(studyId, groupName, groupGeomObj, parameters, name = "CABLE"): return CircularBeam(studyId, groupName, groupGeomObj, parameters, name, color = PURPLE) +## Alias for class ThickShell. +# \ingroup parts def VisuCoque(studyId, groupName, groupGeomObj, parameters, name = "COQUE"): """ Alias for class :class:`ThickShell`. """ return ThickShell(studyId, groupName, groupGeomObj, parameters, name) - + +## Alias for class Grid. +# \ingroup parts def VisuGrille(studyId, groupName, groupGeomObj, parameters, name = "GRILLE"): """ Alias for class :class:`Grid`. diff --git a/src/GEOM_SWIG/geomBuilder.py b/src/GEOM_SWIG/geomBuilder.py index 62bf941d0..8f2afc126 100644 --- a/src/GEOM_SWIG/geomBuilder.py +++ b/src/GEOM_SWIG/geomBuilder.py @@ -29,7 +29,7 @@ """ ## -## @defgroup l1_publish_data Publishing results in SALOME study +## @defgroup geomBuilder geomBuilder Python module ## @{ ## ## @details @@ -184,8 +184,12 @@ ## it only affects on the representation of the data tree. ## - It is impossible to publish geometry object using any folder as father. ## +## \defgroup l1_publish_data +## \defgroup l1_geomBuilder_auxiliary +## \defgroup l1_geomBuilder_purpose ## @} +## @defgroup l1_publish_data Publishing results in SALOME study ## @defgroup l1_geomBuilder_auxiliary Auxiliary data structures and methods @@ -504,7 +508,7 @@ class info: CLOSED = 1 UNCLOSED = 2 -##! Private class used to bind calls of plugin operations to geomBuilder +## Private class used to bind calls of plugin operations to geomBuilder class PluginOperation: def __init__(self, operation, function): self.operation = operation diff --git a/src/GEOM_SWIG/gsketcher.py b/src/GEOM_SWIG/gsketcher.py index 8e72e50d9..e738c1993 100644 --- a/src/GEOM_SWIG/gsketcher.py +++ b/src/GEOM_SWIG/gsketcher.py @@ -21,6 +21,38 @@ # Author : Julia DOROVSKIKH, Open CASCADE S.A.S. # Module : GEOM_SWIG +## @defgroup sketcher sketcher - Wrapper to help the creation of simple sketches +# @{ +# @details +# This module provides the user with a simple python API +# to realize various sketches from the GEOM text user interface. +# @n Example: +# @code +# import GEOM +# from salome.geom import geomBuilder +# geompy = geomBuilder.New(salome.myStudy) +# +# # create a wire for sketcher +# geomObj_1 = geompy.MakeMarker(0, 0, 0, 1, 0, 0, 0, 1, 0) +# +# # Create the sketch +# sk = geompy.Sketcher2D() +# sk.addPoint(0.000000, 0.000000) +# sk.addSegmentAbsolute(50.000000, 50.000000) +# sk.addSegmentPerpY(0.000000) +# sk.addArcAbsolute(0.000000, 0.000000) +# sk.close() +# Sketch_1 = sk.wire(geomObj_1) +# +# # add objects in the study +# geompy.addToStudy( Sketch_1, 'Sketch_1' ) +# +# # update object browser +# salome.sg.updateObjBrowser(1) +# @endcode +# @n Additionnal examples can be found as unit tests in the source code. +# @} + """ \namespace geompy \brief 2D and 3D Sketcher interfaces @@ -37,6 +69,7 @@ def printVar (var): # Use geompy.Sketcher3D() method to obtain an instance of this class. # # @ref tui_3dsketcher_page "Example" +# @ingroup sketcher class Sketcher3D: """ 3D sketcher interface. @@ -284,9 +317,9 @@ class Sketcher3D: self.geompyD._autoPublish(wire, theName, "wire") return wire -# An interface to build a 2D Sketcher step-by-step. +## An interface to build a 2D Sketcher step-by-step. # Use geompy.Sketcher2D() method to obtain an instance of this class. - +# @ingroup sketcher class Sketcher2D: """ 2D sketcher interface. -- 2.39.2