Overview

Programming Guide

API Reference

2.1 Simple load and export

HOOPS Exchange can be used within your application in two different ways - as a direct or indirect integration.

A direct integration means you are accessing the assembly tree structure, parsing entities, and using that information to inspect the model data or otherwise provide a feature-rich experience to the end user. For information on how you would do this, see section 4, Reading model geometry.

An indirect integration means you are simply reading a model file and using HOOPS Exchange to write it in a different format without reading the assembly tree.

Loading a model

Start HOOPS Exchange by initializing the libraries and setting the license key. That process is described in the initialization section.

Once HOOPS Exchange is initialized, you can use it to load a CAD model into memory. CAD files can be imported with a minimal amount of code:

A3DSDKHOOPSExchangeLoader sHoopsExchangeLoader(myFilename);
A3DStatus importResult = sHoopsExchangeLoader.Import(A3DImport(filename));

If you're doing an indirect integration, you're done. You can export the file as another format by using the code in the next subsection.

For direct integrations, you'll need access to the model file pointer. This pointer gives you a reference to the root of the assembly tree:

A3DAsmModelFile* myModelPtr = sHoopsExchangeLoader.m_psModelFile;

Loading a CAD file with custom options

Many file formats contain extraneous data that is not necessary for all situations. Therefore, before loading the file, you should set the file import parameters to load only the specific data required by your application. Doing so decreases the memory footprint, CPU load, and load time. These parameters are set using the A3DRWParamsLoadData structure:

sReadParam.m_sGeneral.m_bReadSolids = true;
sReadParam.m_sGeneral.m_bReadSurfaces = true;
sReadParam.m_sGeneral.m_bReadPmis = true;
// ... set other A3DRWParamsLoadData fields as necessary
A3DAsmModelFile* pModelFile = NULL;
A3DAsmModelFileLoadFromFile("output.3.prc", &sReadParam, &pModelFile);
// alternatively, if you've used the A3DSDKHOOPSExchangeLoader:
A3DAsmModelFileGet(sHoopsExchangeLoader.m_psModelFile, &modelFileData);

The end result of successful file load is a model file pointer. This structure represents the root entity for a model file. Through it, you can access the assembly tree. There is only one model file per model.

Once in memory, the model is represented by a PRC assembly tree that is equivalent to its native structure. Note that pModelFile points to a model file node. Nodes always have data associated with them, but this data is not populated by default. The following code sample fills the node's data structure so that you can access the information within:

A3DAsmModelFileData modelFileData; // will contain node data
A3DAsmModelFileGet(pModelFile, &modelFileData);

At this point, the model file is loaded into memory and you can use the modelFileData structure to access the assembly tree. As noted above, this is the route you would take to perform a direct integration. For information on how you would do this, see section 7, Reading model geometry.

A PRC assembly tree can contain any number of nodes, and in many cases, they will be nested several levels deep. In order to gather all the information from the PRC, your traversal algorithm must visit every node. Typically, this is done through recursion.

Loading a PDF model

A PDF file can potentially contain multiple 3D data streams. Therefore, simply using A3DAsmModelFileLoadFromFile or A3DAsmModelFileGet will not work because those functions can only handle a single data stream. To load a PDF, you need to use A3DGet3DPDFStreams.

PDF data can be either in PRC or U3D format. If the data is PRC, you can load it from memory. If U3D, you must write the data to a temporary file before reading it using A3DPDF3DStreamCreateFromFile.

A3DStream3DPDFData* pStream3DPDFData;
A3DInt32 iNumStreams;
A3DGet3DPDFStreams((char*) pcFileName, &pStream3DPDFData, &iNumStreams);
// a real use case might parse every stream in the input file. Here, we just take the first one (pStream3DPDFData[0]).
if (pStream3DPDFData[0].m_bIsPrc) // test whether the data is PRC or U3D
{
// even an input PRC file must be read in memory and mapped into modelfile data structures
A3DRWParamsPrcReadHelper* pPrcReadHelper;
A3DAsmModelFileLoadFromPrcStream(pStream3DPDFData[0].m_pcStream, pStream3DPDFData[0].m_iLength, &pPrcReadHelper, ppModelFile);
}
else
{
// A U3D stream must first be stored as a physical file, then read by A3DAsmModelFileLoadFromFile
sprintf(tempfilename, "%s.u3d", OUT_FILE);
FILE * pFile = fopen(tempfilename , "wb");
fwrite(pStream3DPDFData[0].m_pcStream, 1, pStream3DPDFData[0].m_iLength , pFile);
fclose(pFile);
// physical file to stream
A3DAsmModelFileLoadFromFile(tempfilename, sReadParam, ppModelFile);
// the temp file can be disposed of afterwards
remove(tempfilename);
}

Exporting a model

Exporting your model is similar to importing - simply reverse the procedure. You need only three things: the model file pointer, the export parameters structure, and the target filename. The supported export formats can be found here.

Indirect integration with the HOOPSExchangeLoader

Exporting a file with the HOOPSExchangeLoader is the preferred method when you are doing an indirect integration. Simply specify the filename of the import file and the export file. The export file type is determined by the file extension, so you should use a known file extension for the file format.

A3DImport sImport(importFilename);
A3DExport sExport(exportFilename);
A3DStatus iRet = sHoopsExchangeLoader.Convert(sImport, sExport);

Direct integration

Export options vary widely between file types. However, all export data structures have the following name:

A3DRWParamsExport*Data

...where * is substituted with the file type. Suppose you are exporting a STEP file. Configure a A3DRWParamsExportStepData data structure to suit your needs. Then, to export your model, you would do something like this:

A3DRWParamsExportStepData sParamsExportData;
// set export options
sParamsExportData.m_bSaveFacetedToWireframe = true;
sParamsExportData.m_bSaveAnalyticsToNurbs = true;
iRet = A3DAsmModelFileExportToStepFile(pModelFile, &sParamsExportData, pcOutputFileName);
if (iRet != A3D_SUCCESS)
// handle error