########################################################
HOOPS Exchange for Parasolid Developers: Getting Started
########################################################

*******************************
How to Benchmark the Technology
*******************************

There are two ways to benchmark HOOPS Exchange and its Parasolid translators.
The simplest way is to use the HOOPS Parasolid Demo Viewer, while the TranslateToPkParts method allows for benchmarking programmatically.

HOOPS Parasolid Demo Viewer (HPDV)
==================================

HOOPS Parasolid Demo Viewer is a Windows application that highlights the integration of Parasolid with HOOPS Exchange and HOOPS Visualize.
Users can control the import settings to mimic what they would want in their application, making the HPDV an excellent tool for evaluating the quality and performance of our Parasolid integration.

In this application, the CAD model and its tessellation are queried through the Parasolid API.
The HPDV also allows you to export models to the XT format so that you can bring the data into your application for further analysis.
The HPDV can be downloaded from the `Developer Zone <https://developer.techsoft3d.com/hoops/demos/>`__.

TranslateToPkParts
==================

To benchmark the Exchange/Parasolid integration programmatically or in a batch mode, the TranslateToPkParts sample is a good starting point; this program is available in the HOOPS Exchange package in the _samples_ directory.
Please note, Parasolid must be installed to use this sample, and the `PARASOLID_INSTALL_DIR` and `P_SCHEMA` environment variables must be set.
(More information can be found in the TranslateToPkParts.cpp file.)

**********
Parameters
**********

B-Rep Quality
=============

There are several options available for optimizing the quality of your model  when converting CAD data to Parasolid with HOOPS Exchange.

Number of Solids
----------------

To maximize the number of solids generated, sewing functionality needs to be activated.
This option is particularly important when reading IGS files.

To activate this setting in the TranslateToPkParts sample, use the following command-line arguments:

.. code-block:: c

   TranslateToPkParts.exe <InputCAD_path> <OutputParasolid_path> -sew 1 -sewexchange 1 -sewingtolerance 0.1

To use this setting in the HOOPS Parasolid Demo Viewer, select "Show Import Options" in the Open dialog, which will bring up the Import Options window.
Set the "Sew Sheet Bodies" option to On and the Sewing Tolerance to 0.001:

.. image:: /_assets/images/HPDV_ImportOptions_1.png

Healing
-------

Advanced healing algorithms can be activated to improve and adapt the geometry and topology with Parasolid constraints and tolerances.
This option typically reduces the number of PK_BODY_check issues by adjusting tolerances and removing discontinuities and self-intersection.
If you would like to reduce the number of PK_BODY_check issues, our recommendation is to activate healing for only non-Parasolid-based formats.

In the TranslateToPkParts sample, you can activate this setting using the following command-line argument:

.. code-block:: c

   TranslateToPkParts.exe <InputCAD_path> <OutputParasolid_path> -healing 2

To use this setting in the HOOPS Parasolid Demo Viewer, select "Show Import Options" in the Open dialog, which will bring up the Import Options window.
In the "Healing" drop-down, select "Only non-Parasolid formats":

.. image:: /_assets/images/HPDV_ImportOptions_2.png

For Step files, there is a specific option available to fix the orientation of topological entities:

In the TranslateToPkParts sample, set the `m_bHealOrientations` option to true:

.. code-block:: c

   sImport.m_sLoadData.m_sSpecifics.m_sStep.m_bHealOrientations=true;

In the Import Options dialog of the HOOPS Parasolid Demo Viewer, click on the STEP tab and check "Heal Orientations":

.. image:: /_assets/images/HPDV_ImportOptions_3.png

.. note::

   HOOPS Exchange includes a connector to Parasolid that allows Parasolid developers to easily import CAD data into an active
   Parasolid session. If the source data is Parasolid-based (NX, Solid Edge, or SolidWorks), then the data is imported without modification.

To ensure that Parasolid data isn't modified, the following option needs to be activated:

.. code-block:: c

   sImport.m_sLoadData.m_sSpecifics.m_sParasolid.m_bKeepParsedEntities=true;

This option is used by default in HOOPS Parasolid Demo Viewer and TranslateToPkParts.

.. warning:: The following functions cannot be used when the model was imported with :c:member:`A3DRWParamsParasolidData.m_bKeepParsedEntities` is set to ``A3D_TRUE``:

   * :c:func:`A3DAdaptAndReplaceAllBrepInModelFileAdvanced`
   * :c:func:`A3DAsmModelFileSew`
   * :c:func:`A3DComputeModelFilePhysicalProperties`
   * :c:func:`A3DComputeOrthoHLROnModelFile2`
   * :c:func:`A3DComputeOrthoHLROnModelFile3`
   * :c:func:`A3DComputeOrthoHLROnModelFile`
   * :c:func:`A3DComputeOrthoHLROnRepresentationItems`
   * :c:func:`A3DComputePhysicalProperties`
   * :c:func:`A3DComputePlanarSectionOnModelFile`
   * :c:func:`A3DComputePlanarSectionOnRepresentationItem`
   * :c:func:`A3DComputePolyBrepPhysicalProperties`
   * :c:func:`A3DCopyAndAdaptBrepModelAdvanced`
   * :c:func:`A3DCopyAndAdaptBrepModel`
   * :c:func:`A3DCutWithMultiPlanarSectionOnModelFile`
   * :c:func:`A3DCutWithMultiPlanarSectionOnRepresentationItems`
   * :c:func:`A3DProjectPointCloud`
   * :c:func:`A3DSewBrep`
   * :c:func:`A3DSimplifyModelFileCurveAndSurfaceAsAnalytic`
   * :c:func:`A3DSimplifyModelFileWithAnalytics`

.. rubric:: Other Options

Many other options are available to adapt the B-rep to specific criteria. These options include:

* The ability to simplify geometry and topology by converting curve data to corresponding analytic forms (e.g., cones, planes, or spheres) wherever possible. See the \ref m_eSimplifyGeometry in the \ref A3DRWParamsTranslateToPkPartsData structure.
* The ability to remove redundant edges and surfaces for improved performance and a smaller memory footprint. (See the \ref m_eMergeEntities option.)
* The ability to replace tolerant edges with accurate edges. (See the \ref m_eComputeAccurateEdges option.)
* The ability to use PSBodyshop, resulting in more entities approximated to analytics and more merged entities. (See the m_pcPSBodyShopPath option.)

Parameters to Improve Performance
=================================

Multi-Process Option
--------------------

HOOPS Exchange can use multi-process translation to increase performance when exporting assemblies into Parasolid.
This option is available in the HOOPS Parasolid Demo Viewer and also for developers integrating HOOPS Exchange directly.

For the HPDV, in the Import Options dialog select the number of processes to use in the translation:

.. image:: /_assets/images/HPDV_ImportOptions_4.png

This option significantly improves performance, particularly for healing operations when translating CAD assemblies into Parasolid.
However, it's better not to use the multi-process option on parts or when translating Parasolid-based CAD files (SolidWorks, NX, Solid Edge) if healing is not activated for the original Parasolid-based CAD files.

on-Demand Healing Operations
----------------------------

Performance can also be improved by initiating healing operations on-demand instead of globally.
For instance, it's possible to call a healing operation after importing and displaying CAD files in your application, just before calling a specific operation or function.

For instance, when working with assemblies, a user can call healing functionality on the parts that may be impacted by a specific operation – just before imprinting, for instance.
A healing operation can be done in the application's Parasolid session, eliminating the need to transfer data back and forth between HOOPS Exchange and your application.

See the function :struct:`A3DHealPkParts` function for more details.

Use the Latest HOOPS Exchange Release
-------------------------------------

Performance for healing operations is continually improved from one release to the next.
For best results, use the latest available package.

HOOPS Exchange can be integrated in two ways:

HOOPS Exchange can convert a CAD model into Parasolid directly in your Parasolid session with a few lines of code, as is demonstrated in the TranslateToPkParts sample.

For more advance usage, HOOPS Exchange offers the ability to just convert B-rep solids in your Parasolid session using :func:`A3DRepresentationItemsTranslateToPkPartsMultiProcess`.
All additional information, such as the assembly tree, PMI, configuration, layers, and filters can be retrieved directly from the Exchange API.

.. image:: /_assets/images/Parasolid_Exchange_Diagram.png

HOOPS Exchange then provides some additional information to link CAD information (e.g., PMI, assemblies, nodes) to the Parasolid data (e.g., B-rep, faces, edges) that has been exported to your Parasolid session.HOOPS Parasolid Demo Viewer is itself based on a direct integration.

.. image:: /_assets/images/HPDV_Screenshot.png

***********************
General Recommendations
***********************

Each parameter we provide is useful for adapting our Parasolid translator to your application's requirements.
In case you're not 100% sure about which parameters to use, we recommend the following default settings and best practices.

Use a Direct Integration
========================

By using a direct integration, you'll have more flexibility in your application to import what you need.
You'll also be able to optimize performance by using multi-process and healing operations on demand.
See :func:`A3DRepresentationItemsTranslateToPkPartsMultiProcess` for more details.

Activate the STEP Healing Operation (for STEP Models)
=====================================================

In our experience, we have encountered many Step files that were created with incorrect orientation.
For that reason, we recommend using the Step Healing Orientation setting by default.

.. code-block:: c

   sImport.m_sLoadData.m_sSpecifics.m_sStep.m_bHealOrientations=true;

Keep Parasolid Entities as-Is
=============================

.. code-block:: c

   sImport.m_sLoadData.m_sSpecifics.m_sParasolid.m_bKeepParsedEntities=true;

Use the HOOPS Exchange Sew With a 0.1mm Tolerance
=================================================

The 0.1 tolerance can be considered as the maximum value we'll use to close gaps between faces.
Behind the scenes, we'll use the smallest tolerance we can to sew faces together.
For instance, if the gap between 2 faces is a micron, we'll sew these faces together with a micron.

.. code-block:: c

   A3DAsmModelFileSew (&sHoopsExchangeLoader.m_psModelFile, 0.1);

Use the Parasolid Sew With a 1e-4 Meter Tolerance
=================================================

Parasolid default unit is the meter, so the Parasolid tolerance needs to be set to 1e-4.
This corresponds with the 1e-1 mm Exchange sewing tolerance.

.. code-block:: c

   sExport.m_sTranslateToPkPartsData.m_dSewingTolerance  = 1e-4;

Don't Activate Healing Except if Needed, and on-Demand if Possible
==================================================================

.. code-block:: c

   // Healing deactivated:
   sExport.m_sTranslateToPkPartsData.m_eHealing = kA3D_HEALING_NO;

   // Healing activated:
   sExport.m_sTranslateToPkPartsData.m_eHealing = kA3D_HEALING_ONLY_IF_NOT_PARASOLID;

   // On-demand healing:
   A3DHealPkParts();

Other Options
=============

By default, other options should be turned off unless specific needs arise.

Convergent Modeling combines solid B-rep operations and faceted geometry operations in a single modeling component.
It is available with Parasolid version 28.1 or higher.

To activate Convergent Modeling, call the function `PK_SESSION_set_facet_geometry`.
Note that the `hepb` Exchange library will activate on the fly when necessary.

Just like solid B-rep, faceted solids are of type `PK_BODY`, so there's no need to treat them independently.
However, certain functions may not work on faceted geometry.
These functions are listed in the Parasolid documentation under *Volume 12.Facet Modeling* (Parasolid documentation can be downloaded as a separate package from the `Developer Zone <https://developer.techsoft3d.com/toolkits/siemens-parasolid/downloads/>`__).

Note that if you want to import a Parasolid file with tessellated data using the Parasolid API, you will have to use two
functions instead of one: `PK_PART_receive` and `PK_PART_receive_meshes`.

