===================
Color Interpolation
===================

HOOPS Visualize Desktop supports the concept of color interpolation which can help convey information such as stress, pressure, airflow, altitude, etc...  Color interpolation is supported on  faces, vertices and edges for shells/meshes/cylinders, and may be smooth (normal color interpolation) or banded (color index interpolation). The ``HPS::ColorInterpolationControl`` is used to enable or disable color interpolation. 

Normal color interpolation is achieved by:

* Using one of the ``SetVertexRGB[variant]`` methods supported by the ``HPS::ShellKey``, ``HPS::MeshKey``, and ``HPS::CylinderKey`` classes, in order to set a color on vertices
* Calling ``HPS::ColorInterpolationControl::SetFaceColor`` to instruct HOOPS Visualize Desktop to interpolate the vertex colors across faces. 

The following code sample shows how to set colors on vertices to get a color interpolation effect:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_color_interpolation.cpp
		   :start-after: //! [smooth]
		   :end-before: //! [smooth]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_color_interpolation.cs
		   :start-after: //! [smooth]
		   :end-before: //! [smooth]
		   
.. image:: images/color_interpolation.png

*This code snippet would produce this type of interpolation*


.. _color_index_interpolation:

Color Index Interpolation
=========================

When color interpolation is used, individual colors typically have a specific value or range of values associated with them. For instance, if you want to show a topographical map with different colors representing different altitude, you would create a color map. In the rendering of the topographical map, you want to show color banding that corresponds to the color map. 

Color Index  interpolation is achieved by:

* Using one of the  SetVertexIndexColor[variant] methods supported by the ``HPS::ShellKey``, ``HPS::MeshKey``, and ``HPS::CylinderKey`` classes, in order to set colormap index colors on vertices
* Calling ``HPS::ColorInterpolationControl::SetFaceIndex`` to instruct HOOPS Visualize Desktop to interpolate across the colors in the colormap.

The following sample code and images demonstrate the effect of the various color interpolation settings. See our :ref:`color interpolation sample <guides/sample_code:interpolation>` for additional details.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_color_interpolation.cpp
		   :start-after: //! [enabling_ci]
		   :end-before: //! [enabling_ci]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_color_interpolation.cs
		   :start-after: //! [enabling_ci]
		   :end-before: //! [enabling_ci]
		   
.. image:: images/jello-mold-1.png

*A shell rendered with color interpolation*

.. image:: images/jello-mold-2.png

*A shell rendered with color index interpolation*

.. image:: images/jello-mold-3.png

*A shell rendered with both color interpolation and color index interpolation*


.. _contour_lines:

Contour Lines
=============

Contour lines are a special type of line which can delineate different regions on a shell or mesh. The classic use case for contour lines is to show topographic elevation on a map. Coupling this type of line with color bands gives the viewer a sense of varying altitudes at different locations.

.. image:: images/topo_map.png

*A topographic map with contour lines*

Typically, a model like the one above is built out of a :doc:`mesh <0202_meshes>`. In HOOPS Visualize Desktop, contour lines are always associated with color bands - you can't have contour lines without some kind of color data that delineates the boundaries of the band. You must define the colors using a :ref:`material palette <prog_guide/0501_materials_introduction:Defining material palettes>`, then you (indirectly) define the contour boundaries by :ref:`setting color on individual vertices <prog_guide/0504_applying_materials:Applying materials at various levels>` in the mesh.

A topographic map is usually made out of a rectangular mesh. The z-values of each point are then altered to create the relief. You could then set the color of a particular vertex as a function of its height. After the colors are set, you can use the ``HPS::ContourLineControl`` to enable visibility as well as other attributes of the lines themselves:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_color_interpolation.cpp
		   :start-after: //! [contour_lines]
		   :end-before: //! [contour_lines]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_color_interpolation.cs
		   :start-after: //! [contour_lines]
		   :end-before: //! [contour_lines]
		   
An important consideration when setting contour line attributes is ``HPS::ContourLineControl::SetPositions``. This method allows fine control over where the lines appear as well as the interval between them. In the code example above, the interval is set to 1.0f. This means a contour line will be drawn between each color band. A value of 2.0f would mean a line would appear at every other band. The offset, 0.5f, means the contour line will be displaced by half a measure. This method works well if the lines are in a predictable pattern, but if you need to set the contour lines to appear at arbitrary positions, you should look into ``HPS::ContourLineControl::SetPositions(FloatArray)``. That variant allows you to set the contour lines at specific positions.
