
.. _view-page:

#############
View Overview
#############

.. image:: ../../images/uml_view.png

The :class:`View <cee::vis::View>` provides a render area to enable visualization of the current model data and 
overlay items. 

.. image:: ../../images/overlays.png
    :align: right
    :height: 300 


Each view can observe one or more :class:`Model <cee::vis::Model>` and is linked to a :class:`Camera <cee::vis::Camera>` 
and a :class:`Viewer <cee::vis::Viewer>`. The Camera dictates how the model is viewed, while the Viewer class manages 
the interaction with the computer's windowing system.

******
Models
******

A view can accommodate one or more models for visualization. These models can be either an 
:class:`UnstructGridModel <cee::ug::UnstructGridModel>`, a :class:`MarkupModel <cee::vis::MarkupModel>`, or a 
:class:`GeometryModel <cee::geo::GeometryModel>`, each offering distinct visual configurations for your data.

See the :ref:`Model topic <model-page>` for  a description of the different model types.

******
Camera
******

The camera provides support for camera manipulation in the view. You can use a built-in input handler or create
your own customized input handler by sub classing :class:`cee::vis::CameraInputHandler`.
The camera enables both perspective (field of view and clipping planes) and parallel projection. It offers useful 
features such as support for rubberband zooming and extracting a ray from windows coordinates to be used
for, for example, picking.

Each view has its own camera object.

*************
Overlay Items 
*************

.. image:: ../../images/axiscross.png
    :align: right
    :height: 300 

The view can have any number of overlay items. These are items drawn on top of the model 
in the view, for instance a color legend for scalar results.

Available :class:`overlay item <cee::vis::OverlayItem>` types are:

-   :class:`OverlayColorLegend <cee::ug::OverlayColorLegend>`
-   :class:`OverlayAxisCross <cee::vis::OverlayAxisCross>`
-   :class:`OverlayImage <cee::vis::OverlayImage>`
-   :class:`OverlayTextBox <cee::vis::OverlayTextBox>`
-   :class:`OverlayNavigationCube <cee::vis::OverlayNavigationCube>`
-   :class:`OverlayCategoryLegend <cee::vis::OverlayCategoryLegend>`
-   :class:`OverlayColorLegendContinuousDomain <cee::vis::OverlayColorLegendContinuousDomain>`
-   :class:`OverlayPlot <cee::plt::OverlayPlot>`

Overlay items are added to a corner of your choosing using :func:`Overlay::addItem() <cee::vis::Overlay::addItem>`. 
Or, if you want full control over the overlay layout, you can add the overlay item using 
:enumerator:`LayoutDirection::ABSOLUTE_POSITION <cee::vis::OverlayItem::ABSOLUTE_POSITION>` 
and use :func:`OverlayItem::setAbsolutePosition() <cee::vis::OverlayItem::setAbsolutePosition>`.

********
Clipping
********

Clipping planes are used to clip parts of the geometry in the scene to be able to look inside.
Anything behind (on the opposite side of the plane normal) the given planes is hidden.

|ProductName| supports bounded clipping planes. This allows for cutting out parts of
the model in many different ways. Normal clipping planes will clip an object/fragment if 
it is on the wrong side of any of the active clipping planes.
By default an object/fragment will be clipped if it is behind (on the opposite side of the plane normal)
at least one of the specified planes. Setting 
:func:`setMustBeBehindAllPlanesToClip() <cee::vis::Clipping::setMustBeBehindAllPlanesToClip>` 
to true will require that an object/fragment be behind all the specified planes in order to be clipped.

**********
Background
**********

The view's :class:`background settings <cee::vis::Background>`.
The background can either be single colored or a gradient between a top and a bottom color.

****************
Image Rendering
****************

The current view can be exported to an image as a :class:`cee::Image` object. The cee::Image is a simple structure 
containing raw RGBA image data and can be easily read from any image exporter tool. |ProductName| offer the helper 
classes :class:`cee::ImageIoPng` and :class:`cee::ImageIoJpeg` to convert :class:`cee::Image` into PNG and JPEG files.

************
Bounding Box
************

The bounding box of all currently visible models can be found using :func:`boundingBox() <cee::vis::View::boundingBox>`.

.. seealso::

    -   :class:`View <cee::vis::View>`
    -   :class:`Model <cee::vis::Model>`
    -   :class:`Camera <cee::vis::Camera>`
    -   :class:`Overlay <cee::vis::Overlay>`
    -   :class:`Background <cee::vis::Background>`
    -   :class:`Clipping <cee::vis::Clipping>`
