File-to-File Translation

This tutorial will step you through the ImportExport sample code that ships with HOOPS Exchange. This sample implements the most basic possible workflow, which is reading an input file, and writing it to a new format.

To follow along, you must have HOOPS Exchange installed, and be able to run the sample code that ships with it.

You can find that sample projects for HOOPS Exchange in the samples folder. On macOS and Linux, you are provided a Makefile for building the code. The Windows package contains a Visual Studio solution file. Whichever your platform, be sure you’re able to build and run the ImoprtExport sample code.

The Code

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

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

#define INITIALIZE_A3D_API
#include <A3DSDKIncludes.h>

The definition of INITIALIZE_A3D_API prior to including the Exchange header causes initialization code to be included. This should only appear in a single compilation unit of an application. For this sample, we only have one - ImportExport.cpp.

In the body of main, you’ll find some logic for handling command line arguments. If you execute the program without specifying an input and/or an output file, defaults are used instead. The default input file is samples/data/catiaV5/CV5AquoBottle/Aquo Bottle.CATProduct. The default output file is the same as the input file with .prc appended.

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

A3DSDKHOOPSExchangeLoader sHoopsExchangeLoader(_T(HOOPS_BINARY_DIRECTORY));

This constructs an object that is declared and implemented inline. It is responsible for loading and initializing HOOPS Exchange. It also unlocks the product using your license key found in hoops_license.h. Furthermore, its destructor is implemented to de-initialize and unload HOOPS Exchange. This class is implemented inline, so you can examine its implementation.

Next, this sample connects callbacks for custom memory allocation and free. This isn’t required to use HOOPS Exchange but can be useful when debugging memory related issues. After connecting the memory callbacks, the code connects a callback for handling information, warning, and error messages from the library. Again, this isn’t required to use HOOPS Exchange, but it can provide useful 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 export object, then uses the Convert method on A3DSDKHOOPSExchangeLoader to perform the conversion. Each of these classes and methods are implemented in A3DSDKInternalConvert.hxx, so you can examine them more closely.

The A3DImport class serves as a container for the input filename, and an options struct that controls the behavior of the reader. Internally, it initializes the options to the most common set of values.

Similarly, the A3DExport class serves as a contained for the output filename, and an options struct that controls the behavior of the writer. The class is implemented to examine the file extension and sets an enumeration indicating the desired format.

The final step of this tutorial is the call to Convert(). The implementation of this method first reads the input file, then uses the filetype determined by the A3DExport class to invoke the proper function to write the desired output file format.

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.