##################
Layers and filters
##################

Both filters and layers are mechanisms to group entities together. They are either extracted from a CAD model during import or are created during authoring. They currently can't be created or edited via the HOOPS Web Viewer API.


Filters
=======

Filters allow you to combine entities in logical groups often for the purpose of bringing attention to particular components in order to simplify the model or express an idea. That is usually done through highlighting or showing and hiding those filtered components but it is up to you to apply any desired attributes.

.. image:: images/viewer_filter_off.png

*Model with all parts visible*

.. image:: images/viewer_filter_on.png

*Model with a filter applied, hiding a single part (housing)*

 
Retrieving filters
==================

To retrieve a list of all the filters available in a CAD model you first call the function ``getFilters()``:

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

**Console output:**

``Map(4) {0 => "Filter Housing", 1 => "Filter Screws+Carbu", 2 => "Exclude Screws+Carbu", 3 => "Include Screws+Carbu"}``

The function returns a map of in this case four filters with their ID and name. If you need the name of an individual filter you can call the function :ref:`getFilterName() <api_ref/viewing/classes/Communicator.Model:getfiltername>`.

To get a list of all filters that show or hide a given node, use :ref:`getFiltersWithNode() <api_ref/viewing/classes/Communicator.Model:getfilterswithnode>`:

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

**Console output:**

``(3) [1, 2, 3]``

In this case, node 12 is included in filters with id's 1, 2 and 3.


Filtering nodes
===============

The function :ref:`getNodesFromFiltersId() <api_ref/viewing/classes/Communicator.Model:getnodesfromfiltersid>` makes it easy to find all nodes for which a set of filters applies. The behavior differs depending on the first filter that is applied. If the first filter has the inclusive flag, all nodes except those in the filter are removed. If the first filter is exclusive, all nodes are kept, and the nodes in the filter are removed. After the first one, all filters are applied in order and nodes are added or removed depending on whether or not they are inclusive.

To make this behavior more clear, see below for a code sample that interprets the results of :ref:`getNodesFromFiltersId() <api_ref/viewing/classes/Communicator.Model:getnodesfromfiltersid>` and selects nodes in case of an inclusive filter and hides the nodes otherwise:

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

Layers
======

A layer is simply a logical group of objects. The objects are not required to be related in any way. A node  can only be linked to one layer.

.. image:: images/viewer_layer_all.png

*Full drawing is visible*

.. image:: images/viewer_layer_one.png

*Only a single layer is visible and highlighted*
 

Retrieving layers
=================

To retrieve a list of all the layers available in a CAD model you first call the function :ref:`getLayers() <api_ref/viewing/classes/Communicator.Model:getlayers>`:

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

**Console output:**

``Map(33) {41 => "0", 43 => "A215_EXT WALL PANELS", 13 => "A225_EXT WALL INNER LEAF", 11 => "A320_DOORS", 9 => "A210_EXTERNAL WALLS", ...``

The function returns a map of - in this case - 33 layers with their ID and name. If you need the name of an individual layer or its id you can call the function :ref:`getLayerName() <api_ref/viewing/classes/Communicator.Model:getlayername>`.

To find out which layer a specific node belongs to call the function :ref:`getNodeLayerId() <api_ref/viewing/classes/Communicator.Model:getnodelayerid>`:

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

**Console output:**

``43``

In the case above the node with id 6842 belongs to layer 43. As mentioned before a node can only belong to a single layer.


Retrieving nodes per layer
==========================

The function :ref:`getNodesFromLayer() <api_ref/viewing/classes/Communicator.Model:getnodesfromlayer>` retrieves all nodes belonging to a given layer:

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

**Console output:**

``(2) [6842, 6844]``

In this case layer 43 (A215_EXT WALL PANELS) is associated with 2 nodes with id 6842 and 6844. It is up to you to apply attributes (e.g., highlighting, isolating) to those nodes as you see fit.
