geom/doc/salome/gui/GEOM/input/creating_polyline.doc

/*!

\page create_polyline_page 2D Polyline

The 2D Polyline allows drawing arbitrary 2D shapes. 

To create a <b>2D Polyline</b> select in the main menu  <b>New Entity -> Basic -> 2D Polyline</b>.

\image html polyline_dlg.png

A polyline represents a section or a set of sections. Each section is constructed from a sequence of 2D points
connected  by either linear segments or an interpolation curve. Every section has its own attributes:
- \b Name, 
- \b Type (Polyline or Spline),
- \b Closed flag.

A created Polyline represents a shape that lies on the XOY plane. Its type can be one of the following:
- \b Vertex for a single section with only 1 point.
- \b Wire for a single section with 2 or more points. A Wire can have multiple edges for more then 2 points if the section type is Polyline. A single edge in the resulting wire is obtained for a Spline or Polyline with 2 points.
- \b Compound of Wires and/or Vertices if there are several sections.

For the moment only one reference coordinate system for polyline creation is supported, which is the XOY plane of the <b>Global coordinate system</b>. 
\b Restore button orientates the viewer correspondingly to the chosen working plane and fits the scene to show all objects.
For the moment this button works with only one plane.

It is possible to import a shape in this dialog using <b>Import polyline</b> selection button. An imported object should meet the conditions for polyline shapes mentioned above. If a valid shape is selected, when the dialog is opened, it is initialized by this shape.
Though the shape can be on any plane, the imported polyline will be defined on XOY plane only due to the limitation.

The group \b Sections in this dialog represents the Polyline construction framework. 

The buttons <b>Undo</b> and <b>Redo</b> allow to undo or redo the changes of the polyline.

<b>Insert new section</b> button opens the corresponding dialog:

\image html polyline_dlg_add_section.png

In this dialog it is possible to choose:
- \b Name of section;
- \b Type of section;
- Set \b Closed flag.

To create a new section, click \b Add button. \b Cancel button is used to cancel this operation.
After clicking \b Add button a new section appears in the list. Its name is generated automatically depending on its type, closed or opened state and the number of points (equal to 0 after creation).

To modify section parameters, double-click on a section in the list. In this case the following dialog appears:

\image html polyline_dlg_edit_section.png

To apply the modifications, click \b Ok button.

<b>Addition mode</b> allows adding points to a section. Select a particular section in the list of sections
and left-click in the viewer to add new nodes to the section. A section preview is recomputed after each click.

<b>Modification mode</b> and <b>Detection mode</b> are not implemented for the moment.

\b Remove button allows removing a section. It is available if all modes are deactivated and one section is selected.

<b>Join selected sections</b> button is available in modification mode if two or more sections are selected. It is used to
merge several sections into the first one from the selection list. The points of the merged sections are appended at the end of the list of points of the first section.

Some actions are available via the context menu activated by right mouse button click.
- <b>Join all sections</b> - joins all defined sections into the first one.
- \b Join - joins two or more selected sections.
- <b>Clear all</b> - removes all selected sections. 
- <b>Set closed</b> - sets \b Closed flag for all selected section.
- <b>Set open</b>  - unset \b Closed flag for all selected sections.
- <b>Set polyline</b> - sets the type of all selected sections to Polyline.
- <b>Set spline</b>  - set the type of all selected sections to Spline. 

Different actions are available depending on the mode and selection.  

<h2>TUI Commands</h2>

To create the 2D polyline in TUI Polyline2D interface is used.

<em>pl = geompy.Polyline2D()</em> - returns an instance of Polyline2D interface <i>pl</i>.

See the \ref gsketcher.Polyline2D "Polyline2D" interface documentation for more information.

Our <b>TUI Scripts</b> provide you with useful examples of the use of
\ref tui_creation_polyline "2D Polyline".
*/