##############
Cutting Planes
##############

Basic concepts
==============

Cutting planes are used to hide geometry on one side of a plane. Multiple cutting planes can be added to the scene to create a view that shows only part of the model. Cutting planes are contained in cutting sections.

.. image:: images/cutting_plane_basic.png

*Cutting plane example*


Cutting manager
===============

The :doc:`cutting manager </api_ref/viewing/classes/Communicator.CuttingManager>` controls the logic of creating cutting sections and cutting planes.


Cutting sections
================

There is a max of 6 :doc:`cutting sections </api_ref/viewing/classes/Communicator.CuttingSection>`. Each cutting section may contain up to 4 cutting planes. Cutting planes in separate cutting sections cut independently. If any cutting section cuts the geometry, the geometry is hidden. Within a cutting section, each cutting plane must cut the geometry to hide it. 

.. literalinclude:: /../../applications/client/docs/PG_Viewing_cutting_planes.ts
   :start-after: //! [add_cutting_plane]
   :end-before: //! [add_cutting_plane]


Capping geometry
================

When a part is cut by a plane, capping geometry can be drawn to close the shape. If the cutting plane is moved, the capping geometry will be updated. Capping geometry is optional. Visibility and color can be set separately for both faces and lines. Capping geometry settings are the same across all cutting sections.

.. literalinclude:: /../../applications/client/docs/PG_Viewing_cutting_planes.ts
   :start-after: //! [capping_geometry]
   :end-before: //! [capping_geometry]

.. image:: images/capping_geom.png


Reference geometry
==================

Stand in geometry represents the location of the cutting plane. Reference geometry is optional and can be configured for each cutting plane. The geometry is specified with 4 world space coordinates which are used to draw a transparent plane representation. The coordinates that define the reference geometry should be specified in a clockwise or counterclockwise fashion, and define a plane that contains the origin.

The cutting manager has two functions to generate coordinates for the reference geometry.

:ref:`createReferenceGeometryFromAxis <api_ref/viewing/classes/Communicator.CuttingManager:createreferencegeometryfromaxis>` uses the provided bounding box to create reference geometry coordinates at the edge of the box aligned with the provided axis.

:ref:`createReferenceGeometryFromFaceNormal <api_ref/viewing/classes/Communicator.CuttingManager:createreferencegeometryfromfacenormal>` creates reference geometry coordinates aligned with the normal, at the position, using the bounding box as guidance for the rectangle size.

.. literalinclude:: /../../applications/client/docs/PG_Viewing_cutting_planes.ts
   :start-after: //! [reference_geometry]
   :end-before: //! [reference_geometry]


Cutting plane operator
======================

The cutting plane operator interacts with cutting plane reference geometry to move the cutting planes. If a cutting plane has reference geometry visible, the cutting plane operator will move the reference geometry when it is selected with a mouse (or touch input) drag.


Callbacks related to cutting planes / sections
==============================================

:ref:`addCuttingSection <api_ref/viewing/interfaces/Communicator.CallbackMap:addcuttingsection>` and :ref:`removeCuttingSection <api_ref/viewing/interfaces/Communicator.CallbackMap:removecuttingsection>` are triggered when cutting sections are added and removed.

:ref:`cuttingPlaneDragStart <api_ref/viewing/interfaces/Communicator.CallbackMap:cuttingplanedragstart>`,  :ref:`cuttingPlaneDrag <api_ref/viewing/interfaces/Communicator.CallbackMap:cuttingplanedrag>`, and :ref:`cuttingPlaneDragEnd <api_ref/viewing/interfaces/Communicator.CallbackMap:cuttingplanedragend>` are triggered when the cutting plane operator is used to start dragging, continue dragging, and stop dragging a cutting plane. 

See :doc:`CallbackMap </api_ref/viewing/interfaces/Communicator.CallbackMap>` for details.


Cutting pane UI
===============

The communicator UI has controls for adding and removing cutting planes. The UI assumes that nothing else is changing the state of cutting planes simultaneously. If changes are made to cutting planes using the API, the icon state of the UI may become out of sync.

.. image:: images/cutting_plane_ui_controls.png

The left column has 4 icons for inserting cutting planes. The bottom 3 add a cutting plane along the X, Y, or Z axis. The top icon aligns a cutting plane to a face normal. When there is no plane selected, the icon is disabled. Selecting a face will enable the icon.

.. image:: images/cutting_plane_ui_icons.png

When a cutting plane is added, the background color for the icon will change to light blue. Clicking on an icon when it is light blue changes inverts the direction of the cutting plane and changes the background of the icon to dark blue. Clicking on the icon again will remove the cutting plane. 

.. image:: images/cutting_plane_ui_background.png

The top icon in the right column toggles the visibility of the cutting plane reference geometry. By default, the reference geometry is visible. Clicking on the icon will hide the reference geometry and turn the background color of the icon light blue.

.. image:: images/cutting_plane_ui_ref_geom.png

The middle icon in the right column toggles whether the cutting planes are in the same cutting section or different cutting sections. By default, each cutting plane will be created in a new cutting section. Clicking the icon will move them all to the same cutting section and turn the background color light blue. Clicking it again will move the cutting planes into separate sections.

.. image:: images/cutting_plane_ui_sections.png

The bottom icon on the right clears all cutting planes from all cutting sections. If there are no active cutting sections, the clear icon will be disabled.

.. image:: images/cutting_plane_ui_clear_sections.png
