2. File-to-File Translation

This tutorial walks you through the ImportExport sample, 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/hello_world/ImportExport folder of your package.

2.1. The Code

Open ImportExport.cpp in your editor. The sample is organized into four functions that represent the typical HOOPS Exchange workflow:

static void initialize_exchange(void);
static A3DAsmModelFile* import_cad_file(const std::string& file_path);
static void export_cad_file(A3DAsmModelFile* model_file, const std::string& file_path);
static void terminate_exchange(void);

The main() function calls these in sequence: initialize, import, export, and terminate.

For a detailed walkthrough of the full implementation, see the ImportExport Example example documentation.

2.1.1. Initialization and Termination

Before using HOOPS Exchange, you must load the library and apply your license. The initialize_exchange() function handles this:

50    REQUIRE(loaded);
51
52    A3DStatus status = A3DLicPutUnifiedLicense(HOOPS_LICENSE);
53    REQUIRE(status == A3D_SUCCESS);
54
55    status = A3DDllInitialize(A3D_DLL_MAJORVERSION, A3D_DLL_MINORVERSION);
56    REQUIRE(status == A3D_SUCCESS);
57
58    status = A3DDllSetCallbacksReport(Sample::PrintMessage, Sample::PrintWarning, Sample::PrintError);
59    REQUIRE(status == A3D_SUCCESS);
60}
61/// End of initialize_exchange()
62

The three key calls are A3DSDKLoadLibraryA(), A3DLicPutUnifiedLicense(), and A3DDllInitialize().

When finished, terminate_exchange() cleans up:

269/// Function entry point
270/// - Parses and set arguments
271/// - calls import and export
272int main(int argc, char* argv[])
273{
274    Sample::Arguments args;

2.1.2. Importing

The import_cad_file() function configures import parameters and calls A3DAsmModelFileLoadFromFile():

The A3DRWParamsLoadData structure controls what gets loaded: geometry types, PMI, attributes, tessellation quality, and more.

2.1.3. Exporting

The export_cad_file() function writes the model to a new format. Each format has its own export function and parameters structure. Here’s the STEP export case:

141        }
142
143        case kA3DModellerJt: {
144            A3DRWParamsExportJTData export_data = A3D_MAKE_DATA(A3DRWParamsExportJTData);
145            export_data.m_eWriteGeomTessMode    = kA3DWriteGeomAndTess;

The sample determines the output format from the file extension and calls the appropriate export function.

2.1.4. The Main Flow

The main() function ties everything together:

293}
294// End of main()
295
296static A3DEModellerType get_file_format(const std::string& filepath) {
297    auto pos = filepath.find_last_of('.');
298    if (pos == std::string::npos || pos + 1 >= filepath.size()) {
299        return kA3DModellerUnknown;
300    }
301

2.1.5. Running the Sample

If you run the program without arguments, defaults are used:

  • Input: samples/data/catiaV5/CV5_Aquo_Bottle/_Aquo Bottle.CATProduct
  • Output: the input filename with .prc appended

Use --help to see all available options

2.2. Playing With 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"

../../_images/vs-test-sample.png
  • 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:
../../_images/Bullet_Lid_Cap.CATPart-win.png

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_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 & drop the resulting CV5_Sample.CATPart.prc in HOOPS Demo Viewer to visualize the part in your output folder:
../../_images/pmi-sample.png
  • Open ImportExport.cpp in Visual Studio.

In the import_cad_file() function, you’ll find all the import parameters. Let’s modify one:

  • Locate the line read_params.m_sGeneral.m_bReadPmis = A3D_TRUE;
  • Change it to read_params.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.
../../_images/pmi-sample-no-pmi.png

As you can see, by turning off the import parameter m_bReadPmis, the Product and Manufacturing Information is not loaded or 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 have learned:

For more details on import and export options, see the Simple Load and Export programming guide.

Now that you have completed the ImportExport sample, you are ready to move forward with the Traverse CAD Structure tutorial.