From a2adcba393bcaac9a2f664f53f845756e99a65e2 Mon Sep 17 00:00:00 2001 From: vsr Date: Wed, 29 Apr 2020 18:18:37 +0300 Subject: [PATCH] Improve doc layout --- .gitattributes | 1 + doc/gui/CMakeLists.txt | 4 +- doc/gui/{ => General}/Introduction.rst | 1370 ++++++++++++------------ doc/gui/{ => General}/TUI_tutorial.rst | 0 doc/gui/{ => General}/Tutorial.rst | 74 +- doc/gui/{ => General}/tutorial.py | 0 doc/gui/TUI_scripts.rst.in | 9 + doc/gui/build_index.py | 121 ++- doc/gui/index.rst.in | 8 +- 9 files changed, 812 insertions(+), 775 deletions(-) rename doc/gui/{ => General}/Introduction.rst (91%) rename doc/gui/{ => General}/TUI_tutorial.rst (100%) rename doc/gui/{ => General}/Tutorial.rst (86%) rename doc/gui/{ => General}/tutorial.py (100%) create mode 100644 doc/gui/TUI_scripts.rst.in diff --git a/.gitattributes b/.gitattributes index 2838ea411..895ba7e5f 100644 --- a/.gitattributes +++ b/.gitattributes @@ -26,6 +26,7 @@ *.qml eol=lf *.qrc eol=lf *.py eol=lf +*.rst eol=lf *.bat eol=crlf *.cmd eol=crlf *.dll binary diff --git a/doc/gui/CMakeLists.txt b/doc/gui/CMakeLists.txt index 62b5e3cc2..dd1b911a6 100644 --- a/doc/gui/CMakeLists.txt +++ b/doc/gui/CMakeLists.txt @@ -32,7 +32,7 @@ CONFIGURE_FILE(${input} ${output}) #sphinx-build -b html -c doc -D latex_paper_size=a4 -d doc/doctree /dn23/PPGP/vsv/SALOME730/SOURCES/PPGP_SRC/doc doc/html -INSTALL(FILES ${DOC_FILES} DESTINATION ${CMAKE_CURRENT_BINARY_DIR}) +INSTALL(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/General DESTINATION ${CMAKE_CURRENT_BINARY_DIR}) INSTALL(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/images DESTINATION ${CMAKE_CURRENT_BINARY_DIR}) @@ -45,7 +45,7 @@ COMMAND ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/build_index.py ${CMAKE_ INSTALL(CODE " EXECUTE_PROCESS( -COMMAND ${SPHINX_EXECUTABLE} -Q -b html -c ${CMAKE_CURRENT_BINARY_DIR} -d doctree ${CMAKE_CURRENT_BINARY_DIR} html +COMMAND ${SPHINX_EXECUTABLE} -b html -c ${CMAKE_CURRENT_BINARY_DIR} -d doctree ${CMAKE_CURRENT_BINARY_DIR} html WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} )" ) diff --git a/doc/gui/Introduction.rst b/doc/gui/General/Introduction.rst similarity index 91% rename from doc/gui/Introduction.rst rename to doc/gui/General/Introduction.rst index ed7d557e8..2c11ea9b4 100644 --- a/doc/gui/Introduction.rst +++ b/doc/gui/General/Introduction.rst @@ -1,685 +1,685 @@ - -.. _introduction: - -Introduction to SHAPER -====================== - -SHAPER module of SALOME is destined for: - -- import and export of geometrical models in IGES, BREP, STEP and XAO formats; -- parametric construction of geometrical objects using a wide range of functions: - - - creation of complex 2D sections using :ref:`sketchPlugin` with consequent extrusion or revolution (see :ref:`featuresPlugin`); - - construction of model using primitives defined in :ref:`primitivesPlugin`; - - usage of Boolean operations (see :ref:`featuresPlugin`); - -- viewing geometrical objects in the OCC viewer; -- transformation of geometrical objects using various algorithms. - -It is possible to easily set :ref:`parameter_usage` predefined to be used as arguments when objects are created. - -SHAPER module preferences are described in the :ref:`preferences` section of SALOME Help. - -Almost all SHAPER module functionalities are accessible via Python Interface. - -SHAPER module works with one study containing several documents: - -- partset -- one or several parts. - -Only one document can be active. In complicated models partset consists of several parts. Parts in partset may be copied, positioned relatively to each other, or simply translated. - -A new study contains only a partset with 7 default constructions, which cannot be deleted: - -- one point **Origin** coinciding with the origin of the coordinate system; -- three axes **OX**, **OY**, **OZ** coinciding with coordinate axes; -- three planes **YOZ**, **XOZ**, **XOY** coinciding with coordinate planes. - -Only points, axis, planes (see :ref:`constructionPlugin`) and sketches (see :ref:`sketchPlugin`) can be added into Partset to be used in any part later. -:ref:`parameter_usage` can be used both in Partset and any Part. - -A new Part can be created as described in :ref:`partPlugin`. - -Double click or pop-up menu can be used to activate existing document. - -Application desktop -------------------- - -The main window of the application consists of the following components: - -- :ref:`main_menu`; -- :ref:`doc_windows`; -- :ref:`viewer`; -- :ref:`toolbar`; -- status bar. - -.. figure:: images/main_window.png - :align: center - - Main window of SHAPER module - -.. _main_menu: - -Main menu ---------- - -Main menu provides access to all commands of the application. - -.. figure:: images/main_menu.png - :align: center - - Main menu - -Main menu includes standard Salome items: - -- File; -- Edit; -- View; -- Tools; -- Window; -- Help; - -and items specific for SHAPER module: - -- Part (see :ref:`partPlugin`); -- Sketch (see :ref:`sketchPlugin`); -- Construction (see :ref:`constructionPlugin`); -- Build (see :ref:`buildPlugin`); -- Primitives (see :ref:`primitivesPlugin`); -- GDML (see :ref:`gdmlPlugin`); -- Features (see :ref:`featuresPlugin`); -- Macros. - - .. _toolbar: - -SHAPER toolbar --------------- - -Application toolbar contains: - -- standard toolbar; -- modules toolbar; -- SHAPER toolbar. - -.. figure:: images/toolbar.png - :align: center - - Toolbars - -SHAPER toolbar duplicates the main menu and provides access to all commands of the application. - -SHAPER toolbar is separated into sections: - -- Part; -- Movement; -- Measurement; -- Sketch; -- Construction; -- Build; -- Primitives; -- GDML; -- Features; -- Boolean; -- Collections; -- Fillet; -- Macros. - -Visibility of SHAPER toolbar sections is managed using *View -> Toolbar* :ref:`main_menu` item or toolbar pop-up menu. - -.. _doc_windows: - -Dock windows ------------- - -Standard dock windows are: - -- :ref:`object_browser` -- :ref:`inspection_panel` -- :ref:`hidefaces_panel` -- :ref:`python console` -- :ref:`property_panel` - -Dock windows can be placed in three dock areas using drag-and-drop: - -- left, -- right, -- bottom. - -By default Object browser window is placed at the left dock area, Inspection panel at the right dock area and Python console at the bottom dock area of the main window. - -Property Panel is hidden. - -Property Panel is shown on operation start in left dock area of the main window by default. - -If Object browser is shown at the same side then they will be tabbed. - -Each dock window can be closed using **Cross** window button and opened again using a corresponding command from *View - Windows* :ref:`main_menu` or alternatively using pop-up menu. - -.. figure:: images/popup_menu.png - :align: center - - Pop-up menu for visibility of windows and toolbars - -.. _object_browser: - -Object browser -^^^^^^^^^^^^^^ - -Object browser contains all documents created in the current study. - -Each document includes standard branches where created objects are placed. - -Documents with branches are shown in Tree View. - -.. figure:: images/object_browser.png - :align: center - - **Object browser**: Partset active - -Partset includes three branches: - -- Parameters; -- Constructions; -- Features - -Part includes the following branches: - -- Parameters; -- Constructions; -- Results; -- Fields; -- Groups; -- Features. - -New part contains only 3 empty branches: - -- Parameters; -- Constructions; -- Results. - -Features are placed one after another in the active document with default names and their results are placed into the corresponding branch. - -Examples of default names assigned automatically for :ref:`box_feature` are: - -* **Box_1**, **Box_2**, ... for Feature; -* **Box_1_1**, **Box_2_1**, ... for Result. - -Note, that a default branch is added into Tree View when the first feature of this type is created. - -Note, that the result used in feature as argument is removed. - -This child result can be restored using **Recover** feature. - -Each feature, result, construction, group, field, parameter can be renamed using *Rename* pop-up menu command. - -.. figure:: images/popup_menu_object_browser_feature.png - :align: center - - **Feature** pop-up menu - -.. figure:: images/popup_menu_object_browser_result.png - :align: center - - **Result** pop-up menu - -.. figure:: images/popup_menu_object_browser_construction.png - :align: center - - **Construction** pop-up menu - -The order of features can be changed using *Move to the end* and *Move to the end and split* pop-up menu commands. They work only for Group features. The selected group or several groups will be moved to the end of features list. The *Move to the end and split* also splits the resulting group in several groups: one group per one selection. - -Folders can be used to arrange long Tree View for features. - -.. figure:: images/object_browser_folder.png - :align: center - - **Object browser** with folder Dome: Part_1 active - -*Insert a folder before* pop-up menu command creates a new empty folder before the selected feature. The folder can be renamed. - -Features placed after/before the created folder can be moved into the folder using *Move into the previous folder* / *Move into the next folder* pop-up menu command. - -This allows to decrease the length of feature list. - -Features can be removed from the folder using *Move out before the folder* / *Move out after the folder* pop-up menu command. - -*Clean history* pop-up menu command looks for features that do not participate in other features. - -**Clean history** dialog box shows a list of unused features. After confirmation by click **Yes** button unused features are removed. - -.. figure:: images/clean_history.png - :align: center - - **Clean history** dialog box - -*Select result* and *Select parent feature* pop-up menu commands help to navigate along Tree View. - -A feature and its result can be deleted using *Delete* pop-up menu command. - -Note that all features using the removed feature and their results will be removed simultaneously. - -**Delete feature** dialog box shows the list of features to be removed. After confirmation by click **Yes** button all these features are removed. - -.. figure:: images/delete_feature.png - :align: center - - **Delete feature** dialog box - -.. _property_panel: - -Property panel -^^^^^^^^^^^^^^ - -.. |ok_btn| image:: images/button_ok.png -.. |cancel_btn| image:: images/button_cancel.png -.. |help_btn| image:: images/button_help.png - -Property panel consists of two parts: - -- controls a container for input of parameters for the current operation; -- buttons panel containing standard buttons: - - | |ok_btn| **Ok/Apply** executes operation with defined parameters, - | |cancel_btn| **Cancel/Close** calls **Abort operation** dialog box to confirm operation abort, - | |help_btn| **Help** calls User's guide opened on page describing the current operation. - - .. figure:: images/abort_operation.png - :align: center - - **Abort operation** dialog box - -|ok_btn| **OK/Apply** button is disabled if not all input parameters are defined or some errors are found. Error is shown as tooltip and in status bar. - -.. _inspection_panel: - -Inspection panel -^^^^^^^^^^^^^^^^ - -Inspection panel provides the list of types and quantities of all topological entities, composing the selected result, construction or feature. - -.. figure:: images/inspection_panel.png - :align: center - - **Inspection panel** for default Box - -**Object** displays name of the selected result, construction or feature. - -**Type** characterizes the whole shape. - -The information about Point, Axis or Edge additionally shows coordinates of point / end points. - -.. figure:: images/inspection_panel_line.png - :align: center - - **Inspection panel** for Axis - -The information about Plane, Face additionally shows coordinates of center point and direction of normal. - -.. figure:: images/inspection_panel_face.png - :align: center - - **Inspection panel** for Face - -.. _hidefaces_panel: - -Hide Faces panel -^^^^^^^^^^^^^^^^ - -**Hide Faces** panel makes possible to hide temporary faces of any displayed object. **Hide Faces** panel looks like following: - -.. figure:: images/hide_faces_panel.png - :align: center - - **Hide Faces** panel - -- If this panel is activated it "listens" user selection. -- If a face is selected then its name will be shown in the panel's list and hidden in the viewer. -- If user selects a group of faces (or at least a one face of this group) then whole group will be hidden and also all faces from all objects referenced by this group. -- If user will display the hidden group again (by a show operation) then the group will be removed from Hide Faces list and visibility of all referenced faces will be restored. - -Also it is possible do not to hide faces, but make them transparent. For this purpose **"Transparent"** check-box can be used. Value of the transparency can be changed in **Visualization** tab of **Preferences** dialog box. -Closing of **Hide Faces** panel restores visibility state of all objects. If it is necessary to deactivete the **Hide Faces** panel (preserving the current display state) then user has to press **"Esc"** button. - -.. _python console: - -Python console -^^^^^^^^^^^^^^ - -Python console interpreters Python commands entered manually. - -In particular, it is possible to load the python script: - -*execfile(r"/dn48/newgeom/data/example.py")* - -Pop-up menu gives the possibility to: - -- Copy the selected text to clipboard; -- Paste the text from clipboard to Python console ; -- Clear Python console; -- Dump commands from console into the specified file; -- Start/Stop writing log into the specified file. - -.. figure:: images/python_console_popup.png - :align: center - - Pop-up menu of Python console - -.. _viewer: - -Viewer ------- - -The application supports one instance of OCC 3D viewer and is able to show only one 3D space. - -This 3D space can be represented in several view windows. New view window can be created using **Clone view** button in viewer toolbar. - -Each view windows shows its own point of view on the 3D scene. - -This point of view can be modified using viewer commands: **Panning**, **Zooming**, **Scaling**, etc. - -.. figure:: images/2_viewers.png - :align: center - - Two view windows - -The description of OCC 3D Viewer architecture and functionality is provided in GUI module user's guide in chapter **OCC 3D Viewer**. - -.. _parameter_usage: - -Parameters ----------- - -Model parametrization can be done using parameters. - -A parameter can be created in the active partset or part by: - -- :ref:`parameter`; -- :ref:`parameters`; -- :ref:`parameter_expression`. - -Any argument in features can be defined as parameter or expression containing parameters. - -The list of features using parameters is given in **Parameters** dialog box: - - .. figure:: images/parameters_feature.png - :align: center - - Parameters dialog box - -If a parameter value is changed, then all features where it is used are rebuilt. - -A parameter name should be unique in the active document. - -However, partset and part can have parameters with the same name. If parameter names in Partset and Part are identical, then Part parameter has a higher priority and its value will be used in the features of this part. - -In contrast to features (see :ref:`object_browser`), there is an additional option when parameters are deleted. - -.. figure:: images/delete_parameter.png - :align: center - - Delete parameter - -After clicking **Replace** button, the selected parameter is removed but its parent parameters and features are not removed. The deleted parameter is replaced by its value. - -.. _parameter_expression: - -Create parameter on fly -^^^^^^^^^^^^^^^^^^^^^^^ - -Parameter can be created during feature creation simply by writing *variable=expression* in any editbox. - -After feature validation a new parameter with the given name **variable** and value equal to the evaluated expression appears in object browser under **Parameters** in the active partset or part. - -.. _preferences: - -SHAPER preferences ------------------- - -Description of General application preferences and **Preferences** dialog box is provided in GUI module user's guide in chapter **Setting Preferences**. - -SHAPER preferences define visualization of objects, visualization during selection, edition. New preferences can be used right after modification or later after activation of SHAPER module. - -To call **Preferences** dialog box: - -#. select in the Main Menu *File - > Preferences* item or -#. use **Ctrl+P** shortcut. - -SHAPER preferences contains the following tabs: - -- :ref:`visualization_preferences`; -- :ref:`plugins_preferences`; -- :ref:`shortcuts_preferences`; -- :ref:`windows_preferences`. -- :ref:`sketch_preferences`. -- :ref:`viewer_preferences`. - -Visualization tab is activated by default when **Preferences** dialog box is opened in the active SHAPER module. - -Other tabs are activated by click on tab header. - -.. _visualization_preferences: - -Visualization tab -^^^^^^^^^^^^^^^^^ - -This tab defines presentation of objects displayed in OCC 3D viewer. - -.. figure:: images/visualization_preferences.png - :align: center - - **Preferences**: Visualization tab - -**Input fields**: - -- **Selection color** defines a color for selected objects; -- **Result color** selects default shading color for objects from **Results** branch; -- **Group color** selects default color for objects from **Groups** branch; -- **Construction color** selects default color for objects from **Constructions** branch; -- **Part color** selects default color for parts shown in Partset; -- **Field color** selects default color for objects from **Fields** branch; -- **Body deflection coefficient** defines default deflection coefficient for objects from **Results** branch. A smaller coefficient provides better quality of a shape in the viewer; -- **Construction deflection coefficient** defines default deflection coefficient for objects from **Constructions** branch. A smaller coefficient provides better quality of a shape in the viewer; -- **Reference shape wireframe color in operation** selects default color used for wireframe visualization of objects used in active operation; -- **Result shape wireframe color in operation** selects default color used for wireframe visualization of result in active operation. Click **See preview** button to show result; -- **Multi selector item color in operation** selects default color used for visualization of objects selected in property panel to distinguish them among all objects used in active operation; -- **Color of removed feature in operation** selects default color used for visualization of sketch entities to be removed during **Trim/Split** operations; -- **Color of sketch plane** selects default shading color for sketch plane; -- **Hidden faces transparency** defines default transparency value for hidden faces; -- **Dimension arrow size** defines default size of arrows for extension line showing dimensional constraint; -- **Dimension font** defines font used for value of dimensional constraint; -- **Dimension value size** defines default size of value for dimensional constraint; -- **Sketch dimension color** defines default color of dimensional constraint; -- **Construction plane color** selects default color for Construction planes; -- **Sketch entity color** selects default color for sketch objects; -- **Sketch external entity color** selects default color for external objects selected as reference during sketch creation/edition; -- **Sketch auxiliary entity color** selects default color for sketch auxiliary objects; -- **Sketch overconstraint color** selects default color for a sketch with redundant constraints; -- **Sketch fully constraint color** selects default color for a sketch with zero degrees of freedom. - -To redefine any color click on the corresponding line to access **Select color** dialog box - -.. figure:: images/select_color.png - :align: center - - **Preferences**: **Select color** dialog box - -Preferences for sketch are applicable during sketch creation/edition operation. - -.. _plugins_preferences: - -Plugins tab -^^^^^^^^^^^ -Plugins tab defines folders where plugins and resources are located. - -.. figure:: images/plugins_preferences.png - :align: center - - **Preferences**: Plugins tab - -**Input fields**: - -- **Default path** selects default folder where plugins are located. Click on **Open** button opens standard **Find directory** dialog box to navigate to desired folder; - -- **Import initial directory** selects default folder where resources are located. Click on **Open** button opens standard **Find directory** dialog box to navigate to desired folder. - -.. figure:: images/open_button.png - :align: center - - **Open** button - -.. figure:: images/find_directory.png - :align: center - - **Find directory** dialog box - - -.. _shortcuts_preferences: - -Shortcuts tab -^^^^^^^^^^^^^ - -Shortcuts tab defines shortcut keys for different operations. - -.. figure:: images/shortcuts_preferences.png - :align: center - - **Preferences**: Shortcuts tab - -- **Add parameter in parameters manager dialog** defines shortcut keys for adding parameter in parameters manager dialog box. - -.. _windows_preferences: - -Windows tab -^^^^^^^^^^^ - -Windows tab contains definitions for the module windows management. - -.. figure:: images/windows_preferences.png - :align: center - - **Preferences**: Windows tab - -- **Use HideFaces panel in operation** if the checkbox is checked then HideFaces panel will be launched automatically on launching an operation where using of this panel is considered. - -.. _sketch_preferences: - -Sketch tab -^^^^^^^^^^ - -Sketch tab defines properties of coordinate planes shown for selection of sketch plane when no convenient objects are shown in OCC 3D viewer. - -.. figure:: images/sketch_preferences.png - :align: center - - **Preferences**: Sketch tab - -**Input fields**: - -- **Size** defines size of coordinate planes; -- **Thickness** defines thickness of coordinate plane borders; -- **Rotate to plane when selected** check-box turns on/off automatic switch the viewer to the top view for the selected sketch plane. -- **Angular tolerance** defines defines an angular tolerance for automatic creation of horizontal and vertical constraints; -- **Default spline weight** defines default weight for B-spline nodes during creation. The default value can be changed by editing of the spline; -- **Cursor for sketch operation** defines a cursor which indicates a launched sketcher sub-operation. -- **Create sketch entities by dragging** defines a style of sketch etities creation. It concerns creation of lines, rectangles, circles, arcs, ellipses, elliptic arcs. If it is switched ON then points of objects have to be defined by mouse press - mouse move - mouse release. Otherwise every point of an object has to be defined by mouse click; - -.. _viewer_preferences: - -Viewer tab -^^^^^^^^^^ - -Viewer tab defines selection in OCC 3D viewer properties. - -.. figure:: images/viewer_preferences.png - :align: center - - **Preferences**: Viewer tab - -**Input fields**: - -- **Default Selection** defines objects to be selected by mouse click in OCC 3D viewer: - - - **Faces** check-box turns on/off selection of faces; - - **Edges** check-box turns on/off selection of edges; - - **Vertices** check-box turns on/off selection of vertices; - -- **Selection sensitivity** defines size of area around object in pixels, in which mouse click selects object inside this area: - - - **Vertex** defines selection sensitivity for vertices; - - **Edge** defines selection sensitivity for edges. - -.. _toolbars_management: - -Toolbars management -------------------- - -.. _toolbars_dialog: - -**Toolbars** dialog box -^^^^^^^^^^^^^^^^^^^^^^^ -To edit the current tool bars structure select in the Main Menu *Edit - > Edit toolbars* item. -The following dialog box with existing toolbars appears: - -.. figure:: images/Toolbars.png - :align: center - - **Toolbars** dialog box - -**Input fields**: - -- **Toolbars** window contains list of toolbars names. Number of commands in each tool bar is shown in brackets. -- **Add** button creates a new toolbar. Click on **Add** button opens :ref:`create_toolbar`; -- **Edit** button calls :ref:`edit_toolbar` for currently selected tool bar; -- **Delete** button removes currently selected tool bar. Click on **Delete** button opens warning dialog box. After confirmation by click **Yes** button the selected toolbar is deleted. Click **No** button cancels removing of the selected toolbar; -- **Reset** button restores modified tool bars structure to default state; -- **OK** button closes the dialog box, stores result of tool bars edition and updates Shaper tool bars; -- **Cancel** button closes the dialog box without modification of tool bars. - -.. figure:: images/delete_toolbar.png - :align: center - - Warning dialog box - -.. _create_toolbar: - -**Create toolbar** dialog box -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Input fields** of **Create toolbar** dialog box: - -.. figure:: images/create_toolbar.png - :align: center - - **Create toolbar** dialog box - -- **Name of a new toolbar** defines name of the new tool bar. The name of tool bar has to be unique. If user defines a not unique name then a warning appears and a new tooolbar with not unique name is not created; -- **Ok** button closes the dialog box and add a new tool bar of the module into **Toolbars** window; -- **Cancel** button closes the dialog box without addition of a new tool bar. - -.. figure:: images/name_toolbar.png - :align: center - - **Warning** dialog box - -.. _edit_toolbar: - -**Edit toolbar** dialog box -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Input fields** of **Edit toolbar** dialog box: - -.. figure:: images/EditToolbar.png - :align: center - - **Edit toolbar** dialog box - -- **Toolbar name** non-editable field displays name of modified tool bar; -- **Out of toolbars** window contains list of commands which are not included into any tool bar and separator definition "------"; -- **In the toolbar** window contains list of commands which are defined in the current tool bar. Items in this window are listed according to order of commands in the toolbar; -- **Right arrow** button transfers currently selected item from **Out of toolbars** window to **In the toolbar** window and puts new item before the selected item in **In the toolbar** window. - If there is no selected item in **In the toolbar** window then new item will be added at the end of items list. In order to clear current selection it is necessary to click in empty space of the window. -- **Left arrow** button transfers currently selected item from **In the toolbar** window into **Out of toolbars** window; -- **Up** and **Down** buttons change position of selected command in **In the toolbar** window; -- **Ok** button closes the dialog box, stores result of edition; -- **Cancel** button closes the dialog box without modification of tool bar content. + +.. _introduction: + +Introduction to SHAPER +====================== + +SHAPER module of SALOME is destined for: + +- import and export of geometrical models in IGES, BREP, STEP and XAO formats; +- parametric construction of geometrical objects using a wide range of functions: + + - creation of complex 2D sections using :ref:`sketchPlugin` with consequent extrusion or revolution (see :ref:`featuresPlugin`); + - construction of model using primitives defined in :ref:`primitivesPlugin`; + - usage of Boolean operations (see :ref:`featuresPlugin`); + +- viewing geometrical objects in the OCC viewer; +- transformation of geometrical objects using various algorithms. + +It is possible to easily set :ref:`parameter_usage` predefined to be used as arguments when objects are created. + +SHAPER module preferences are described in the :ref:`preferences` section of SALOME Help. + +Almost all SHAPER module functionalities are accessible via Python Interface. + +SHAPER module works with one study containing several documents: + +- partset +- one or several parts. + +Only one document can be active. In complicated models partset consists of several parts. Parts in partset may be copied, positioned relatively to each other, or simply translated. + +A new study contains only a partset with 7 default constructions, which cannot be deleted: + +- one point **Origin** coinciding with the origin of the coordinate system; +- three axes **OX**, **OY**, **OZ** coinciding with coordinate axes; +- three planes **YOZ**, **XOZ**, **XOY** coinciding with coordinate planes. + +Only points, axis, planes (see :ref:`constructionPlugin`) and sketches (see :ref:`sketchPlugin`) can be added into Partset to be used in any part later. +:ref:`parameter_usage` can be used both in Partset and any Part. + +A new Part can be created as described in :ref:`partPlugin`. + +Double click or pop-up menu can be used to activate existing document. + +Application desktop +------------------- + +The main window of the application consists of the following components: + +- :ref:`main_menu`; +- :ref:`doc_windows`; +- :ref:`viewer`; +- :ref:`toolbar`; +- status bar. + +.. figure:: /images/main_window.png + :align: center + + Main window of SHAPER module + +.. _main_menu: + +Main menu +--------- + +Main menu provides access to all commands of the application. + +.. figure:: /images/main_menu.png + :align: center + + Main menu + +Main menu includes standard Salome items: + +- File; +- Edit; +- View; +- Tools; +- Window; +- Help; + +and items specific for SHAPER module: + +- Part (see :ref:`partPlugin`); +- Sketch (see :ref:`sketchPlugin`); +- Construction (see :ref:`constructionPlugin`); +- Build (see :ref:`buildPlugin`); +- Primitives (see :ref:`primitivesPlugin`); +- GDML (see :ref:`gdmlPlugin`); +- Features (see :ref:`featuresPlugin`); +- Macros. + + .. _toolbar: + +SHAPER toolbar +-------------- + +Application toolbar contains: + +- standard toolbar; +- modules toolbar; +- SHAPER toolbar. + +.. figure:: /images/toolbar.png + :align: center + + Toolbars + +SHAPER toolbar duplicates the main menu and provides access to all commands of the application. + +SHAPER toolbar is separated into sections: + +- Part; +- Movement; +- Measurement; +- Sketch; +- Construction; +- Build; +- Primitives; +- GDML; +- Features; +- Boolean; +- Collections; +- Fillet; +- Macros. + +Visibility of SHAPER toolbar sections is managed using *View -> Toolbar* :ref:`main_menu` item or toolbar pop-up menu. + +.. _doc_windows: + +Dock windows +------------ + +Standard dock windows are: + +- :ref:`object_browser` +- :ref:`inspection_panel` +- :ref:`hidefaces_panel` +- :ref:`python console` +- :ref:`property_panel` + +Dock windows can be placed in three dock areas using drag-and-drop: + +- left, +- right, +- bottom. + +By default Object browser window is placed at the left dock area, Inspection panel at the right dock area and Python console at the bottom dock area of the main window. + +Property Panel is hidden. + +Property Panel is shown on operation start in left dock area of the main window by default. + +If Object browser is shown at the same side then they will be tabbed. + +Each dock window can be closed using **Cross** window button and opened again using a corresponding command from *View - Windows* :ref:`main_menu` or alternatively using pop-up menu. + +.. figure:: /images/popup_menu.png + :align: center + + Pop-up menu for visibility of windows and toolbars + +.. _object_browser: + +Object browser +^^^^^^^^^^^^^^ + +Object browser contains all documents created in the current study. + +Each document includes standard branches where created objects are placed. + +Documents with branches are shown in Tree View. + +.. figure:: /images/object_browser.png + :align: center + + **Object browser**: Partset active + +Partset includes three branches: + +- Parameters; +- Constructions; +- Features + +Part includes the following branches: + +- Parameters; +- Constructions; +- Results; +- Fields; +- Groups; +- Features. + +New part contains only 3 empty branches: + +- Parameters; +- Constructions; +- Results. + +Features are placed one after another in the active document with default names and their results are placed into the corresponding branch. + +Examples of default names assigned automatically for :ref:`box_feature` are: + +* **Box_1**, **Box_2**, ... for Feature; +* **Box_1_1**, **Box_2_1**, ... for Result. + +Note, that a default branch is added into Tree View when the first feature of this type is created. + +Note, that the result used in feature as argument is removed. + +This child result can be restored using **Recover** feature. + +Each feature, result, construction, group, field, parameter can be renamed using *Rename* pop-up menu command. + +.. figure:: /images/popup_menu_object_browser_feature.png + :align: center + + **Feature** pop-up menu + +.. figure:: /images/popup_menu_object_browser_result.png + :align: center + + **Result** pop-up menu + +.. figure:: /images/popup_menu_object_browser_construction.png + :align: center + + **Construction** pop-up menu + +The order of features can be changed using *Move to the end* and *Move to the end and split* pop-up menu commands. They work only for Group features. The selected group or several groups will be moved to the end of features list. The *Move to the end and split* also splits the resulting group in several groups: one group per one selection. + +Folders can be used to arrange long Tree View for features. + +.. figure:: /images/object_browser_folder.png + :align: center + + **Object browser** with folder Dome: Part_1 active + +*Insert a folder before* pop-up menu command creates a new empty folder before the selected feature. The folder can be renamed. + +Features placed after/before the created folder can be moved into the folder using *Move into the previous folder* / *Move into the next folder* pop-up menu command. + +This allows to decrease the length of feature list. + +Features can be removed from the folder using *Move out before the folder* / *Move out after the folder* pop-up menu command. + +*Clean history* pop-up menu command looks for features that do not participate in other features. + +**Clean history** dialog box shows a list of unused features. After confirmation by click **Yes** button unused features are removed. + +.. figure:: /images/clean_history.png + :align: center + + **Clean history** dialog box + +*Select result* and *Select parent feature* pop-up menu commands help to navigate along Tree View. + +A feature and its result can be deleted using *Delete* pop-up menu command. + +Note that all features using the removed feature and their results will be removed simultaneously. + +**Delete feature** dialog box shows the list of features to be removed. After confirmation by click **Yes** button all these features are removed. + +.. figure:: /images/delete_feature.png + :align: center + + **Delete feature** dialog box + +.. _property_panel: + +Property panel +^^^^^^^^^^^^^^ + +.. |ok_btn| image:: /images/button_ok.png +.. |cancel_btn| image:: /images/button_cancel.png +.. |help_btn| image:: /images/button_help.png + +Property panel consists of two parts: + +- controls a container for input of parameters for the current operation; +- buttons panel containing standard buttons: + + | |ok_btn| **Ok/Apply** executes operation with defined parameters, + | |cancel_btn| **Cancel/Close** calls **Abort operation** dialog box to confirm operation abort, + | |help_btn| **Help** calls User's guide opened on page describing the current operation. + + .. figure:: /images/abort_operation.png + :align: center + + **Abort operation** dialog box + +|ok_btn| **OK/Apply** button is disabled if not all input parameters are defined or some errors are found. Error is shown as tooltip and in status bar. + +.. _inspection_panel: + +Inspection panel +^^^^^^^^^^^^^^^^ + +Inspection panel provides the list of types and quantities of all topological entities, composing the selected result, construction or feature. + +.. figure:: /images/inspection_panel.png + :align: center + + **Inspection panel** for default Box + +**Object** displays name of the selected result, construction or feature. + +**Type** characterizes the whole shape. + +The information about Point, Axis or Edge additionally shows coordinates of point / end points. + +.. figure:: /images/inspection_panel_line.png + :align: center + + **Inspection panel** for Axis + +The information about Plane, Face additionally shows coordinates of center point and direction of normal. + +.. figure:: /images/inspection_panel_face.png + :align: center + + **Inspection panel** for Face + +.. _hidefaces_panel: + +Hide Faces panel +^^^^^^^^^^^^^^^^ + +**Hide Faces** panel makes possible to hide temporary faces of any displayed object. **Hide Faces** panel looks like following: + +.. figure:: /images/hide_faces_panel.png + :align: center + + **Hide Faces** panel + +- If this panel is activated it "listens" user selection. +- If a face is selected then its name will be shown in the panel's list and hidden in the viewer. +- If user selects a group of faces (or at least a one face of this group) then whole group will be hidden and also all faces from all objects referenced by this group. +- If user will display the hidden group again (by a show operation) then the group will be removed from Hide Faces list and visibility of all referenced faces will be restored. + +Also it is possible do not to hide faces, but make them transparent. For this purpose **"Transparent"** check-box can be used. Value of the transparency can be changed in **Visualization** tab of **Preferences** dialog box. +Closing of **Hide Faces** panel restores visibility state of all objects. If it is necessary to deactivete the **Hide Faces** panel (preserving the current display state) then user has to press **"Esc"** button. + +.. _python console: + +Python console +^^^^^^^^^^^^^^ + +Python console interpreters Python commands entered manually. + +In particular, it is possible to load the python script: + +*execfile(r"/dn48/newgeom/data/example.py")* + +Pop-up menu gives the possibility to: + +- Copy the selected text to clipboard; +- Paste the text from clipboard to Python console ; +- Clear Python console; +- Dump commands from console into the specified file; +- Start/Stop writing log into the specified file. + +.. figure:: /images/python_console_popup.png + :align: center + + Pop-up menu of Python console + +.. _viewer: + +Viewer +------ + +The application supports one instance of OCC 3D viewer and is able to show only one 3D space. + +This 3D space can be represented in several view windows. New view window can be created using **Clone view** button in viewer toolbar. + +Each view windows shows its own point of view on the 3D scene. + +This point of view can be modified using viewer commands: **Panning**, **Zooming**, **Scaling**, etc. + +.. figure:: /images/2_viewers.png + :align: center + + Two view windows + +The description of OCC 3D Viewer architecture and functionality is provided in GUI module user's guide in chapter **OCC 3D Viewer**. + +.. _parameter_usage: + +Parameters +---------- + +Model parametrization can be done using parameters. + +A parameter can be created in the active partset or part by: + +- :ref:`parameter`; +- :ref:`parameters`; +- :ref:`parameter_expression`. + +Any argument in features can be defined as parameter or expression containing parameters. + +The list of features using parameters is given in **Parameters** dialog box: + + .. figure:: /images/parameters_feature.png + :align: center + + Parameters dialog box + +If a parameter value is changed, then all features where it is used are rebuilt. + +A parameter name should be unique in the active document. + +However, partset and part can have parameters with the same name. If parameter names in Partset and Part are identical, then Part parameter has a higher priority and its value will be used in the features of this part. + +In contrast to features (see :ref:`object_browser`), there is an additional option when parameters are deleted. + +.. figure:: /images/delete_parameter.png + :align: center + + Delete parameter + +After clicking **Replace** button, the selected parameter is removed but its parent parameters and features are not removed. The deleted parameter is replaced by its value. + +.. _parameter_expression: + +Create parameter on fly +^^^^^^^^^^^^^^^^^^^^^^^ + +Parameter can be created during feature creation simply by writing *variable=expression* in any editbox. + +After feature validation a new parameter with the given name **variable** and value equal to the evaluated expression appears in object browser under **Parameters** in the active partset or part. + +.. _preferences: + +SHAPER preferences +------------------ + +Description of General application preferences and **Preferences** dialog box is provided in GUI module user's guide in chapter **Setting Preferences**. + +SHAPER preferences define visualization of objects, visualization during selection, edition. New preferences can be used right after modification or later after activation of SHAPER module. + +To call **Preferences** dialog box: + +#. select in the Main Menu *File - > Preferences* item or +#. use **Ctrl+P** shortcut. + +SHAPER preferences contains the following tabs: + +- :ref:`visualization_preferences`; +- :ref:`plugins_preferences`; +- :ref:`shortcuts_preferences`; +- :ref:`windows_preferences`. +- :ref:`sketch_preferences`. +- :ref:`viewer_preferences`. + +Visualization tab is activated by default when **Preferences** dialog box is opened in the active SHAPER module. + +Other tabs are activated by click on tab header. + +.. _visualization_preferences: + +Visualization tab +^^^^^^^^^^^^^^^^^ + +This tab defines presentation of objects displayed in OCC 3D viewer. + +.. figure:: /images/visualization_preferences.png + :align: center + + **Preferences**: Visualization tab + +**Input fields**: + +- **Selection color** defines a color for selected objects; +- **Result color** selects default shading color for objects from **Results** branch; +- **Group color** selects default color for objects from **Groups** branch; +- **Construction color** selects default color for objects from **Constructions** branch; +- **Part color** selects default color for parts shown in Partset; +- **Field color** selects default color for objects from **Fields** branch; +- **Body deflection coefficient** defines default deflection coefficient for objects from **Results** branch. A smaller coefficient provides better quality of a shape in the viewer; +- **Construction deflection coefficient** defines default deflection coefficient for objects from **Constructions** branch. A smaller coefficient provides better quality of a shape in the viewer; +- **Reference shape wireframe color in operation** selects default color used for wireframe visualization of objects used in active operation; +- **Result shape wireframe color in operation** selects default color used for wireframe visualization of result in active operation. Click **See preview** button to show result; +- **Multi selector item color in operation** selects default color used for visualization of objects selected in property panel to distinguish them among all objects used in active operation; +- **Color of removed feature in operation** selects default color used for visualization of sketch entities to be removed during **Trim/Split** operations; +- **Color of sketch plane** selects default shading color for sketch plane; +- **Hidden faces transparency** defines default transparency value for hidden faces; +- **Dimension arrow size** defines default size of arrows for extension line showing dimensional constraint; +- **Dimension font** defines font used for value of dimensional constraint; +- **Dimension value size** defines default size of value for dimensional constraint; +- **Sketch dimension color** defines default color of dimensional constraint; +- **Construction plane color** selects default color for Construction planes; +- **Sketch entity color** selects default color for sketch objects; +- **Sketch external entity color** selects default color for external objects selected as reference during sketch creation/edition; +- **Sketch auxiliary entity color** selects default color for sketch auxiliary objects; +- **Sketch overconstraint color** selects default color for a sketch with redundant constraints; +- **Sketch fully constraint color** selects default color for a sketch with zero degrees of freedom. + +To redefine any color click on the corresponding line to access **Select color** dialog box + +.. figure:: /images/select_color.png + :align: center + + **Preferences**: **Select color** dialog box + +Preferences for sketch are applicable during sketch creation/edition operation. + +.. _plugins_preferences: + +Plugins tab +^^^^^^^^^^^ +Plugins tab defines folders where plugins and resources are located. + +.. figure:: /images/plugins_preferences.png + :align: center + + **Preferences**: Plugins tab + +**Input fields**: + +- **Default path** selects default folder where plugins are located. Click on **Open** button opens standard **Find directory** dialog box to navigate to desired folder; + +- **Import initial directory** selects default folder where resources are located. Click on **Open** button opens standard **Find directory** dialog box to navigate to desired folder. + +.. figure:: /images/open_button.png + :align: center + + **Open** button + +.. figure:: /images/find_directory.png + :align: center + + **Find directory** dialog box + + +.. _shortcuts_preferences: + +Shortcuts tab +^^^^^^^^^^^^^ + +Shortcuts tab defines shortcut keys for different operations. + +.. figure:: /images/shortcuts_preferences.png + :align: center + + **Preferences**: Shortcuts tab + +- **Add parameter in parameters manager dialog** defines shortcut keys for adding parameter in parameters manager dialog box. + +.. _windows_preferences: + +Windows tab +^^^^^^^^^^^ + +Windows tab contains definitions for the module windows management. + +.. figure:: /images/windows_preferences.png + :align: center + + **Preferences**: Windows tab + +- **Use HideFaces panel in operation** if the checkbox is checked then HideFaces panel will be launched automatically on launching an operation where using of this panel is considered. + +.. _sketch_preferences: + +Sketch tab +^^^^^^^^^^ + +Sketch tab defines properties of coordinate planes shown for selection of sketch plane when no convenient objects are shown in OCC 3D viewer. + +.. figure:: /images/sketch_preferences.png + :align: center + + **Preferences**: Sketch tab + +**Input fields**: + +- **Size** defines size of coordinate planes; +- **Thickness** defines thickness of coordinate plane borders; +- **Rotate to plane when selected** check-box turns on/off automatic switch the viewer to the top view for the selected sketch plane. +- **Angular tolerance** defines defines an angular tolerance for automatic creation of horizontal and vertical constraints; +- **Default spline weight** defines default weight for B-spline nodes during creation. The default value can be changed by editing of the spline; +- **Cursor for sketch operation** defines a cursor which indicates a launched sketcher sub-operation. +- **Create sketch entities by dragging** defines a style of sketch etities creation. It concerns creation of lines, rectangles, circles, arcs, ellipses, elliptic arcs. If it is switched ON then points of objects have to be defined by mouse press - mouse move - mouse release. Otherwise every point of an object has to be defined by mouse click; + +.. _viewer_preferences: + +Viewer tab +^^^^^^^^^^ + +Viewer tab defines selection in OCC 3D viewer properties. + +.. figure:: /images/viewer_preferences.png + :align: center + + **Preferences**: Viewer tab + +**Input fields**: + +- **Default Selection** defines objects to be selected by mouse click in OCC 3D viewer: + + - **Faces** check-box turns on/off selection of faces; + - **Edges** check-box turns on/off selection of edges; + - **Vertices** check-box turns on/off selection of vertices; + +- **Selection sensitivity** defines size of area around object in pixels, in which mouse click selects object inside this area: + + - **Vertex** defines selection sensitivity for vertices; + - **Edge** defines selection sensitivity for edges. + +.. _toolbars_management: + +Toolbars management +------------------- + +.. _toolbars_dialog: + +**Toolbars** dialog box +^^^^^^^^^^^^^^^^^^^^^^^ +To edit the current tool bars structure select in the Main Menu *Edit - > Edit toolbars* item. +The following dialog box with existing toolbars appears: + +.. figure:: /images/Toolbars.png + :align: center + + **Toolbars** dialog box + +**Input fields**: + +- **Toolbars** window contains list of toolbars names. Number of commands in each tool bar is shown in brackets. +- **Add** button creates a new toolbar. Click on **Add** button opens :ref:`create_toolbar`; +- **Edit** button calls :ref:`edit_toolbar` for currently selected tool bar; +- **Delete** button removes currently selected tool bar. Click on **Delete** button opens warning dialog box. After confirmation by click **Yes** button the selected toolbar is deleted. Click **No** button cancels removing of the selected toolbar; +- **Reset** button restores modified tool bars structure to default state; +- **OK** button closes the dialog box, stores result of tool bars edition and updates Shaper tool bars; +- **Cancel** button closes the dialog box without modification of tool bars. + +.. figure:: /images/delete_toolbar.png + :align: center + + Warning dialog box + +.. _create_toolbar: + +**Create toolbar** dialog box +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Input fields** of **Create toolbar** dialog box: + +.. figure:: /images/create_toolbar.png + :align: center + + **Create toolbar** dialog box + +- **Name of a new toolbar** defines name of the new tool bar. The name of tool bar has to be unique. If user defines a not unique name then a warning appears and a new tooolbar with not unique name is not created; +- **Ok** button closes the dialog box and add a new tool bar of the module into **Toolbars** window; +- **Cancel** button closes the dialog box without addition of a new tool bar. + +.. figure:: /images/name_toolbar.png + :align: center + + **Warning** dialog box + +.. _edit_toolbar: + +**Edit toolbar** dialog box +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Input fields** of **Edit toolbar** dialog box: + +.. figure:: /images/EditToolbar.png + :align: center + + **Edit toolbar** dialog box + +- **Toolbar name** non-editable field displays name of modified tool bar; +- **Out of toolbars** window contains list of commands which are not included into any tool bar and separator definition "------"; +- **In the toolbar** window contains list of commands which are defined in the current tool bar. Items in this window are listed according to order of commands in the toolbar; +- **Right arrow** button transfers currently selected item from **Out of toolbars** window to **In the toolbar** window and puts new item before the selected item in **In the toolbar** window. + If there is no selected item in **In the toolbar** window then new item will be added at the end of items list. In order to clear current selection it is necessary to click in empty space of the window. +- **Left arrow** button transfers currently selected item from **In the toolbar** window into **Out of toolbars** window; +- **Up** and **Down** buttons change position of selected command in **In the toolbar** window; +- **Ok** button closes the dialog box, stores result of edition; +- **Cancel** button closes the dialog box without modification of tool bar content. diff --git a/doc/gui/TUI_tutorial.rst b/doc/gui/General/TUI_tutorial.rst similarity index 100% rename from doc/gui/TUI_tutorial.rst rename to doc/gui/General/TUI_tutorial.rst diff --git a/doc/gui/Tutorial.rst b/doc/gui/General/Tutorial.rst similarity index 86% rename from doc/gui/Tutorial.rst rename to doc/gui/General/Tutorial.rst index d9bc3eb9a..e00117dd6 100644 --- a/doc/gui/Tutorial.rst +++ b/doc/gui/General/Tutorial.rst @@ -19,7 +19,7 @@ At this step we will create a regular hexagon. - Select **XOY** plane in the view - Click **Set plane view** button in the Sketch property panel -.. figure:: images/tutorial1_1.png +.. figure:: /images/tutorial1_1.png :align: center Skecth plane XOY @@ -27,7 +27,7 @@ At this step we will create a regular hexagon. - Start :ref:`Line ` creation via Main Menu *Sketch - > Line* - Pick 3 points in the view one by one and select the first one at the end to get a triangle: -.. figure:: images/tutorial1_2.png +.. figure:: /images/tutorial1_2.png :align: center 3 Lines forming a triangle @@ -37,14 +37,14 @@ At this step we will create a regular hexagon. - Click on the eye icon on the left of the origin item to show it in the view - Select both origin and the bottom vertex of the triangle in the view (use **Shift** key for multi-selection) -.. figure:: images/tutorial1_3.png +.. figure:: /images/tutorial1_3.png :align: center Origin and triangle - Create :ref:`Coincident ` constraint via **Coincident** button in Sketch toolbar -.. figure:: images/tutorial1_4.png +.. figure:: /images/tutorial1_4.png :align: center Triangle vertex coincident with origin @@ -53,7 +53,7 @@ At this step we will create a regular hexagon. - Select both **OY** axis and the upper side of the triangle in the view - Create :ref:`Perpendicular ` constraint via **Pependicular** button in Sketch toolbar -.. figure:: images/tutorial1_5.png +.. figure:: /images/tutorial1_5.png :align: center Upper triangle side perpendicular to OY axis @@ -62,7 +62,7 @@ At this step we will create a regular hexagon. - Create :ref:`Equal ` constraint via **Equal** button in Sketch toolbar - Make the upper and the right sides equal length in the same way -.. figure:: images/tutorial1_6.png +.. figure:: /images/tutorial1_6.png :align: center Equilateral triangle @@ -70,14 +70,14 @@ At this step we will create a regular hexagon. - Select the left side of the triangle - Check **Auxiliary** check box in the property panel and click **Apply** button -.. figure:: images/tutorial1_7.png +.. figure:: /images/tutorial1_7.png :align: center Line property panel - Make the right side auxiliary in the same way -.. figure:: images/tutorial1_8.png +.. figure:: /images/tutorial1_8.png :align: center The lateral sides are auxiliary @@ -87,14 +87,14 @@ At this step we will create a regular hexagon. - Select origin in the view as a center of rotation - Set **Total number** of objects equal to 6 -.. figure:: images/tutorial1_9.png +.. figure:: /images/tutorial1_9.png :align: center Angular copy parameters - Click **Apply** button -.. figure:: images/tutorial1_10.png +.. figure:: /images/tutorial1_10.png :align: center Regular hexagon @@ -103,21 +103,21 @@ At this step we will create a regular hexagon. - Start creation of :ref:`Length ` constraint via **Length** button in Sketch toolbar - Set length expression equal to "a=115.4" and press **Enter** -.. figure:: images/tutorial1_11.png +.. figure:: /images/tutorial1_11.png :align: center Fully fixed regular hexagon - Click **Apply** button in the *Skecth* property panel to finish the sketch creation -.. figure:: images/tutorial1_12.png +.. figure:: /images/tutorial1_12.png :align: center Finished Sketch - Check item corresponding to the created parameter **a** under **Part_1 / Parameters** node -.. figure:: images/tutorial1_13.png +.. figure:: /images/tutorial1_13.png :align: center Parameter created during the Sketch operation @@ -128,7 +128,7 @@ Step 2. Polyline - Start :ref:`Parameter ` creation via Main Menu *Part - > Parameter* - Set parameter name = "h", set parameter expression = "90", set comment = "nut height" -.. figure:: images/tutorial2_0.png +.. figure:: /images/tutorial2_0.png :align: center Creation of parameter h = 90 @@ -137,7 +137,7 @@ Step 2. Polyline - Start :ref:`Point ` creation via Main Menu *Construction - > Point* - Set x = 50, y = 0, z = 0 -.. figure:: images/tutorial2_1.png +.. figure:: /images/tutorial2_1.png :align: center Construction of point (50, 0, 0) @@ -148,7 +148,7 @@ Step 2. Polyline - Click right mouse button and select **Color...** item in the popup menu - Select blue color and click **OK** button -.. figure:: images/tutorial2_2.png +.. figure:: /images/tutorial2_2.png :align: center Points created from scratch @@ -157,14 +157,14 @@ Step 2. Polyline - Select all the 7 points (use **Shift** key for multi-selection) - Check **Closed** check box -.. figure:: images/tutorial2_3.png +.. figure:: /images/tutorial2_3.png :align: center Creation of closed polyline from 7 points - Click **Apply** button in the property panel -.. figure:: images/tutorial2_4.png +.. figure:: /images/tutorial2_4.png :align: center Closed Polyline @@ -175,14 +175,14 @@ Step 3. Face - Start :ref:`Face ` creation via Main Menu *Build - > Face* - Select **Polyline_1_1** in the object browser under **Part_1 / Results** node -.. figure:: images/tutorial3_1.png +.. figure:: /images/tutorial3_1.png :align: center Construction of face from a polyline - Click **Apply** button in the property panel -.. figure:: images/tutorial3_2.png +.. figure:: /images/tutorial3_2.png :align: center Face @@ -194,14 +194,14 @@ Step 4. Revolution - Select the face created at step 3 in the view - Click on axis input field in the property panel and select **OZ** axis in the view -.. figure:: images/tutorial4_1.png +.. figure:: /images/tutorial4_1.png :align: center Revolution around OZ by 360 degrees - Click **Apply** button in the property panel -.. figure:: images/tutorial4_2.png +.. figure:: /images/tutorial4_2.png :align: center Solid created by rotation of face @@ -216,14 +216,14 @@ Step 5. Extrusion - Select the bottom face of the revolution shape as **From** plane - Select the top face of the revolution shape as **To** plane -.. figure:: images/tutorial5_1.png +.. figure:: /images/tutorial5_1.png :align: center Extrusion along OZ axis by bounding planes - Click **Apply** button in the property panel -.. figure:: images/tutorial5_2.png +.. figure:: /images/tutorial5_2.png :align: center Solid created by extrusion of sketch @@ -234,14 +234,14 @@ Step 6. Common - Start :ref:`Common ` creation via Main Menu *Features - > Common* - Select the extrusion and the revolution in the object browser under **Part_1 / Results** node (use **Shift** key for multi-selection) -.. figure:: images/tutorial6_1.png +.. figure:: /images/tutorial6_1.png :align: center Common creation - Click **Apply** button in the property panel -.. figure:: images/tutorial6_2.png +.. figure:: /images/tutorial6_2.png :align: center The revolution and the extrusion common part @@ -252,21 +252,21 @@ Step 7. Fillet - Start :ref:`Fillet ` creation via Main Menu *Features - > Fillet* - Select the edge -.. figure:: images/tutorial7_1.png +.. figure:: /images/tutorial7_1.png :align: center Select edge for a Fillet - Select **Radius** parameter equal to 10 -.. figure:: images/tutorial7_2.png +.. figure:: /images/tutorial7_2.png :align: center Fillet with radius = 10 - Click **Apply** button in the property panel -.. figure:: images/tutorial7_3.png +.. figure:: /images/tutorial7_3.png :align: center Fillet @@ -278,14 +278,14 @@ Step 8. Box - Start :ref:`Box ` creation via Main Menu *Primitives - > Box* - Set **DX** = 10, **DY** = 120, **DZ** = 20 -.. figure:: images/tutorial8_1.png +.. figure:: /images/tutorial8_1.png :align: center Box creation - Click **Apply** button in the property panel -.. figure:: images/tutorial8_2.png +.. figure:: /images/tutorial8_2.png :align: center Box @@ -298,14 +298,14 @@ Step 9. Translation - Select the box in the view - Set **DX** = -10, **DY** = 20, **DZ** = 70 -.. figure:: images/tutorial9_1.png +.. figure:: /images/tutorial9_1.png :align: center Box translation - Click **Apply** button in the property panel -.. figure:: images/tutorial9_2.png +.. figure:: /images/tutorial9_2.png :align: center Translated Box @@ -318,14 +318,14 @@ Step 10. Angular Copy - Click on axis input field in the property panel and select **OZ** axis in the view - Set **Nb copies** parameter equal to 6 -.. figure:: images/tutorial10_1.png +.. figure:: /images/tutorial10_1.png :align: center Angular Copy around OZ - Click **Apply** button in the property panel -.. figure:: images/tutorial10_2.png +.. figure:: /images/tutorial10_2.png :align: center Copied Box @@ -339,7 +339,7 @@ Step 11. Cut - Select the fillet object in the view as a main object - Select the angular copy object in the object browser as a tool object -.. figure:: images/tutorial11_1.png +.. figure:: /images/tutorial11_1.png :align: center Cut creation @@ -349,7 +349,7 @@ Step 11. Cut - Click right mouse button and select **Color...** item in the popup menu - Set (R: 255, G: 214, B: 0) color and click **OK** button -.. figure:: images/tutorial11_2.png +.. figure:: /images/tutorial11_2.png :align: center Cut diff --git a/doc/gui/tutorial.py b/doc/gui/General/tutorial.py similarity index 100% rename from doc/gui/tutorial.py rename to doc/gui/General/tutorial.py diff --git a/doc/gui/TUI_scripts.rst.in b/doc/gui/TUI_scripts.rst.in new file mode 100644 index 000000000..82a4d8b36 --- /dev/null +++ b/doc/gui/TUI_scripts.rst.in @@ -0,0 +1,9 @@ +Examples of TUI scripts +======================= + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + TUI_tutorial.rst + diff --git a/doc/gui/build_index.py b/doc/gui/build_index.py index ed63e9ad6..09e22cbe6 100755 --- a/doc/gui/build_index.py +++ b/doc/gui/build_index.py @@ -22,62 +22,87 @@ ## and prepares building of help documentation by sphinx ### +import argparse import os -import sys +import os.path as osp +import re import shutil +import sys from xml.dom.minidom import parse -aBuildDir = sys.argv[1] -aSourcesDir = sys.argv[2] -aSrcPath = aSourcesDir + os.sep + "../../src" - -aConfigPath = aSrcPath + os.sep + "Config/plugins.xml.in" - -def findDir(theConfFile): +def find_dir(src_path, cfg_file): """Find a name of a directory where the given config file exists""" - aSrcList = os.listdir(aSrcPath) - for aDir in aSrcList: - aPath = aSrcPath + os.sep + aDir - aConfPath = aPath + os.sep + theConfFile - if os.path.isdir(aPath) and (os.path.exists(aConfPath) or os.path.exists(aConfPath + ".in")): - return aDir + entities = os.listdir(src_path) + for entity in entities: + path = osp.join(src_path, entity) + cfg_path = osp.join(path, cfg_file) + if not osp.isdir(path): + continue + if not osp.exists(cfg_path) and not osp.exists(cfg_path + '.in'): + continue + if osp.exists(osp.join(path, 'doc')): + return osp.join(path, 'doc') return None -## Find accessible plugins from plugins.xml configuration file -aPluginList = [] -# A map to avoid duplication of plugins -aPluginsMap = {} -aDomObj = parse(aConfigPath) -aPluginsList = aDomObj.getElementsByTagName("plugin") -for plugin in aPluginsList: - aLibName = plugin.getAttribute("library") - if not aLibName: - aLibName = plugin.getAttribute("script") - aConfigFile = plugin.getAttribute("configuration") +def main(src_dir, build_dir): + """Main function""" + src_path = osp.realpath(osp.join(src_dir, *[os.pardir]*2, 'src')) + config_file = osp.join(src_path, 'Config', 'plugins.xml.in') + + ## Find accessible plugins from plugins.xml configuration file + processed = [] + + indices = [] + tui_scripts = [] - if aLibName and aConfigFile and not aLibName in aPluginsMap: - aPluginsMap[aLibName] = True - aLibDir = findDir(aConfigFile) - if not aLibDir is None: - aPluginDocDir = aSrcPath + os.sep + aLibDir + os.sep + "doc" - if os.path.exists(aPluginDocDir): - ## Copy all files to a building directory - aDocDist = aBuildDir + os.sep + aLibName - if os.path.exists(aDocDist): - shutil.rmtree(aDocDist) - shutil.copytree(aPluginDocDir, aDocDist) - aPluginList.append(aLibName) + doc = parse(config_file) + plugins = doc.getElementsByTagName('plugin') + for plugin in plugins: + plugin_name = plugin.getAttribute('library') + if not plugin_name: + plugin_name = plugin.getAttribute('script') + if not plugin_name or plugin_name in processed: + continue + config = plugin.getAttribute('configuration') + if not config: + continue + lib_dir = find_dir(src_path, config) + if lib_dir: + ## Copy plugin's documenation folder to the build directory + dist_dir = osp.join(build_dir, plugin_name) + if osp.exists(dist_dir): + shutil.rmtree(dist_dir) + shutil.copytree(lib_dir, dist_dir) + ## Collect index file + indices.append(osp.join(plugin_name, plugin_name + '.rst')) + ## Collect TUI scripts + tui_files = sorted(f for f in os.listdir(lib_dir) if \ + osp.isfile(osp.join(lib_dir, f)) and re.match('TUI_.*\.rst', f)) + tui_scripts += [osp.join('..', plugin_name, i) for i in tui_files] + ## Mark plugin as processed + processed.append(plugin_name) -## Modify index.rst file accordingly -aIndexFile = open(aSourcesDir + os.sep + "index.rst.in", 'r') -aIndexLines = aIndexFile.readlines() -aIndexFile.close() + ## Generate index file + in_file = osp.join(src_dir, 'index.rst.in') + out_file = osp.join(build_dir, 'index.rst') + with open(in_file, 'r') as fin, open(out_file, 'w') as fout: + lines = fin.readlines() + idx = lines.index('\n') + lines = lines[:idx] + [' {}\n'.format(i) for i in indices] + lines[idx+1:] + fout.writelines(lines) -## Add list of plugins after toctree directive -aIndexLines.append('\n') -for aLibName in aPluginList: - aIndexLines.append(" " + aLibName + "/" + aLibName + ".rst\n") + ## Generate TUI scripts index + in_file = osp.join(src_dir, 'TUI_scripts.rst.in') + out_file = osp.join(build_dir, 'General', 'TUI_scripts.rst') + with open(in_file, 'r') as fin, open(out_file, 'w') as fout: + lines = fin.readlines() + idx = lines.index('\n') + lines = lines[:idx] + [' {}\n'.format(i) for i in tui_scripts] + lines[idx+1:] + fout.writelines(lines) -aNewIndex = open(aBuildDir + os.sep + "index.rst", 'w') -aNewIndex.writelines(aIndexLines) -aNewIndex.close() +if __name__ == '__main__': + parser = argparse.ArgumentParser(description='Generate index file from source directory') + parser.add_argument('build_dir', help='build directory') + parser.add_argument('src_dir', help='source directory') + args = parser.parse_args() + sys.exit(main(args.src_dir, args.build_dir)) diff --git a/doc/gui/index.rst.in b/doc/gui/index.rst.in index a2d14d5c2..bde9f7476 100644 --- a/doc/gui/index.rst.in +++ b/doc/gui/index.rst.in @@ -6,9 +6,11 @@ Welcome to SHAPER documentation! ================================== -- :ref:`introduction` -- :ref:`tutorial` - .. toctree:: :titlesonly: :maxdepth: 3 + + General/Introduction.rst + General/Tutorial.rst + + General/TUI_scripts.rst -- 2.39.2