:topic: Applying visualization filters

.. index::
   triple: DREAM3D-NX; Visualization; Visual Filters

.. _ApplyingFilters:

Applying Visualization Filters
##############################

**In this tutorial we will be covering the various types of filters that
can be applied to geometries.**

There are currently three types of filters:

-  Clip Filter
-  Slice Filter
-  Threshold Filter

A filter can be applied to any geometry or any other filter. The
following sections will detail what each of these filters do and how to
use them.

Since we are only working with one geometry at a time, for this tutorial
it can be helpful to hide all other geometries by clicking the |Showing
Geometry Icon| icon so that it looks like this |Hiding Geometry Icon|.
Once you've hidden any other geometries make sure the geometry you wish
to filter is selected in the *Visualization Pipeline Browser* before
continuing with any of the following sections.

Clip Filter
============

The **Clip Filter** is used to cut through a 3D dataset, allowing you to
inspect the interior regions. It generates a new dataset by using a
plane or box to view a region of interest (ROI) within the original geometry.

1. **Click the clip button** ( |Clip Filter Button| ).

   .. figure:: Images/50_ApplyingFilters/ClipFilter_ClipMenu.png
      :alt: Clip Button Location

      Clip Button Location

2. At this point, you should notice two things happen as a result:

   -  In the *Render Window* your geometry will be shown with a **box
      surrounding it (1)**, a **red plane showing the clipping plane’s
      location (2)** with respect to the geometry, and an **arrow
      specifying which direction from the clipping plane to keep the
      geometry (3)**, this arrow also represents the clipping plane’s
      normal direction.

      .. figure:: Images/50_ApplyingFilters/ClipFilter_RenderWindowInitial.png
         :alt: Clip Filter Render Window

         Clip Filter Render Window

   -  In the *Visualization Properties* section of the *Render
      Properties* view, you will see all the clipping filter options.

      .. figure:: Images/50_ApplyingFilters/ClipFilter_VisualizationPropertiesClipFilter.png
         :alt: Visualization Properties Clip Filter

         Visualization Properties Clip Filter

3. **Choose the clip type** by clicking the *Clip Type* drop down box at
   the top of the settings area. There are two different options within
   the *Clip Type* box:

   -  **Clip by plane**: user must define a plane where the clipping
      will take place and which side of the plane the geometry will be
      removed from
   -  **Clip by box**: user must define a box where the clipping will
      take place and whether to keep the geometry inside the box or
      outside the box

   .. figure:: Images/50_ApplyingFilters/ClipFilter_SelectClipType.png
      :alt: Select Clip Type

      Select Clip Type

4. Choose the “direction” in which the clipping will take place by
   toggling the **Inverted** checkbox located below the Clip Type option in
   the Visualization Properties section. When clipping by plane this
   will change which side of the plane the geometry will be kept after
   clipping (the direction the arrow is pointing defines the side of the
   plane in which geometry is kept). When clipping by box this will
   define whether the geometry is clipped (removed) inside the box or
   outside the box (checked = remove geometry outside the box).

   .. figure:: Images/50_ApplyingFilters/ClipFilter_SelectClipDirection.png
      :alt: SelectClipDirection

      SelectClipDirection

5. **Define the clip geometry**: This is done **via the input sections**
   in the *Visualization Properties* section or by **selecting and
   editing the clip geometry via the Render Window**. These methods are
   interchangeable/cross-compatible, thus **users can switch between
   these two methods of editing** the clip geometry at any point in this
   step.

   **NOTE: The clip geometry in the Render Window updates automatically
   as settings are changed in the Visualization Properties and
   vise-versa.**

   -  **Clipping with planes**

      -  **Defining with the Visualization Properties inputs**: **Enter
         the normal vector to the plane and the origin point** on the
         plane in the corresponding input boxes.

         .. figure:: Images/50_ApplyingFilters/ClipFilter_VisualizationPropertiesClipPlaneGeometry.png
            :alt: Define Clip Plane Geometry

            Define Clip Plane Geometry

      -  **Defining via the Render Window**: **Click and drag on the red
         plane geometry (2)** in the *Render Window* to **move the
         plane’s origin** to the appropriate spot or **click and drag
         the white arrow (3)** to change the plane’s **normal
         direction**. [(1) is an unused label in the following image]

         .. figure:: Images/50_ApplyingFilters/ClipFilter_RenderWindowInitial.png
            :alt: Clip Filter Render Window

            Clip Filter Render Window

   -  **Clipping with boxes**

      -  **Defining with the Visualization Properties inputs**: **Enter
         the translation, rotation, and scale values** in the
         corresponding input boxes.

         .. figure:: Images/50_ApplyingFilters/ClipFilter_VisualizationPropertiesClipBoxGeometry.png
            :alt: Define Clip Box Geometry

            Define Clip Box Geometry

      -  **Defining via the Render Window**: **Click and drag on the
         white box geometry (1)** in the *Render Window* to change the
         box’s **translation and rotation.** or **Click and drag and of
         the three white axes lines (2)** to change the box’s **x, y,
         and z scaling**.

         .. figure:: Images/50_ApplyingFilters/ClipFilter_RenderWindowClipBox.png
            :alt: Clip Filter Render Window

            Clip Filter Render Window

6. **Click the Apply button** to apply the clip filter to your geometry.

   .. figure:: Images/50_ApplyingFilters/ClipFilter_VisualizationPropertiesApplyClipFilter.png
      :alt: Apply Clip Filter

      Apply Clip Filter

7. Users may **show or hide the clipping geometry** at any point in this
   process by **toggling the Show Plane (or Show Box)** option just
   below the *Inverted* option.

   .. figure:: Images/50_ApplyingFilters/ClipFilter_ShowClipBox.png
      :alt: Show/Hide Clip Geometry

      Show/Hide Clip Geometry

+-----------------------------------+-----------------------------------+
| Plane Original                    | Plane Clipped                     |
+===================================+===================================+
| |Clip Plane Ready to be applied|  | |Clip Plane Applied|              |
+-----------------------------------+-----------------------------------+

+--------------------------------------+-----------------------------------+
| Box Original                         | Box Clipped                       |
+======================================+===================================+
| |Clip Plane Box Ready to be applied| | |Clip Plane Box Applied|          |
+--------------------------------------+-----------------------------------+

Slice Filter
============

The *Slice Filter* will **slice the geometry at the specified plane**.
The user will specify a plane in which **only geometry coinciding with
this plane will be shown**.

1. **Click the slice button** ( |Slice Filter Button| ).

   .. figure:: Images/50_ApplyingFilters/SliceFilter_MenuItem.png
      :alt: Slice Button Location

      Slice Button Location

2. At this point, you should notice two things happen as a result:

   -  In the *Render Window* your geometry will be shown with a **box
      surrounding it (1)**, a **red plane showing the clipping plane’s
      location (2)** with respect to the geometry, and an **arrow
      specifying the planes normal direction (3)**.

      .. figure:: Images/50_ApplyingFilters/ClipFilter_RenderWindowInitial.png
         :alt: Slice Filter Render Window

         Slice Filter Render Window

   -  In the **Visualization Properties** section of the *Render
      Properties* view, you will see all the **slicing filter options**.

      .. figure:: Images/50_ApplyingFilters/SliceFilter_VisualizationPropertiesSliceFilter.png
         :alt: Visualization Properties Slice Filter

         Visualization Properties Slice Filter

3. **Define the slice geometry**: This is done **via the input
   sections** below the *Visualization Pipeline Browser* section or by
   **selecting and editing the slice geometry via the Render Window**.
   These methods are interchangeable/cross-compatible, thus **users can
   switch between these two methods of editing** the slice geometry at
   any point in this step.

   **NOTE: The slice geometry in the Render Window updates automatically
   as settings are changed in the Visualization Properties and
   vise-versa.**

   -  **Defining with the inputs**: **Enter the normal vector to the
      plane and the origin point** of the plane in the corresponding
      input boxes.

      .. figure:: Images/50_ApplyingFilters/SliceFilter_VisualizationPropertiesSlicePlaneGeometry.png
         :alt: Define Slice Plane Geometry

         Define Slice Plane Geometry

   -  **Defining via the Render Window**: **Click and drag on the red
      plane geometry (2)** in the *Render Window* to **move the plane’s
      origin** to the appropriate spot or **click and drag the white
      arrow (3)** to change the plane’s **normal direction**. [(1) is an
      unused label in the following image]

      .. figure:: Images/50_ApplyingFilters/ClipFilter_RenderWindowInitial.png
         :alt: Slice Filter Render Window

         Slice Filter Render Window

4. **Click the Apply button** to apply the slice filter to your
   geometry.

   .. figure:: Images/50_ApplyingFilters/SliceFilter_VisualizationPropertiesApplySliceFilter.png
      :alt: Apply Slice Filter

      Apply Slice Filter

5. Users may **show or hide the slicing geometry** at any point in this
   process by **toggling the Show Plane** option at the top of the
   *Visualization Properties* section.

   .. figure:: Images/50_ApplyingFilters/SliceFilter_ShowSliceGeometry.png
      :alt: Show/Hide Slice Geometry

      Show/Hide Slice Geometry

+-----------------------------------+-----------------------------------+
| Original                          | Sliced                            |
+===================================+===================================+
| |Slice Filter Initial|            | |Slice Filter Applied|            |
+-----------------------------------+-----------------------------------+

Threshold Filter
================

The *Threshold Filter* will **remove any geometry/data that does not
fall within the specified range** for the selected data set.

1. **Select the threshold button** ( |Threshold Filter Button| ).

   .. figure:: Images/50_ApplyingFilters/ThresholdFilter_MenuItem.png
      :alt: Threshold Filter Menu Item

      Threshold Filter Menu Item

2. **Select the data set** on which to **define the threshold** via the
   *Scalars* drop down box.

   .. figure:: Images/50_ApplyingFilters/ThresholdFilter_SelectThresholdData.png
      :alt: Select Threshold DataSet

      Select Threshold DataSet

3. **Define the threshold minimum and maximum values.** You may do this
   one of two ways;

   -  **Enter the respective values** in the provided input boxes along
      the right-hand side:

      .. figure:: Images/50_ApplyingFilters/ThresholdFilter_ThresholdRangeInputBoxes.png
         :alt: Define Threshold Range Input Boxes

         Define Threshold Range Input Boxes

   -  **Move the blue slider bar handles** to the spot that represents
      the minimum/maximum values you want. The values in the input boxes
      to the right of the slider bars will update to match the value
      represented by the slider bar as you edit.

      .. figure:: Images/50_ApplyingFilters/ThresholdFilter_ThresholdRangeSliders.png
         :alt: Define Threshold Range Sliders

         Define Threshold Range Sliders

4. **Click the Apply button** at the bottom to apply the threshold to
   your geometry.

   .. figure:: Images/50_ApplyingFilters/ThresholdFilter_VisualizationPropertiesApplyThresholdFilter.png
      :alt: Apply Threshold Criteria

      Apply Threshold Criteria

+-----------------------------------+-----------------------------------+
| Original                          | Thresholded                       |
+===================================+===================================+
| |Threshold Filter Initial|        | |Threshold Filter Applied|        |
+-----------------------------------+-----------------------------------+

1. **Optional : Create a DREAM3D-NX Multi-Threshold Objects Filter** from 
   the values in this visualization threshold filter(and any anscestor or 
   descendant visualization threshold filters linked to this one if desired). 
   The new Multi-Threshold Objects filter will be appended to the end of the
   current pipeline. This feature is designed to be used with the pipeline 
   from which the array/geometry originally came. If there is no pipeline 
   currently loaded or the array(s) cannot be found in the data structure 
   of the last enabled filter, then no Multi-Threshold Objects filter will be added.

   .. figure:: Images/50_ApplyingFilters/ThresholdFilter_CreateDream3dFilterFromVXThreshold.png
      :alt: Create Multi-Threshold Objects Filter from Visualization Threshold Filter

      Create Multi-Threshold Objects Filter from Visualization Threshold Filter


.. |Showing Geometry Icon| image:: Images/50_ApplyingFilters/Icon_ShowingGeometry.png
.. |Hiding Geometry Icon| image:: Images/50_ApplyingFilters/Icon_HidingGeometry.png
   
.. |Clip Filter Button| image:: Images/50_ApplyingFilters/Icon_ClipButton.png

.. |Clip Plane Ready to be applied| image:: Images/50_ApplyingFilters/ClipFilter_RenderWindowClipPlaneOriginal.png
.. |Clip Plane Applied| image:: Images/50_ApplyingFilters/ClipFilter_RenderWindowClipPlaneApplied.png

.. |Clip Plane Box Ready to be applied| image:: Images/50_ApplyingFilters/ClipFilter_RenderWindowClipBoxOriginal.png
.. |Clip Plane Box Applied| image:: Images/50_ApplyingFilters/ClipFilter_RenderWindowClipBoxApplied.png

.. |Slice Filter Button| image:: Images/50_ApplyingFilters/Icon_SliceButton.png
.. |Slice Filter Initial| image:: Images/50_ApplyingFilters/SliceFilter_RenderWindowSliceOriginal.png
.. |Slice Filter Applied| image:: Images/50_ApplyingFilters/SliceFilter_RenderWindowSliceApplied.png

.. |Threshold Filter Button| image:: Images/50_ApplyingFilters/Icon_ThresholdButton.png

.. |Threshold Filter Initial| image:: Images/50_ApplyingFilters/ThresholdFilter_RenderWindowThresholdOriginal.png
.. |Threshold Filter Applied| image:: Images/50_ApplyingFilters/ThresholdFilter_RenderWindowThresholdApplied.png
