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

Visualize 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 Visualize 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 Visualize 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 Visualize, 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.
