2. File-to-File Translation

This tutorial walks you through the ImportExport sample code one of the samples included with HOOPS Exchange. The sample demonstrates the basic workflow of reading an input file and exporting it to a new format.

As a prerequisite, ensure you have followed the previous tutorial about Set Up Your Environment. Ensure you can build and run the ImportExport sample. The sample code can be found in the ../samples/ folder of your package.

The Code

Open ImportExport.cpp in your editor. Since the sample is a complete implementation, you’re not required to add anything new to the program. To facilitate learning, we’ll examine each of the functional areas with a deep dive into what the code is doing.

At the top of the file, you’ll notice two lines of code related to including and initializing HOOPS Exchange:

#define INITIALIZE_A3D_API
#include <A3DSDKIncludes.h>

The definition of INITIALIZE_A3D_API before including the Exchange header triggers the inclusion of initialization code. This should only be present in a single compilation unit of an application, and in this sample, it’s in ImportExport.cpp.

In the `main` function’s body, you’ll find logic for handling command-line arguments.

If you run the program without specifying input and/or output files, defaults are used:

• The default input file is samples/data/catiaV5/CV5AquoBottle/Aquo Bottle.CATProduct.

• The default output file is the input file name with .prc appended.

Following the command line processing, you’ll see the following line of code:

A3DSDKHOOPSExchangeLoader sHoopsExchangeLoader(_T(HOOPS_BINARY_DIRECTORY));

This line constructs an object that is declared and implemented inline. Its role includes loading and initializing HOOPS Exchange and unlocking the product using your license key found in hoops_license.h. Additionally, its destructor is implemented to de-initialize and unload HOOPS Exchange. You can examine this class’s inline implementation.

Next, the sample connects callbacks for custom memory allocation and freeing.

CHECK_RET(A3DDllSetCallbacksMemory(CheckMalloc, CheckFree));
CHECK_RET(A3DDllSetCallbacksReport(PrintLogMessage, PrintLogWarning, PrintLogError));

While not required for using HOOPS Exchange, it can be helpful when debugging memory-related issues. After connecting the memory callbacks, the code establishes a callback for handling information, warning, and error messages from the library. Again, this isn’t mandatory for using HOOPS Exchange, but it can provide valuable information. The samples all print the messages received by the callback to stdout.

The heart of the sample is the next three lines of code:

A3DImport sImport(acSrcFileName)
A3DExport sExport(acDstFileName)
CHECK_RET(sHoopsExchangeLoader.Convert(sImport, sExport))

It declares an import object and an export object, then uses the Convert method on A3DSDKHOOPSExchangeLoader to perform the conversion. Each of these classes and methods are implemented in A3DSDKInternalConvert.hxx, allowing you to examine them more closely.

The A3DImport class serves as a container for the input filename and an options struct controlling the reader’s behavior. Internally, it initializes the options with common values.

Similarly, the A3DExport class serves as a container for the output filename and an options struct controlling the writer’s behavior. This class examines the file extension and sets an enumeration indicating the desired format.

The final step of this tutorial is the call to “Convert()”:

CHECK_RET(sHoopsExchangeLoader.Convert(sImport, sExport));

The method’s implementation first reads the input file and uses the file type determined by the A3DExport class to invoke the appropriate function for writing the desired output file format.

Playing With The Sample

In this section we will tweak the code and see the changes.

WindowsLinuxmacOSiOSAndroid

Change the command line

In Visual Studio from the Solution Tree explorer:

• Locate the sample ImportExport

• Right click on it and select Properties.

• Edit the Command Argument setting under the Debugging tab to change the input CAD file and output.

Assuming that the HOOPS Exchange API package is installed on the root of your disk C: the command argument looks like this:

"C:\HOOPS_Exchange_Publish_2023_SP1\samples\data\catiaV5\CV5_Aquo_Bottle\Bullet_Lid_Cap.CATPart" "C:\HOOPS_Exchange_Publish_2023_SP1\samples\data\catiaV5\CV5_Aquo_Bottle\Bullet_Lid_Cap.CATPart.stl"

• Run the sample ImportExport to convert a CATIA V5 part called Bullet_Lid_Cap.CATPart to STL format.

• Locate the file Bullet_Lid_Cap.CATPart.stl in your output folder.

• Open the HOOPS Demo Viewer desktop application and and drag & drop your resulting Bullet_Lid_Cap.CATPart.stl file to quickly visualize the part:

You just have learned how to specify your own input CAD file and Output format.

Change the conversions settings

In Visual Studio from the Solution Tree explorer:

• Locate the sample ImportExport

• Under the Debugging tab edit the Command Argument setting to specify the input CAD file and output.

Assuming that the HOOPS Exchange API package is installed on the root of your disk C: the command argument looks like this:

"C:\HOOPS_Exchange_Publish_2023_SP1\samples\data\pmi\PMI_Sample\CV5_Sample.CATPart" "C:\HOOPS_Exchange_Publish_2023_SP1\samples\samples\data\pmi\PMI_Sample\CV5_Sample.CATPart.prc"

• Run the sample to convert the file CV5_Sample.CATPart to PRC format.

• Locate and drag & drop the resulting CV5_Sample.CATPart.prc in HOOPS Demo Viewer to visualize the part in your output folder:

• Locate and open the A3DSDKInternalConvert.hxx file from your installation folder ../include/

You are now looking at the file A3DSDKInternalConvert.hxx where all the conversion parameters are exposed.

A3DRWParamsGeneralData m_sGeneral;                                 /*!< The general reading parameters. */
A3DRWParamsPmiData m_sPmi;                                                 /*!< The parameters for PMI reading. Used when `m_sGeneral.m_bReadPmis` is `A3D_TRUE`. */
A3DRWParamsTessellationData m_sTessellation;           /*!< The tessellation reading parameters. */
A3DRWParamsAssemblyData m_sAssembly;                           /*!< The reading parameters used to load Assembly files. */
A3DRWParamsMultiEntriesData m_sMultiEntries;           /*!< The parameters used when reading multiple models. */
A3DRWParamsSpecificLoadData m_sSpecifics;                  /*!< The parameters specific to each CAD format. */
A3DRWParamsIncrementalLoadData m_sIncremental;     /*!< The reading parameters used to load specific parts of an assembly. */
A3DRWParamsLoadData;

Import and Export parameters can be added and edited as needed. Let’s take an example:

• Locate the setting m_sLoadData.m_sGeneral.m_bReadPmis = A3D_TRUE;

• Change its value to setting m_sLoadData.m_sGeneral.m_bReadPmis = A3D_FALSE;

• Rebuild and Run the sample to convert the file CV5_Sample.CATPart to PRC format again.

• Locate and drag & drop the resulting CV5_Sample.CATPart.prc in HOOPS Demo Viewer to visualize the part.

• Compare the two resulting CV5_Sample.CATPart.prc files.

As you can see that by turning off the import parameters m_sLoadData.m_sGeneral.m_bReadPmis = A3D_TRUE; the Product Manufacturing Information are not converted.

Conclusion

The file-to-file workflow is a common starting point for evaluating the capabilities of HOOPS Exchange. Using the ImportExport sample that ships with the product, you can easily convert files from one format to another.

By completing this tutorial, you now have the knowledge of how to use HOOPS Exchange in this basic use case. Furthermore, by examining the implementation of the helper classes involved, you’ll have gained some insight into the use of the API itself.

Now that you played along with our ImportExport sample, you are ready to move forward and play with our Traverse CAD Structure sample.