================
Cutting Sections
================

A cutting section [or cutting plane], is an invisible, infinite plane that cuts away part of a scene. These cut-away views are used to show inner pieces of an assembly or expose detail that would otherwise be obscured. A cutting plane is considered geometry, thus, it is affected by any modelling matrices present of its parent segment. A scene can contain more than one cutting plane - geometry is removed if it is cut away by any cutting plane. In Visualize, a plane is defined using the coefficients of the geometric equation of a plane. The plane equation is::

	ax + by + cx + d = 0

The plane itself is all points (x, y, z) in space that satisfy this equation. The part of the scene that is cut away is all points (x, y, z) that satisfy the following inequality::

	ax + by + cz + d > 0 

When visualizing how the plane equation defines a plane in space, simply imagine the coefficients a, b, and c as components of a vector originating at the origin. The plane will be perpendicular to that vector. The coefficient d is the distance from the origin along the vector that the plane will be offset. For any plane, there is an infinite number of values for (a, b, c, d) that define it.

So, let's say you have a piece of geometry that you would like to cut. For this example, a simple sphere with center at the origin and radius 0.75 units is shown. The top portion of the sphere is cut away to make the inside visible. The following code snippet will demonstrate the effect. Note that the cut edges, if desired, also need to be colored and enabled as they are not visible by default. Thus, to insert a cutting section in Visualize, you could use the following code:

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_cutting_sections_1.cs
		   :start-after: //! [insert_cutting_section]
		   :end-before: //! [insert_cutting_section]
		   
.. image:: images/default_cutting_plane.png

*A sphere cut by a cutting plane. The scene has been rotated for clarity.*

Sometimes it is useful to be able to see the cutting plane itself. In that case, use a ``HPS::CuttingSectionKit`` to set the *visualization* parameters:

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_cutting_sections_1.cs
		   :start-after: //! [capping_plane]
		   :end-before: //! [capping_plane]
		   
.. image:: images/visible_cutting_plane.png

*The cutting plane is made visible*

Alternatively, HOOPS Visualize can draw a cutting section cap over the cut away region when the cut faces are made visible. Using the ``HPS::MaterialMappingControl``, this cap can be assigned any type of material, just like any other geometry. In this case, it is set to a solid color:

.. tabs::

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

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

*The capping geometry*

To enable multiple cutting planes in the scene, simply pass an array of planes to ``SetPlanes``:

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_cutting_sections_2.cs
		   :start-after: //! [multiple_sections]
		   :end-before: //! [multiple_sections]
		   
.. image:: images/multiple_cutting_planes.png

*Multiple cutting planes produce a complex interior view*


Setting the Cutting Section Level
---------------------------------

The cutting section *level* setting makes a big difference in what is cut away by the cutting section. The level can be set locally or globally. A local cutting plane only cuts geometry in its segment or subsegments. Global cutting planes cut all geometry in the scene graph. The cutting level is controlled using the ``HPS::CuttingSectionAttributeControl``.

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_cutting_sections_1.cs
		   :start-after: //! [level]
		   :end-before: //! [level]


Guidelines for Multiple Cutting Sections
----------------------------------------

If cutting sections are an integral part of your application, or you insert and remove them often, you may want to consider grouping your specific cutting section attributes into a ``HPS::CuttingSectionAttributeKit``. Doing so saves you the trouble of applying the same attributes over and over because the attributes are saved in the kit. The kit is then applied to a segment whenever necessary.

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_cutting_sections_1.cs
		   :start-after: //! [csak]
		   :end-before: //! [csak]
		   

.. _extracting_geometry:

Extracting Cutting Plane Geometry
=================================

HOOPS Visualize offers you the ability to extract the capping geometry created by a cutting plane. The capping faces are delivered in the form of shells to a segment you specify. Edges are delivered as polylines.

Capping geometry extraction is specified using a ``HPS::CutGeometryGatheringOptionsKit``. The kit allows you to specify the depth for which the cut geometry will be gathered, as well as the segment where the caps will be placed are the operation is complete.

The following code sample assumes the model has been loaded into a subsegment of the window key called "model". The capping geometry is extracted to the "caps" subsegment. The actual gathering is done with a ``HPS::KeyPath``. The key path must lead back to a window key.

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_cutting_sections_2.cs
		   :start-after: //! [gather]
		   :end-before: //! [gather]
		   
The result of this operation is shown below, as applied to the turbine model:

.. image:: images/turbine_source/turbine_whole.png

*The turbine model*

.. image:: images/turbine_source/turbine_cut.png

*The turbine model sectioned by a cutting plane. Notice the cut faces.*


.. image:: images/turbine_source/turbine_caps.png

*After removing the model, only the capping geometry is left.*


