###
PMI
###

.. program:: converter

PMI (Product and Manufacturing Information) refers to the annotations and attributes that compliment the geometric definitions of a CAD model. Often PMI is used in conjunction with the 3D model within the model-based definition workflow to fully describe a 3D model without the need for 2D drawings.

In HOOPS Communicator PMI markup can be associated with specific components within the model hierarchy including faces or edges within a part. Often PMI elements are associated to CAD Views, in particular, annotation-views representing a specific state of the assembly.

.. image:: images/PMI_simple_part.png

*Properties for a IFCWall element displayed in the HOOPS Web Viewer*


Importing PMI
=============

By default, converter automatically imports all PMI elements from a CAD model.
If you don’t want any PMI to be imported, you can specify :option:`--import_pmi` to *false* as a :doc:`command line option </api_ref/data_import/converter-command-line-options>`.

If you want PMI to be imported but want to exclude it only when generating a SC model, you can specify :option:`--sc_export_pmi=false`.
To exclude PMI only when generating a PNG image, you can specify :option:`--png_export_pmi=false`.


Authoring PMI
=============

You can author your own PMI either with libsc or directly in the HOOPS Web Viewer. To find out more please refer to the libs and :doc:`HOOPS Web Viewer Reference Manual </api_ref/viewing/modules/Communicator>`.


Retrieving PMI elements
=======================

You can retrieve all PMI elements in a model with the :ref:`getPmis <api_ref/viewing/classes/Communicator.Model:getpmis>` function. Please note that the name of an individual PMI element can also be retrieved with the :ref:`getNodeName <api_ref/viewing/classes/Communicator.Model:getnodename>` function.

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

Result:

7:"Linear Size.2"

9:"Simple Datum.6"

11:"Simple Datum.2"

13:"Simple Datum.1"

15:"Parallelism.1"

17:"Simple Datum.5"

19:"Simple Datum.7"

...

To retrieve all PMI Elements associated with a specific CAD view, you can use the :ref:`getCadViewPmis <api_ref/viewing/classes/Communicator.Model:getcadviewpmis>` function, which will return a list of PMI node IDs.

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

Result:

[7, 19, 21, 23, 25, 27, 31, 33, 35, 37, 39, 43, 45, 47, 49, 55, 57, 59, 61, 63, 65, 67, 69, 71, 73]


Interrogating PMI
=================

When iterating over the model tree or handling selection events you can identify if a node refers to a PMI element with the :ref:`getNodeType <api_ref/viewing/classes/Communicator.Model:getnodetype>` function. If the node is a PMI element you can then identify the type of PMI as well as its subtype.  

.. image:: images/PMI_highlighted.png

*A PMI element (highlighted) denoting the diameter of a cylinder and its associated geometry.*

.. literalinclude:: /../../applications/client/docs/PG_MCAD_PMI.ts
	   :start-after: //! [mcad_pmi_identify]
	   :end-before: //! [mcad_pmi_identify]
	
It is important to note that the meaning of the value returned by getPmiSubtype depends on the type of PMI. See below for a list of PMI types.  For a list of subtypes please refer to the :doc:`HOOPS Web Viewer Reference manual <api_ref/viewing/modules/Communicator>`

* Text 
* Dimension 
* Arrow 
* Balloon 
* CircleCenter 
* Coordinate 
* Datum 
* Fastener 
* Gdt 
* Locator 
* MeasurementPoint 
* Roughness 
* Welding 
* Table 
* Other 
* GeometricalTolerance 

Additional information about a PMI element can be retrieved with the :ref:`getNodeProperties <api_ref/viewing/classes/Communicator.Model:getnodeproperties>` function.


Setting PMI color
=================

All PMI elements have a color value associated with them which has been defined in the CAD System or during authoring. However, in some cases it might be desirable to override this default color values and instead display all PMI elements in the model with the same color. To do that you can specify the PMI color for the whole model with :ref:`setPmiColor <api_ref/viewing/classes/Communicator.Model:setpmicolor>` and then enable the PMI Color override with :ref:`SetPmiColorOverride <api_ref/viewing/classes/Communicator.Model:setpmicoloroverride>`.

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

The code above sets the PMI color to black and enables the PMI Color override resulting in every PMI in the model turning black. You can reset the PMI to their default color with ``setPmiColorOverride(false)``.

