Merge branch 'V8_4_BR'

[modules/gui.git] / doc / salome / gui / input / occ_3d_viewer.doc

/*!

\page occ_3d_viewer_page OCC 3D Viewer

<h2>Operations</h2>

The functionalities of OCC viewer are available via its Viewer
Toolbar. Buttons marked with small downward triangles have extended
functionality which can be accessed by locking on them with left mouse
button.

\image html occviewer_toolbar.png
<hr>

\image html occ_view_camera_dump.png

<b>Dump View</b> - exports an object from the viewer in bmp, png,
jpeg or another image format.
<hr>

\image html occ_view_style_switch.png

<b>Interaction style switch</b> - allows to switch between standard
and "keyboard free" interaction styles. "Keyboard free" style allows
to process all view transformations without using keyboard (only by
mouse). By default, rotation in this mode is performed by left mouse
button, panning - by middle mouse button, zooming - by right mouse 
button. Selection in view by pressing "s" key works in both
styles.
<hr>

\image html occ_view_zooming_style_switch.png

<b>Zooming style switch</b> - allows to switch between standard
(zooming at the center of the view) and advanced (zooming at the
current cursor position) zooming styles.
<hr>

\image html occ_view_triedre.png

<b>Show/Hide Trihedron</b> - shows or hides coordinate axes.
<hr>

\image html occ_view_preselection.png

<b>Enable/Disable preselection</b> - enables or disables preselection (highlighting) in the view.
<hr>

\image html occ_view_selection.png

<b>Enable/Disable selection</b> - enables or disables selection in the view.
<hr>

\image html occ_view_fitall.png

<b>Fit all</b> - represents all displayed objects in the
visible area.
<hr>

\image html occ_view_fitarea.png

<b>Fit area</b> - resizes the view to place in the visible area only
the contents of a frame drawn with pressed left mouse button.
<hr>

\image html occ_view_fitselection.png

<b>Fit selection</b> - fits view contents to the current selection.
<hr>

\image html occ_view_zoom.png

<b>Zoom</b> - allows to zoom in and out.
<hr>

\image html occ_view_pan.png

<b>Panning</b> - if the represented objects are greater that the
visible area and you don't wish to use <b>Fit all</b> functionality,
click on this button and you'll be able to drag the scene to see its
remote parts.
<hr>

\image html occ_view_glpan.png

<b>Global panning</b> - allows to select a point to be the center of a scene
representing all displayed objects in the visible area.
<hr>

\image html occ_view_rotation_point.png

<b>Change rotation point</b> - allows to choose the point around
which the rotation is performed.

\image html set_rotation_point_dialog1.png

By default the rotation point is located in the Center of the bounding
box of represented objects.

\image html set_rotation_point_dialog2.png

Unchecking <b>Use Bounding Box Center</b> check-box allows you to
change rotation point:

- <b>Set to Origin</b> button sets the rotation point to 
origin of coordinates: (0, 0, 0).

- <b>Gravity Center of Selected Object</b> button allows using the 
gravity center of the object selected in the viewer as the center of 
the rotation point.
When you click this button, you should first choose the type of 
selectable object: Point, Edge, Face or Solid and only then proceed 
with selection in the viewer.

- Also you can define the coordinates of the rotation point manually.

<hr>

\image html occ_view_rotate.png

<b>Rotation</b> - allows to rotate the scene using the mouse.
<hr>

\image html occ_view_front.png
\image html occ_view_back.png
\image html occ_view_top.png
\image html occ_view_bottom.png
\image html occ_view_left.png
\image html occ_view_right.png

These buttons orientate the scene strictly about coordinate axes:
\b Front, \b Back, \b Top, \b Bottom, \b Left or \b Right side.
<hr>

\image html occ_view_anticlockwise.png

<b>Rotate counterclockwise</b> - rotates view 90 @htmlonly &deg; @endhtmlonly counterclockwise.
<hr>

\image html occ_view_clockwise.png

<b>Rotate clockwise</b> - rotates view 90 @htmlonly &deg; @endhtmlonly clockwise.
<hr>

\image html occ_view_orthographic.png

<b>Ortographic projection</b> - default OCC viewer projection mode.
<hr>

\image html occ_view_perspective.png

<b>Perspective projection</b> - perspective OCC viewer projection mode.
<hr>

\image html occ_view_stereo.png

<b>Stereo projection</b> - stereoscopic rendering of the view.
\note Activation of this mode also switches the view to perpective projection 
in case if the orthographic one has been active.
\note By default, quad-buffered stereo is activated, if it is supported by the graphic card. 
If no stereo capabilities are available, an error message is shown.
\note The stereoscopic view settings can be defined in 
\ref occ_preferences "OCC 3D Viewer" preferences.

<hr>

\image html occ_view_reset.png

<b>Reset</b> - restores the default position (isometric) of objects in
the scene.
<hr>

\image html occ_view_shoot.png

<b>Memorize view</b> - saves the current position of objects in the
scene.
<hr>

\image html occ_view_presets.png

<b>Restore view</b> - restores the saved position of objects in the
scene.
<hr>

\image html occ_view_clone.png

<b>Clone view</b> - opens a new duplicate scene.
<hr>

\anchor clipping_planes

\b Clipping allows creating cross-section views (clipping planes)
of your mesh.

To create a clipping plane, click on the \b New button in the dialog and choose how it will be defined by \b Absolute or \b Relative coordinates.

<b>Absolute Coordinates</b>

\image html Clipping_Absolute.png

- <b>Base point</b> - allows defining the coordinates of the base
  point for the clipping plane.

  - <b>Reset</b> - returns the base point to coordinate origin.

- <b>Direction</b> - allows defining the orientation of the
  clipping plane.

        - <b>Invert</b> - allows selecting, which part of the object will be
    removed and which will remain after clipping.
    
<b>Relative mode</b>  

\image html Clipping_Relative.png

- \b Orientation ( ||X-Y, ||X-Z or ||Y-Z).

- \b Distance between the opposite extremities of the boundary box of 
represented objects, if it is set to 0.5 the boundary box is split in two halves.

- \b Rotation (in angle degrees) <b>around X</b> (Y to Z) and <b>around 
Y</b> (X to Z) (depending on the chosen Orientation)

The other parameters are available in both modes : 
- <b>Active</b> checkbox is used to apply/erase current plane and it's affect to/from view.
- <b>Delete</b> removes the active clipping plane and discards it's view changes.
- <b>Disable all</b> deactivates all created clipping planes and clears <b>Auto Apply</b> checkbox.
- <b>Preview</b> check-box shows the clipping plane in the <b>3D Viewer</b>.
- <b>Auto Apply</b> check-box allows you to see the result of clipping
in the <b>3D Viewer</b> immediately. Be careful, it is not a preview
and Close button could not cancel the applied modifications.

It is also possible to interact with the clipping plane directly in 3D 
view using the mouse. 

<hr>

\image html occ_view_scaling.png

<b>Scaling</b> - represents objects deformed (stretched or stuffed)
along the axes of coordinates.
<hr>

\image html occ_view_graduated_axes.png

<b>Graduated axes</b> - allows to define axes parameters and graduate
them.

\image html graduatedaxes2.png

- <b>Axis name</b> - if checked the axis name is displayed in the viewer.

  - <b>Name</b> - allows to redefine the axis name.

  - <b>Font</b> - allows to define the font color of the axis name.

- <b>Labels</b> - if checked the labels are displayed in the viewer.

  - <b>Number</b> - allows to define the number of labels.

  - <b>Offset</b> - allows to define the distance between axis and labels.

  - <b>Font</b> - allows to define the font color of labels names.

- <b>Tick marks</b> - if checked the tick marks are displayed in the viewer.

  - <b>Length</b> - allows to define the length of tick marks.

- <b>Is visible</b> - if checked the graduated axes are displayed in the viewer.

<hr>

\image html occ_view_ambient.png

<b>Toggle ambient light</b> - toggle "keep only ambient light" flag
on/off.
<hr>

\image html occ_view_minimized.png
\image html occ_view_maximized.png

<b>Minimize/Maximize</b> - these buttons allow switching the current
view area to the minimized / maximized state.
<hr>

\image html occ_view_return_3d_view.png

<b>Return to 3D</b> - this button switches from 2D view projection back to the 3D view mode.
<hr>

\image html occ_view_sync.png

<b>Synchronize view</b> - allows to synchronize 3d view
parameters. This button has two states - checked and
unchecked. Clicking on this button opens a drop-down menu listing the
compatible 3d views. As soon as the user selects any view from the
list, the parameters (view point, position, zoom coefficient, etc.) of
the current view are synchronized with the selected view (static
synchronization).

In addition, when this button is in the "checked" state, the dynamic
synchronization of the views is performed, i.e. any zoom, pan, rotate
or other view operation done in one view is automatically applied to
the other view.
<hr>

\image html occ_view_ray_tracing.png

\anchor ray_tracing

<b>Ray tracing</b> - allows to switch between rendering methods in run-time 
in the current OCCT 3D view. It can be used to produce images with photorealistic quality.

\image html doc_ray_tracing.png

- <b>Ray tracing</b> - specifies rendering mode: OpenGL rasterization (by default) or GPU ray-tracing.

  - <b>Depth</b> - defines maximum ray-tracing depth.
  
  - <b>Specular reflections</b> - enables/disables specular reflections.
  
  - <b>Adaptive anti-aliasing</b> - enables/disables adaptive anti-aliasing.
    
  - <b>Shadows rendering</b> - enables/disables shadows rendering.
  
  - <b>Transparent shadow</b> - enables/disables light propagation through transparent media.
  
<hr>

\image html occ_view_env_texture.png

\anchor env_texture

<b>Environment texture</b> - allows to set parameters for environment texture.
This is a special mode of texture mapping when specular reflection of environment texture 
is simulated by OpenGL using a special texture coordinates generation algorithm (a sphere map).

\image html doc_env_texture.png

- <b>Environment texture</b> - enables/disables environment texture in the current OCCT 3D view.

User can select one of 7 predefined environment texture from the list or define its texture from file by 
choosing item <b>"Custom..."</b> in a combo box.

\note Environment texture file should normally satisfy the following requirements 
in order to produce good visual result:
- The image file should have 2:1 width-to-height ratio.
- It should constitute a 360-degrees panoramic image created using a fish-eye lens. 

<hr>

\image html occ_view_light_source.png

\anchor light_source

<b>Light source</b> - allows to set parameters for light source.

It's possible to choose a type of light source between directional and positional light.

\image html doc_dir_light_source.png

<b>Directional</b> light - creates a directional light source in the viewer.
It is defined by direction coordinates, color and headlight parameter.

\image html doc_pos_light_source.png

<b>Positional</b> light - creates an isolated light source X,Y,Z in the viewer. 
It is also defined by the color and headlight parameter.

Click:

- <b>Apply and Close</b> to apply defined light source to the OCC 3D Viewer.

- <b>Default</b> to restore default values of light source.

- <b>Close</b> to return parameters of light source on initial values.

<hr>
*/