]> SALOME platform Git repositories - modules/geom.git/commitdiff
Salome HOME
0021746: EDF 2135 GEOM: Unification of Python documentations
authormpa <mpa@opencascade.com>
Thu, 13 Mar 2014 12:50:55 +0000 (16:50 +0400)
committermpa <mpa@opencascade.com>
Thu, 13 Mar 2014 12:50:55 +0000 (16:50 +0400)
23 files changed:
CMakeLists.txt
doc/CMakeLists.txt
doc/docutils/CMakeLists.txt [deleted file]
doc/docutils/conf.py.in [deleted file]
doc/docutils/docapi.rst [deleted file]
doc/docutils/images/salome-geom-structuralelements.png [deleted file]
doc/docutils/index.rst [deleted file]
doc/docutils/overview.rst [deleted file]
doc/salome/gui/GEOM/CMakeLists.txt
doc/salome/gui/GEOM/doxyfile_py.in
doc/salome/gui/GEOM/images/salome-geom-structuralelements.png [new file with mode: 0644]
doc/salome/gui/GEOM/input/api_documentation.doc [new file with mode: 0644]
doc/salome/gui/GEOM/input/geompy.doc
doc/salome/gui/GEOM/input/index.doc
doc/salome/gui/GEOM/input/manipulate_object.doc [new file with mode: 0644]
doc/salome/gui/GEOM/input/python_interface.doc [new file with mode: 0644]
doc/salome/gui/GEOM/input/struct_elem_visualisation.doc [new file with mode: 0644]
src/GEOM_PY/geomtools.py
src/GEOM_PY/structelem/__init__.py
src/GEOM_PY/structelem/orientation.py
src/GEOM_PY/structelem/parts.py
src/GEOM_SWIG/geomBuilder.py
src/GEOM_SWIG/gsketcher.py

index 8500b75c5a4ca3699ec3035900614277704df60c..51158531921652fdb73187ef5bf3dbd651b43b41 100755 (executable)
@@ -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)
index fc259fe06a84cce15f9fa106f33433acb2a4df54..27aa5730ad3c0f920b3fb11eb6bd16cb656cb8ea 100755 (executable)
@@ -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 (executable)
index 1cca3b9..0000000
+++ /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 (file)
index 2980f2e..0000000
+++ /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
-# "<project> v<release> 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/<name>.
-html_copy_source = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> 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 (file)
index 6f9140b..0000000
+++ /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/images/salome-geom-structuralelements.png b/doc/docutils/images/salome-geom-structuralelements.png
deleted file mode 100644 (file)
index 9c05f7e..0000000
Binary files a/doc/docutils/images/salome-geom-structuralelements.png and /dev/null differ
diff --git a/doc/docutils/index.rst b/doc/docutils/index.rst
deleted file mode 100644 (file)
index 2a0233d..0000000
+++ /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 (file)
index c74a0aa..0000000
+++ /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)</docapi>` 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
index 455ce44b8373343d8a39655a6e3d40a9911ecbc9..fbe6fd62fd67ed2105975411512a72e318da20ce 100644 (file)
@@ -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
index f45264b7948a79e07d902733fc0f376ac63d3c7f..493b7c65c1b14211e7866d7157e02f532da99dd3 100755 (executable)
@@ -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/salome/gui/GEOM/images/salome-geom-structuralelements.png b/doc/salome/gui/GEOM/images/salome-geom-structuralelements.png
new file mode 100644 (file)
index 0000000..9c05f7e
Binary files /dev/null and b/doc/salome/gui/GEOM/images/salome-geom-structuralelements.png differ
diff --git a/doc/salome/gui/GEOM/input/api_documentation.doc b/doc/salome/gui/GEOM/input/api_documentation.doc
new file mode 100644 (file)
index 0000000..f66d560
--- /dev/null
@@ -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.
+
+<b>salome.geom</b> – Package containing the %GEOM python utilities:
+- <a href="geompy_doc/group__geomtools.html">geomtools</a>
+- <a href="geompy_doc/group__sketcher.html">sketcher</a>
+- <a href="geompy_doc/group__structelem.html">structelem</a>
+*/
index 43cee55d2523616bc1f61d5804ac37023b2476e7..c483ca71ccd6c90c64b4df02bcaeed659b3e3d6f 100644 (file)
@@ -3,11 +3,11 @@
 \page geompy_page Python Interface geomBuilder.py
 
 \n Please, see
-<a href="geompy_doc/modules.html">structured documentation for geomBuilder.py</a>,
+<a href="geompy_doc/group__geomBuilder.html">structured documentation for geomBuilder.py</a>,
 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 <a href="geompy_doc/namespacegeomBuilder.html">
+linear documentation for geomBuilder.py</a>
 
 \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.
index 00c1bf700fa65d456e30b961e005dedb8adadeff..3a3736940605631f13f0e8f3d65eeeec7887f60d 100644 (file)
@@ -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 <a class="el" target="_new" href="../../tui/GEOM/docutils/index.html">salome.geom python package</a>.
+\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 (file)
index 0000000..97383f8
--- /dev/null
@@ -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 (file)
index 0000000..2711c4a
--- /dev/null
@@ -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 (file)
index 0000000..ffeed38
--- /dev/null
@@ -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
+
+*/
index c43c411dda2b68606df1c801ae8ffb65fdeea993..0e5adbba559f820f25981b648202aa46b2bb5dad 100644 (file)
 #
 # 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 <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
@@ -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 <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`.
@@ -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
index e51094d94bc231cf4d76c67768f5baecd0acab59..d0a3fc4d57c8eeb5631c190bc8fcfca118c02914 100644 (file)
 #
 # 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
index c92eea3f39f5b05a363010088942afc2c520a23f..18978b923f7893ddcb0764348c8694244395b0f4 100644 (file)
 #
 # 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
index 9126aca961d83efcd09c373eb34f225d380da9e6..d697210f92871cd0aa73baab3c8c0045ff77e69b 100644 (file)
 #
 # 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`.
index 62bf941d0872649cbf16156327594edf9849c580..8f2afc1266003b1d783e12b08c7302a1bd96dad3 100644 (file)
@@ -29,7 +29,7 @@
 """
 
 ##
-## @defgroup l1_publish_data Publishing results in SALOME study
+## @defgroup geomBuilder geomBuilder Python module
 ## @{
 ##
 ## @details
 ## 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
index 8e72e50d965a498a274a53c701117d2298579c9e..e738c19933d3a861598fef43ac290f060f70bb33 100644 (file)
 #  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.