##############
Configurations
##############

.. program:: converter

Some CAD formats support multiple configurations of a model or assembly structure. A configuration is a specific arrangement of the model with respect to its defining hierarchy. For example, parts may be in different positions, have different geometry or be omitted entirely in different configurations.

An example might be a model of a car with the steering wheel on the left side in one configuration and on the right side in a second configuration. A configuration is separate from a :doc:`CAD view </prog_guide/mcad/cad-views>` in that it is essentially a "sub-model" within a larger model and not just a set of modified properties on various entities of an existing mode.

Sometimes CAD models containing configurations are also referred to as "multi-model" or "multi-entry" files. Only CATIAV4, SolidWorks, and IDEAS files support configurations though it is also possible to create configurations via the HOOPS Communicator authoring API.

.. image:: images/mcad_configuration_and_exclusion.png

*A model with two different configurations, the second one excluding several parts.*


Importing configurations
========================

When importing a model containing configurations into HOOPS Communicator you have the option to include either all configurations or only a specific one.  Without setting any option only the default configuration will be converted.


To import all configurations, set the :option:`--load_all_configurations=true` option.
This will import and convert all configurations of a model and make them accessible in the HOOPS Web Viewer.


Importing a specific configuration
==================================

Importing a specific configuration is generally a two-step process as you (or in effect the user interacting with the model) first needs to decide which of the configuration you are interested in.
To query the configurations within a model without actually converting all of them you can use the :option:`--output_configurations` command line option.
For example:

.. code-block:: none

	--output_configurations "c:\temp\configurations.txt"

When specifying the command line above a file containing a list of all configurations included in the model will be generated which will look something like this:

**pmi [DEF]**

**Default**

**Squelette**

**Angle**

You can then present this list to the user so they can select the configuration they want to convert. To convert a specific configuration by its name you can use the :option:`--configuration` command line option: ``--configuration "Squelette"``

If you use this option in combination with :option:`--load_all_configurations`, the specified configuration will be used as the default configuration that will be initially visible in the HOOPS Web Viewer.


Querying configurations
=======================

Each configurations is referenced via a nodeid. To query all configurations in a model you can use the function :ref:`getCadConfigurations <api_ref/viewing/classes/Communicator.Model:getcadconfigurations>` which returns a map associating the name of the configuration with its ID.

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

Result for the model used above:

#. 2: "pmi"
#. 3: "Default"
#. 4: "Squelette"
#. 5: "Angle"

To get the id of the default configuration, you can use the :ref:`getDefaultCadConfiguration <api_ref/viewing/classes/Communicator.Model:getdefaultcadconfiguration>` function. You can also query the currently active configuration with the :ref:`getActiveCadConfiguration <api_ref/viewing/classes/Communicator.Model:getactivecadconfiguration>` function.


Activating a configuration
==========================

To activate a configuration via the HOOPS Web Viewer UI simply switch to the Configuration tab in the Model Tree UI (which will only appear for models containing configurations) and activate the desired configuration.

To activate a specific configuration programmatically, simply pass its nodeId to the :ref:`activateCadConfiguration <api_ref/viewing/classes/Communicator.Model:activatecadconfiguration>` function as seen below.

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

You can also activate the default Configuration with the :ref:`activateDefaultCadConfiguration <api_ref/viewing/classes/Communicator.Model:activatedefaultcadconfiguration>` function.


Callback
========

With the :ref:`configurationActivated <api_ref/viewing/interfaces/Communicator.Callbackmap:configurationactivated>` callback, you can get notified if the HOOPS Web Viewer has switched to a different configuration (either programmatically or via the UI).


Other considerations
====================

Even if you only specify a particular configuration to be loaded or don’t specificy a configuration at all during import (in which case only the default configuration will be converted) you can still query (and see in the UI) all configurations that have not been converted. However, they will not have any geometry associated with them. As HOOPS Communicator’s intelligent streaming only sends geometry that is visible and active to the client there is often little benefit in only converting a specific communication from a viewing perspective. Converting all configurations will therefore mostly improve conversion time.

