=========
Cylinders
=========

Cylinders have a smaller memory footprint and can be rendered more quickly than shells. These two features can create many advantages for developers who have models that lend themselves to cylindrical representations.

In HOOPS, cylinders are defined as two circles, known as end caps, connected to one another to form a tube. To create a cylinder in the HOOPS database, use ``Insert_Cylinder``. This function accepts two points, indicating the center points of the end caps, a radius and an options string. The options string is used to determine if either of the end caps will be rendered. The following sample code shows a cylinder with a 0.05 radius inserted into the database with options set to "none" indicating that neither end cap wil be drawn.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../demo/common/sanity/0700_docs_0017.cpp
		   :start-after: //! [insert_cylinder]
		   :end-before: //! [insert_cylinder]

Edge and face visibility affect cylinders just like they affect shells.  When edges are visible, the cylinder is rendered with two edges connecting the two circles like struts.  The edges around the end caps are considered hard edges while the struts are silhouette edges under the right viewing angles.  When markers are visible, there will be one marker at the center of each end cap.


Polycylinders
=============

Polycylinders are a sequence of connected cylinders defined by a collection of vertices and their associated radii.  Polycylinders are useful in representing a variety of graphical items. For example, they could be used to depict pipework in a factory or plant, or color-interpolated heat/air/fluid-flow streamlines in CAE post-processing applications.

.. csv-table::

	.. image:: images/02161_arrow.png, .. image:: images/02161_copperpipes.png, .. image:: images/02161_pinkhub.png

*Three different types of models that can be created using polycylinders.*

In addition to their flexibility as a geometric form, polycylinders have only a slightly larger memory footprint than cylinders and can still be rendered more quickly than shells. The following code snippet shows how to create a torus using ``Insert_PolyCylinder``: 

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../demo/common/sanity/0700_docs_0017.cpp
		   :start-after: //! [insert_torus]
		   :end-before: //! [insert_torus]
		   
.. image:: images/02161aRedTorus.png

*A torus created using the HC_Insert_PolyCylinder function.*
  
You can set the face normals on the two end caps of a polycylinder. The end cap face indices are 0 and 1. The following code sample shows you how to set the face normal on a polycylinder's end caps:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../demo/common/sanity/0700_docs_0017.cpp
		   :start-after: //! [set_normals]
		   :end-before: //! [set_normals]
		   
  
Precision Control
=================

Cylinders and polycylinders, like shells, contain LOD representations. The rendering option "tessellation" specifies the number of facets used to represent the cylinder for each LOD level.  When you specify zero for the tessellation value, cylinders will rendered as a single edge between the two end points. This edge will have visibility and attributes of edges (not lines or faces as seen in ``Set_Visibility``). When a negative number is set for the facet value, nothing will be drawn at all. Default resolutions are "tessellation = (cylinder = (24,12,6,0,-1))". 
  
.. image:: images/02162aLowTessellationTorus.png

*A torus created with the tessellation set to five.*


Color and Color Interpolation
=============================

Like shells, you can set the color value for the edges and faces of a polycylinder. In addition, you can also set the color of the individual vertices.  When the rendering option "color interpolation" is enabled and color values are set on individual vertices, HOOPS will perform color interpolation between the vertices of the polycylinder. This feature of polycylinders is particularly useful because polylines do not have color interpolation.  So to simulate color interpolation for polylines, create a polycylinder with a radius equal to 0 and then, set the color values on your individual vertices.  The following sample code shows how this can be achieved:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../demo/common/sanity/0700_docs_0017.cpp
		   :start-after: //! [polycylinder_colors]
		   :end-before: //! [polycylinder_colors]
		   
.. image:: images/02163aPolycylColorInterp.png

*Color interpolation being performed on a polycylinder with radius equal to zero.*

Note that if you want to set the color on an end cap, you can set it indirectly by setting the color of the vertex associated with that end cap.  Color values can be set via ``Set_Color_By_Index``, ``MSet_Vertex_Colors_By_Value`` and its variants.

Another feature of note is the 'invert polycylinders' suboption found in "geometry options" via ``Set_Rendering_Options``.  When this option is enabled, you flip the order upon which the color and/or radii are applied to points in a polycylinder quickly and easily.


Limitations
===========

Although cylinders and polycylinders are an extremely versatile and highly efficient geometry primitive, there are limitations that affect how they can be used.  The following is a list of the restrictions associated with cylinders: 

* Changes in the tessellation resolution are the only form of LOD allowed on cylinders.  Unlike with shells, it is not possible to use ``Open_LOD`` to insert arbitrary geometry or modify the contents of a LOD If such functionality is required, shells, not cylinders, are the appropriate primitive. As described above, however, the special case of 0 resolution has a non-cylinder representation. 
* Cylinders are never broken lengthwise into pieces, making it impossible to have a specular highlight in the middle of a cylinder using Gouraud shading (though it would be possible with Phong). 
* Unlike with shells, the individual faces and edges of cylinders may not be assigned local visibility, or local attributes beyond what is described in the previous section. 
* There is currently no mechanism to assign a starting point for the faceting so that the cylinder will exactly match up with other geometry, though cylinders should match up with each other.
