<?xml version="1.0" encoding="utf-8"?>
<section version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"
         xml:id="usage.viewports" xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Viewports</title>

  <para>
    OVITO's main window contains four viewports, which are laid out in a 2 by 2
    grid. Each viewport shows the same three-dimensional scene from a different angle.
    The caption in the upper left corner and an axis tripod in the lower left corner of every viewport 
    indicate the current viewing direction, i.e. the orientation of the virtual camera.
  </para> 

  <simplesect xml:id="usage.viewports.navigation">
  <title>Navigation</title>     
  <para>
    <figure>
      <title>The colored cross marks the center of rotation of the camera. Double-click on a particle to reposition the marker.</title>
      <screenshot><mediaobject><imageobject>
            <imagedata fileref="images/viewport_control_toolbar/viewport_screenshot.png" format="png" />
       </imageobject></mediaobject></screenshot>
    </figure> 
    Use the mouse to navigate within a viewport and to move the virtual camera around:
    <itemizedlist>
    <listitem><para>
      Left-click and drag to rotate the camera around the current orbit center, which, by default, is the center of the simulation box.
    </para></listitem>
    <listitem><para>
      Right-click and drag to move the camera parallel to the current projection plane. You can also use the middle mouse button for this.
    </para></listitem>
    <listitem><para>
      Use the mouse wheel to zoom in and out.
    </para></listitem>
    <listitem><para>
      Double-click on a particle or other object to set a new orbit center. From now on the camera will rotate around that position, which is marked by a colored cross.
    </para></listitem>
    <listitem><para>
      Double-click in an empty region to reset the orbit center to the center of the active object (typically the simulation box).
    </para></listitem>
    </itemizedlist>

     By default, the z-axis is considered the "up" (=vertical) direction, and OVITO ensures that it always points upward when you rotate or move the camera. 
     Depending on your simulation setup this might not be the best choice. In such a case you can define the x or y axis to be the vertical axis in the 
     application settings dialog.
  </para>
  </simplesect>
  
  <simplesect xml:id="usage.viewports.toolbar">
  <title>Viewport toolbar</title>     
   <para>
     <figure>
      <title>The viewport toolbar.</title>
      <screenshot><mediaobject><imageobject>
            <imagedata fileref="images/viewport_control_toolbar/viewport_toolbar.png" format="png" />
       </imageobject></mediaobject></screenshot>
     </figure> 
     The viewport toolbar is located below the viewports and contains buttons to explicitly activate various navigation input modes.
     The <emphasis>Maximize Active Viewport</emphasis> button enlarges the current viewport such that it fills the entire main window. 
     Pressing the button a second time restores the original 2x2 viewport layout. The active viewport is marked by a yellow border.
   </para>
   <para>
     The <emphasis>Zoom Scene Extents</emphasis> button adjusts the zoom level and repositions the viewport camera
     such that the complete scene becomes fully visible.
   </para>
  </simplesect>

  <simplesect xml:id="usage.viewports.menu">
  <title>Viewport menu</title>
   <para>
     Each of OVITO's viewports has a caption in its upper left corner, e.g. <emphasis>Perspective</emphasis>, <emphasis>Top</emphasis>, etc.
     Clicking on the caption opens the viewport context menu as shown in the screenshot. 
     The menu allows you to switch between the standard view types.
   </para>
   <para>
     <figure>
      <title>The viewport menu.</title>
      <screenshot><mediaobject><imageobject>
            <imagedata fileref="images/viewport_control_toolbar/viewport_menu_screenshot.png" format="png" scale="50" />
       </imageobject></mediaobject></screenshot>
     </figure> 
     <menuchoice><guimenuitem>Adjust View</guimenuitem></menuchoice> opens a <link linkend="viewports.adjust_view_dialog">dialog box</link> that lets you enter the view position and orientation 
     of the virtual camera numerically.
   </para>
   <para>
     The <menuchoice><guimenuitem>Create Camera</guimenuitem></menuchoice> function creates a camera object in the three-dimensional
     scene. The camera is linked to the viewport, and moving the camera object will automatically update the viewport's 
     view accordingly. It is even possible to <link linkend="usage.animation.camera">animate the camera object</link> to create movies with
     a moving camera. Creating a camera object is also useful to fix the current viewport view and protect it against
     inadvertent or automatic changes, e.g. the automatic adjustment that is performed by OVITO when loading a new simulation dataset.
   </para>
   <para>
     The <menuchoice><guimenuitem>Preview Mode</guimenuitem></menuchoice> option activates a frame, which
     indicates the area that will be visible in the final output picture. The aspect ratio of the render frame can be 
     adjusted in the <link linkend="core.render_settings">Render settings</link> panel by changing the width and height
     of the output image or movie. 
     When the <menuchoice><guimenuitem>Preview Mode</guimenuitem></menuchoice>
     is active for a viewport, everything (including the background and <link linkend="viewport_overlays">overlays</link>) will 
     be rendered as in the final output image.
   </para>
  </simplesect>     

</section>
