2. File-to-File Translation
This tutorial walks you through the Import Export sample code, which is 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, Set Up Your Environment. Ensure you can build and run the ImportExport sample. The sample code can be found in the csharp/samples folder of your package.
2.1. The Code
Open ImportExport.cs 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.
The first thing you’ll notice is the C# assemblies needed for this sample to work. In this case, we’re using:
using TS3D.Exchange;
using TS3D.Exchange.Direct;
This sample takes a few command-line parameters: the path to the HOOPS Exchange libraries, the input filename, and the output filename.
Starting at Main
, the first significant step is parsing the command-line arguments. This is handled in ParseArgs
.
If you run the program without specifying input and/or output files, defaults are used:
- The default input file is <HOOPS_EXCHANGE_INSTALL_DIR>samples/data/catiaV5/CV5AquoBottle/Aquo Bottle.CATProduct.
- The default output file is the input file name with .prc appended.
The default values indicate we are converting the Catia V5 input file to its PRC equivalent.
Next, the sample connects callbacks for a log file and various callbacks.
// Initialize log file and HOOPS Exchange callbacks
LogFile = new StreamWriter(outputLogFile);
API.A3DDllSetCallbacksReport(MessageCallback, WarningCallback, ErrorCallback);
While not required for using HOOPS Exchange, these callbacks can provide valuable information while debugging.
The samples all print the messages received by the callback to stdout
.
Next, HOOPS Exchange is initialized.
// Initialize HOOPS Exchange library
try
{
Library.Initialize(HOOPS_LICENSE.KEY, exchangeFolder);
}
catch (Library.InitializationException e)
{
// handle error
Console.WriteLine(e.Message);
return (int) A3DStatus.A3D_ERROR;
}
Here, the class Library
gives us access to the HOOPS Exchange library object.
It needs to be initialized before using HOOPS Exchange functionality.
The license key may be set here, if you haven’t set it elsewhere in the environment.
The application also needs to know where the Exchange libraries are located. The exchangeFolder
parameter is the path to those libraries.
Following the initialization steps, the file is loaded. But before that happens, we’ll have to set up its parameters. You’ll see the following lines of code:
// initialize load parameters object
A3DRWParamsLoadData loadParams;
API.Initialize(out loadParams);
// set load parameters
loadParams.m_sGeneral.m_bReadSolids = true;
loadParams.m_sGeneral.m_bReadSurfaces = true;
loadParams.m_sGeneral.m_bReadWireframes = true;
loadParams.m_sGeneral.m_bReadPmis = true;
loadParams.m_sGeneral.m_bReadAttributes = true;
loadParams.m_sGeneral.m_bReadHiddenObjects = true;
loadParams.m_sGeneral.m_bReadConstructionAndReferences = false;
loadParams.m_sGeneral.m_bReadActiveFilter = true;
loadParams.m_sGeneral.m_eReadingMode2D3D = A3DEReadingMode2D3D.kA3DRead_3D;
loadParams.m_sGeneral.m_eReadGeomTessMode = A3DEReadGeomTessMode.kA3DReadGeomAndTess;
loadParams.m_sGeneral.m_eDefaultUnit = A3DEUnits.kA3DUnitUnknown;
loadParams.m_sTessellation.m_eTessellationLevelOfDetail = A3DETessellationLevelOfDetail.kA3DTessLODMedium;
loadParams.m_sAssembly.m_bUseRootDirectory = true;
loadParams.m_sMultiEntries.m_bLoadDefault = true;
loadParams.m_sPmi.m_bAlwaysSubstituteFont = false;
loadParams.m_sPmi.m_pcSubstitutionFont = "Myriad CAD";
The line API.Initialize(out loadParams);
initializes loader’s parameters structure.
These are parameters used by the application’s file loader and indicate which constructs should be loaded.
As different file formats support different constructs, these parameters may be different depending on the file type you’re attempting to load, and which constructs your application requires.
Note
A list of supported parameters can be found Load & Export Module.
Next, the file is loaded using the parameters initialized in the previous step:
// Load input CAD file
IntPtr modelFile;
A3DStatus loadStatus = API.A3DAsmModelFileLoadFromFile(inputFile, ref loadParams, out modelFile);
The inputFile
is from a command-line parameter, loadParams
is from the previous step, and modelFile
is the PRC filename to write after the translation.
Hint
It is always good practice to check the load status using the function’s returned value. It will be of the A3DStatus
type.
Now that our file is loaded, we will export it.
The translation is handled automatically during the write action.
We only specify the file type, which is implied by the outputFile extension.
Successful functions return A3DStatus.A3D_SUCCESS
.
// Export output CAD file
A3DStatus exportStatus = Export(modelFile, outputFile);
if (exportStatus == A3DStatus.A3D_SUCCESS)
{
Console.WriteLine("Success.");
}
else
{
Console.WriteLine("Failure.");
}
Notice the different objects, modelFile
and outputFile
.
The modelFile
is an object in memory which represents the output file logically.
The outputFile
is merely the filename as a string
.
Assuming the application is successful, the file is converted.
Now we should terminate cleanly. Since the C# API is only a set of bindings, the memory lies within the C binaries. Thus, the objects have to be explicitely released when they are not needed anymore. The following code snippets releases the model file object, then unloads the C binaries.
API.A3DAsmModelFileDelete(modelFile);
Library.Free();
2.2. Investigating the sample
In this section, we will tweak the code and see the changes.
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_INSTALL_DIR>\samples\data\catiaV5\CV5_Aquo_Bottle\Bullet_Lid_Cap.CATPart" "C:\<HOOPS_EXCHANGE_INSTALL_DIR>\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, then drag and drop your resulting Bullet_Lid_Cap.CATPart.stl file to quickly visualize the part:
![]()
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_INSTALL_DIR>\samples\data\pmi\PMI_Sample\CV5_Sample.CATPart" "C:\<HOOPS_EXCHANGE_INSTALL_DIR>\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 and 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 `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 look at an example:
- Locate the setting
m_sLoadData.m_sGeneral.m_bReadPmis = true;
- Change its value to setting
m_sLoadData.m_sGeneral.m_bReadPmis = false;
- Rebuild and run the sample to convert the file CV5_Sample.CATPart to PRC format again.
- Locate and drag and 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 = true;
the Product Manufacturing Information are not converted.
Change the command line
On Linux, open the Terminal:
- Locate the sample ImportExport from the installation folder ../samples/exchange/exchangesource/ImportExport
- Right click on the folder and select Open in Terminal
- Locate the file Bullet_Lid_Cap.CATPart from the installation folder ../samples/data/catiaV5/
- Make sure the sample is already built otherwise build it again. Command line:
make
![]()
- Run the sample ImportExport to convert a CATIA V5 part called Bullet_Lid_Cap.CATPart to STL format. Command line:
./ImportExport ../samples/data/catiaV5/Bullet_Lid_Cap.CATPart ../samples/data/catiaV5/Bullet_Lid_Cap.CATPart.stl
![]()
- Run the sample Viewer to load the resulting part called Bullet_Lid_Cap.CATPart.stl. Command line:
./Viewer ../samples/data/catiaV5/Bullet_Lid_Cap.CATPart.stl
- Bullet_Lid_Cap.CATPart.stl file will be displayed in an OpenGL Window:
![]()
You just have learned how to specify your own input CAD file and Output format.
Change the conversion settings
- Stop the execution of the sample Viewer (Ctrl+C).
- Locate the file CV5_Sample.CATPart from the installation folder ../samples/data/pmi/
- Run the sample importExport to convert the file CV5_Sample.CATPart to PRC format.
- Locate the resulting CV5_Sample.CATPart.prc file from the folder ./samples/data/pmi/
- Run the sample Viewer to load the PRC file. Command line:
./Viewer ../samples/data/pmi/CV5_Sample.CATPart.prc
![]()
- Stop the execution of the sample Viewer (Ctrl+C).
- 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 `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 look at an example:
- Locate the setting
m_sLoadData.m_sGeneral.m_bReadPmis = true;
- Change its value to setting
m_sLoadData.m_sGeneral.m_bReadPmis = false;
- Rebuild using
make clean
thenmake
the sample ImportExport
The import parameter has been changed and is now taken into account by the sample.
- Locate the file CV5_Sample.CATPart from the installation folder ../samples/data/pmi/
- Run the sample importExport to convert the file CV5_Sample.CATPart to PRC format.
- Locate the resulting CV5_Sample.CATPart.prc file from the folder ./samples/data/pmi/
- Run the sample Viewer to load the PRC file. Command line:
./Viewer ../samples/data/pmi/CV5_Sample.CATPart.prc
- 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 = true;
the Product Manufacturing Information are not converted.
Change the command line
On macOS, open the Terminal:
- Locate the sample ImportExport from the installation folder ../samples/exchange/exchangesource/ImportExport
- Right click on the folder and select Open in Terminal.
- Locate the file Bullet_Lid_Cap.CATPart from the installation folder ../samples/data/catiaV5/
- Make sure the Sample is already built otherwise build it again. Command line:
make
![]()
- Run the sample
ImportExport
to convert a CATIA V5 part called Bullet_Lid_Cap.CATPart to STL format. Command line:./ImportExport ../samples/data/catiaV5/Bullet_Lid_Cap.CATPart ../samples/data/catiaV5/Bullet_Lid_Cap.CATPart.stl
![]()
- Run the sample
Viewer
to load the resulting part called Bullet_Lid_Cap.CATPart.stl. Command line:./Viewer ../samples/data/catiaV5/Bullet_Lid_Cap.CATPart.stl
- Bullet_Lid_Cap.CATPart.stl file will be displayed in an OpenGL Windows:
![]()
You just have learned how to specify your own input CAD file and Output format.
Change the conversions settings
- Stop the execution of the sample
Viewer
(Ctrl+C).- Locate the file CV5_Sample.CATPart from the installation folder
../samples/data/pmi/
- Run the sample
importExport
to convert the file CV5_Sample.CATPart to PRC format.- Locate the resulting CV5_Sample.CATPart.prc file from the folder
./samples/data/pmi/
- Run the sample
Viewer
to load the PRC file. Command line:./Viewer ../samples/data/pmi/CV5_Sample.CATPart.prc
![]()
- Stop the execution of the sample
Viewer
(Ctrl+C).- 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 `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 look at an example:
- Locate the setting
m_sLoadData.m_sGeneral.m_bReadPmis = true;
- Change its value to setting
m_sLoadData.m_sGeneral.m_bReadPmis = false;
- Rebuild
make clean
thenmake
the sampleImportExport
The Import parameter has been changed and is now taken into account by the sample.
- Locate the file CV5_Sample.CATPart from the installation folder
../samples/data/pmi/
- Run the sample ImportExport to convert the file CV5_Sample.CATPart to PRC format.
- Locate the resulting CV5_Sample.CATPart.prc file from the folder
./samples/data/pmi/
- Run the sample Viewer to load the PRC file. Command line:
./Viewer ../samples/data/pmi/CV5_Sample.CATPart.prc
- 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 = true;
, the Product Manufacturing Information are not converted.
2.3. 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.