#######################################
HOOPS Exchange for Parasolid Developers
#######################################

********
Overview
********

HOOPS Exchange includes a connector to Parasolid which allows Parasolid developers to easily import CAD data into an active Parasolid session.
If the source data is Parasolid-based (NX, Solid Edge, SolidWorks, or JT files carrying a Parasolid B-rep), then the data is imported untouched.
This means you can assume the quality of the data will be exactly the same as what you would get within SolidWorks, Solid Edge, or NX.

.. note::

   For JT files, this is decided per body, not per file: a single JT file can mix Parasolid, JT, and ULP B-rep bodies (see :ref:`jt_rd_brep`).
   Only the bodies stored as Parasolid B-rep are treated as Parasolid-based data.

If the data originates from a non-Parasolid system (such as CATIA, Creo, or STEP, etc...), then our connector leverages Parasolid and optionally PS/BodyShop to ensure that the models are imported with the highest quality.
Connections between the Parasolid model and additional data such as PMI, assembly structure, and meta-data are maintained in a mapping table.

The APIs for using the Parasolid connector are `:func:A3DAsmModelFileTranslateToPkParts` and `:struct:A3DRepresentationItemTranslateToPkParts`.
In both cases, everything which can be exported to the Parasolid session is transferred, and Exchange provides a map (`:struct:A3DMiscPKMapper`) to keep the bi-directional link between the PRC data and the resulting `PK_ENTITY`.
For example:

* `A3DAsmProductOccurrence <-> PK_ASSEMBLY`
* `A3DRiRepresentationItem <-> PK_BODY`
* `A3DTopoFace <-> PK_FACE`

This works even if faces or edges are sewn or merged in the bridge.
In a "full integration", parts are transferred one by one, and the whole assembly structure is transferred into your scene graph, allowing you to manage visibilities, views, and additional meta-data.

The following picture is a screenshot of a Parasolid-based application showing an imported CATIAV5 model with the semantic PMI maintained

.. image:: /_assets/images/ParasolidDemoViewer.png

.. _parasolid_loading_translation:

***************************
From Loading to Translation
***************************

Getting a model into a Parasolid session takes two steps: loading the model file, which converts it to PRC, then translating the PRC data to Parasolid.
Each step does different work, which is why loading is much faster than translation.

Loading
=======

Loading converts the whole model to PRC, B-rep included, without approximating the geometry (see :doc:`/guide/geometry/getting_brep`).
It does not run modeling operations.
Sewing, healing, accurate edge computation, simplification, and merging are only performed during translation.
Some readers still provide repair options of their own, such as healing face orientations when loading STEP files.

Parasolid Entities Kept as Is
=============================

Parasolid, NX, SolidWorks and Solid Edge files store their B-rep as Parasolid data, and so can some bodies of a JT file.
When :c:member:`A3DRWParamsParasolidData.m_bKeepParsedEntities` is set to ``A3D_TRUE``, HOOPS Exchange keeps the original Parasolid entities of this data alongside the PRC B-rep, which is still built in full.
Translating the model then reuses these entities without modification, instead of rebuilding them from PRC.

As a result, some functions cannot be used on a model loaded this way, such as :c:func:`A3DAsmModelFileSew` and :c:func:`A3DSimplifyModelFileWithAnalytics`.
See :doc:`/guide/parasolid/developers-getting-started` for the full list.

Translation
===========

:c:func:`A3DAsmModelFileTranslateToPkParts` and :c:func:`A3DRepresentationItemTranslateToPkParts` translate PRC data into the Parasolid session, and are where the modeling work happens.
Each operation is controlled by a member of :c:struct:`A3DRWParamsTranslateToPkPartsData`, described in `Loading Options`_.
Two kinds of operations can change the model:

* **Simplification** converts curves and surfaces to analytic forms within a tolerance.
  This is where geometry can be approximated.
* **Sewing and merging** can merge close edges and remove very small ones.
  As a result, PRC and Parasolid entities do not always match one to one (see `Mapping`_).

Healing, accurate edge computation, simplification and merging accept an ``ONLY_IF_NOT_PARASOLID`` value, such as ``kA3D_HEALING_ONLY_IF_NOT_PARASOLID``.
With this value, the operation runs on all data except the Parasolid entities kept with :c:member:`A3DRWParamsParasolidData.m_bKeepParsedEntities`:

.. code-block:: c

   A3DRWParamsLoadData sLoadParams = A3D_MAKE_DATA(A3DRWParamsLoadData);
   sLoadParams.m_sSpecifics.m_sParasolid.m_bKeepParsedEntities = A3D_TRUE; // Keep the Parasolid entities
   // ... load the model file

   A3DRWParamsTranslateToPkPartsData sTranslateParams = A3D_MAKE_DATA(A3DRWParamsTranslateToPkPartsData);
   sTranslateParams.m_eHealing = kA3D_HEALING_ONLY_IF_NOT_PARASOLID; // Heal the other data only

Healing is best activated only when needed.
It can also be run later, on specific parts only, with :c:func:`A3DHealPkParts`.
See :doc:`/guide/parasolid/developers-getting-started` for more performance recommendations.

Partial Loading and Translation
===============================

Incremental load reads the assembly structure first, then the geometry of selected parts only (see the Incremental Load section in :doc:`/guide/basic_operations/load_model`).

Likewise, :c:func:`A3DRepresentationItemTranslateToPkParts` translates a single representation item, and :c:func:`A3DRepresentationItemsTranslateToPkPartsMultiProcess` translates a set of them across several processes.

***************
Loading Options
***************

The loading options in :struct:`A3DRWParamsTranslateToPkPartsData` can have a significant impact on performance and model quality, so each is reviewed below.

+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| Field                       | Type                                     | Description                                                                                                               |
+=============================+==========================================+===========================================================================================================================+
| `m_eHealing`                | `A3DETranslateToPkPartsHealing`          | Enum to control the healing. Healing controls adjustment of topological                                                   |
|                             |                                          | tolerances, removing geometric discontinuities, eliminating slicer                                                        |
|                             |                                          | faces, etc. This option can be enabled, disabled, or enabled only for                                                     |
|                             |                                          | non-Parasolid files.                                                                                                      |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| `m_eComputeAccurateEdges`   | `A3DETranslateToPkPartsAccurate`         | Enum to control accurate edge computation. This option can be enabled, disabled, or enabled only for non-Parasolid files. |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| `m_bDisjoinIfFaceFaceError` | `A3DBool`                                | If TRUE, bodies with face-face error will be                                                                              |
|                             |                                          | disjoined. This means that when errors are detected, the problematic                                                      |
|                             |                                          | faces are isolated from the rest of the model. The faces are considered                                                   |
|                             |                                          | disjoined only in the case of                                                                                             |
|                             |                                          | PK_FACE_state_bad_face_face_c errors: self-intersecting bodies.                                                           |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| `m_bSew`                    | `A3DBool`                                | Controls whether sewing will be enabled.                                                                                  |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| `m_dSewingTolerance`        | `A3DDouble`                              | Tolerance for sewing algorithm, in meters (Parasolid's native unit).                                                      |
|                             |                                          | See :ref:`parasolid_sew_tolerance`.                                                                                       |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| `m_eSimplifyGeometry`       | `A3DETranslateToPkPartsSimplifyGeometry` | Simplifies geometry and topology by converting curve                                                                      |
|                             |                                          | data to corresponding analytic forms (for example, cones, planes, or                                                      |
|                             |                                          | spheres) wherever possible. This option can be enabled, disabled, or                                                      |
|                             |                                          | enabled only for non-Parasolid files.                                                                                     |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| `m_eMergeEntities`          | `A3DETranslateToPkPartsMergeEntities`    | Removes redundant edges and surfaces for a smaller                                                                        |
|                             |                                          | memory footprint and improved performance. This option can be enabled,                                                    |
|                             |                                          | disabled, or enabled only for non-Parasolid files.                                                                        |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| `m_pcPSBodyShopPath`        | `A3DUTF8Char*`                           | Path to PSBodyshop DLL. Exchange will use PSBodyshop                                                                      |
|                             |                                          | to improve the export quality for non-Parasolid models. That is more                                                      |
|                             |                                          | entities are approximated as analytics and more entities are merged.                                                      |
|                             |                                          | This is an optional field: you can consider setting it only if you want                                                   |
|                             |                                          | to provide your own library.                                                                                              |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| `m_pMapper`                 | `A3DMiscMapper**`                        | Mapper used to retrieve the link between PRC and Parasolid entities. See section below.                                   |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| `m_bUseColour2Attribute`    | `A3DBool`                                | Use SDL/TYSA_COLOUR_2 Parasolid attribute                                                                                 |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| `m_bUseUNameAttribute`      | `A3DBool`                                | Use SDL/TYSA_UNAME Parasolid attribute.                                                                                   |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| `m_bUseLayerAttribute`      | `A3DBool`                                | Use SDL/TYSA_LAYER Parasolid attribute.                                                                                   |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| `m_uiNbProc`                | `A3DBool`                                | Only for A3DAsmModelFileTranslateToPkParts: Use this to decide the number of process used. If 0 1 or                      |
|                             |                                          | A3DAsmModelFileTranslateToPkParts will run in the current process only.                                                   |
|                             |                                          | For any other value the operation will perform using the requested                                                        |
|                             |                                          | number of process. This field may be automatically clamped to a lower                                                     |
|                             |                                          | value if not supported by the system.                                                                                     |
+-----------------------------+------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+

*************
Prerequisites
*************

HOOPS Exchange and Parasolid are run independently.
Thus, in order to use any Parasolid-related Exchange function, you will need a valid Parasolid session.
HOOPS Exchange will not initialize a Parasolid session automatically - session management is up to you.
Additionally, please consider the following:

* The minimum version of Parasolid is *24.1* on Windows and *27.0* on Linux.
  For Parasolid convergent modeling (faceted data) you will need at least `28.1`.
* The execution environment must have a defined environment variable called `P_SCHEMA` which expands to the path to the Parasolid `Schema` folder.

*******
Mapping
*******

Once translated it may be useful to know which topological entities from PRC corresponds to Parasolid ones and vice versa.
Besides the matching is not always "one to one" for treatment is done during the process:

* The sewing process may merge two close edges into one according to provided sewing tolerance.
* Too small edges may be removed from the resulting topology

****************************************
Loading a Model Into a Parasolid Session
****************************************

The following code snippet demonstrates how to use the `:func:A3DAsmModelFileTranslateToPkParts` to load a model into a Parasolid session:

.. code-block:: c

   A3DRWParamsExportParasolidData sExportOptions = A3D_MAKE_DATA(A3DRWParamsExportParasolidData);

   // ... set your desired export options here

   int iNbPkParts;
   PK_PART_t* pPkParts;

   A3DAsmModelFileTranslateToPkParts(sHoopsExchangeLoader.m_psModelFile,
   &sOptions,                      // Parasolid options structure
   &pParamsTranslateToPkPartsData, // Parasolid translation structure
   &iNbPkParts,                    // [out] length of pPkParts
   &pPkParts);                     // [out] PK_PART_t entity IDs

**Important:**  The Parasolid modeler uses the meter as its default unit.
When exporting a file to a
Parasolid session, Exchange will convert the scaling in the model to meters.

Setting Parasolid Attributes in Exchange
========================================

The only attributes of topological entities that are translated to Parasolid are string attributes whose title begins with H3DX_BRIDGE_*.
These attributes will be translated into Parasolid with a name beginning with `H3DX_BRIDGE/*`.
For instance, a string attribute of title `H3DX_BRIDGE_MyAttributeName` will be translated to Parasolid with a name `H3DX_BRIDGE/MyAttributeName`.

Here's how to set Parasolid attributes in Exchange:

.. code-block:: c

   A3DMiscAttribute* pAttribute = 0;
   A3DMiscAttributeData sAttributeData = A3D_MAKE_DATA(A3DMiscAttributeData);
   sAttributeData.m_pcTitle = "Parasolid attributes."; // will create Parasolid attribute: H3DX_BRIDGE/MyAttributeName

   A3DMiscSingleAttributeData sSingleAttributeData = A3D_MAKE_DATA(A3DMiscSingleAttributeData);
   sSingleAttributeData.m_bTitleIsInt = false;
   sSingleAttributeData.m_eType = kA3DModellerAttributeTypeString;
   sSingleAttributeData.m_pcTitle = (char*) "H3DX_BRIDGE_MyAttributeName";
   sSingleAttributeData.m_pcData = (char*) "My string attribute.";

   sAttributeData.m_uiSize = 1;
   sAttributeData.m_pSingleAttributesData = &sSingleAttributeData;

   A3DMiscAttributeCreate(&sAttributeData, &pAttribute);

   sBaseData.m_uiSize = 1;
   sBaseData.m_ppAttributes = (A3DMiscAttribute**) malloc(sBaseData.m_uiSize * A3DUns32(sizeof(A3DMiscAttribute*)));
   sBaseData.m_ppAttributes = &pAttribute;

   CHECK_RET(A3DRootBaseSet(pEntity, &sBaseData));

In this example, `pEntity` is the `A3DEntity` for which you would like to define an attribute.

