Simple Load and Export

Whether you need to convert a CAD file to another format or explore its content using the API, the first step is always the same: loading the file into memory. This document covers how to load and export CAD files with HOOPS Exchange.

In HOOPS Exchange, a CAD file loaded into memory is called a model file. It can be referenced using the A3DAsmModelFile type, which represents the topmost entity of your file.

Loading a CAD File

To load a model file from disk, use the A3DAsmModelFileLoadFromFile() function. It requires:

  • a C-string file path (A3DUTF8Char*),
  • a set of load parameters (A3DRWParamsLoadData), and
  • a location to store the model file handle (A3DAsmModelFile**).
A3DAsmModelFile*    model_file  = A3D_NULL_HANDLE;
A3DRWParamsLoadData read_params = A3D_MAKE_DATA(A3DRWParamsLoadData);

A3DStatus status = A3DAsmModelFileLoadFromFile("path/to/file", &read_params, &model_file);

The function returns A3D_SUCCESS, or another code in case of failure. See the reference guide for A3DAsmModelFileLoadFromFile() for the complete list of possible errors. If the file is properly loaded, model_file contains a handle to a valid model file entity.

Once your model file is loaded, you can:

Using Custom Import Options

Before loading a file, you can configure import parameters to specify what data to load. Use the A3DRWParamsLoadData structure to enable the features you need, such as solids, surfaces, or PMI.

A3DRWParamsLoadData is an extensive structure that contains several sub-structures:

Field Name Structure Description
m_sGeneral A3DRWParamsGeneralData General reading parameters
m_sPmi A3DRWParamsPmiData Parameters for PMI reading
m_sTessellation A3DRWParamsTessellationData Tessellation reading parameters
m_sAssembly A3DRWParamsAssemblyData Reading parameters for assembly files
m_sMultiEntries A3DRWParamsMultiEntriesData Parameters for reading multiple models
m_sSpecifics A3DRWParamsSpecificLoadData Parameters specific to each CAD format
m_sIncremental A3DRWParamsIncrementalLoadData Reading parameters for incremental loading

You do not need to set all fields explicitly. Only set the ones you need, and leave the others default-initialized.

A3DRWParamsLoadData params = A3D_MAKE_DATA(A3DRWParamsLoadData);

params.m_sGeneral.m_bReadSolids   = A3D_TRUE;
params.m_sGeneral.m_bReadSurfaces = A3D_TRUE;
params.m_sGeneral.m_bReadPmis     = A3D_TRUE;

A3DAsmModelFile* model_file = A3D_NULL_HANDLE;
A3DStatus status = A3DAsmModelFileLoadFromFile("model.stp", &params, &model_file);

Here is a more complete example from the ImportExport Example:

The model file handle returned by A3DAsmModelFileLoadFromFile() doesn’t contain data directly. To navigate the CAD hierarchy, retrieve its information using A3DAsmModelFileGet(). See the PRC page for more information.

Unloading a Model File

When you’re done with a model file, free it using A3DAsmModelFileDelete():

A3DStatus status = A3DAsmModelFileDelete(model_file);

Incremental Load

Incremental load allows you to load specific parts into memory without loading the entire model. Exchange loads the full assembly structure (product occurrences), but only the geometry and tessellation of specified parts. This reduces memory overhead and improves performance for large CAD models.

Incremental load is available for certain file formats, including SolidWorks, NX (Unigraphics), Creo (Pro/E), JT, and CATIA V5. Support is indicated on the format information pages.

The workflow consists of two steps:

  1. Load structure only: Load the assembly tree without geometry
  2. Load specific parts: Load geometry for selected product occurrences
// Step 1: Load assembly structure only
A3DRWParamsLoadData load_params = A3D_MAKE_DATA(A3DRWParamsLoadData);
load_params.m_sIncremental.m_bLoadStructureOnly = A3D_TRUE;

A3DAsmModelFile* model_file = A3D_NULL_HANDLE;
A3DStatus status = A3DAsmModelFileLoadFromFile("assembly.CATProduct", &load_params, &model_file);

// Traverse the assembly tree to find the parts you need...
// Store the target part in pLeafProductOccurrence
// Store its parent in pRootProductOccurrence

// Step 2: Load geometry for specific parts
load_params.m_sGeneral.m_eReadGeomTessMode = kA3DReadGeomAndTess;
load_params.m_sIncremental.m_bLoadStructureOnly = A3D_FALSE;
load_params.m_sIncremental.m_ppProductOccurrences = &pLeafProductOccurrence;
load_params.m_sIncremental.m_uiProductOccurrencesSize = 1;
load_params.m_sIncremental.m_pRootProductOccurrence = pRootProductOccurrence;

status = A3DAsmModelFileLoadFromFile("assembly.CATProduct", &load_params, &model_file);

Note

  • Only leaf nodes (parts with geometry) can be loaded incrementally.
  • Assembly-level geometry, PMI, and views are not supported.
  • Attempting to load an assembly product occurrence returns A3D_LOAD_INVALID_PARAMETERS_FOR_INCREMENTAL_LOAD.
  • Metadata for JT format is not supported in incremental mode.

To unload parts after use, call A3DAsmModelFileUnloadParts().

A complete example is available in the Incremental Load sample. You can also evaluate incremental mode in the HOOPS Demo Viewer (see the HDV documentation for instructions).

Loading a PDF Model

HOOPS Exchange supports reading PRC and U3D content embedded in PDF files. This is done by first extracting data streams from a PDF file and loading those streams into a new model file.

For more information, see Loading a PDF Model.

Exporting a CAD File

Each export format has its own function and parameter structure. The general pattern is:

  1. Create and configure an export parameters structure
  2. Call the format-specific export function
// Example: Export to STEP
A3DRWParamsExportStepData export_params = A3D_MAKE_DATA(A3DRWParamsExportStepData);
export_params.m_bSaveFacetedToWireframe = A3D_TRUE;

A3DStatus status = A3DAsmModelFileExportToStepFile(model_file, &export_params, "output.stp");

The supported export formats are listed in the supported formats page.

Export Functions Reference

The following table lists all available export functions and their parameter structures:

Format Function Parameters Structure
3MF A3DAsmModelFileExportTo3mfFile() A3DRWParamsExport3mfData
ACIS A3DAsmModelFileExportToAcisFile() A3DRWParamsExportAcisData
FBX A3DAsmModelFileExportToFbxFile() A3DRWParamsExportFbxData
glTF A3DAsmModelFileExportToGltfFile() A3DRWParamsExportGltfData
HTML A3DAsmModelFileExportToHTMLFile() A3DRWParamsExportHtmlData
IGES A3DAsmModelFileExportToIgesFile() A3DRWParamsExportIgesData
JT A3DAsmModelFileExportToJTFile() A3DRWParamsExportJTData
OBJ A3DAsmModelFileExportToObjFile() A3DRWParamsExportObjData
Parasolid A3DAsmModelFileExportToParasolidFile() A3DRWParamsExportParasolidData
PRC A3DAsmModelFileExportToPrcFile() A3DRWParamsExportPrcData
SCS deprecated_A3DAsmModelFileExportToSCSFile() deprecated_A3DRWParamsExportScsData
STEP A3DAsmModelFileExportToStepFile() A3DRWParamsExportStepData
STL A3DAsmModelFileExportToStlFile() A3DRWParamsExportStlData
U3D A3DAsmModelFileExportToU3DFile() A3DRWParamsExportU3DData
VRML A3DAsmModelFileExportToVrmlFile() (none)
XML A3DAsmModelFileExportToXMLFile() A3DRWParamsExportXMLData

Here is an example exporting to JT with custom options:

A3DRWParamsExportJTData export_params = A3D_MAKE_DATA(A3DRWParamsExportJTData);
export_params.m_eWriteGeomTessMode    = kA3DWriteGeomAndTess;
export_params.m_bWritePMI             = A3D_TRUE;

A3DStatus status = A3DAsmModelFileExportToJTFile(model_file, &export_params, "output.jt");

Using the C++ Convenience Wrapper

HOOPS Exchange provides a C++ convenience wrapper called HOOPSExchangeLoader for simpler file-to-file conversion scenarios. This wrapper is useful when you don’t need to manipulate the model file between import and export.

The wrapper uses A3DImport and A3DExport classes to configure options, and the Convert() method to perform the conversion in a single call. The export format is determined automatically from the output file extension.

#include <ExchangeToolkit.h>

HOOPSExchangeLoader loader;

A3DImport import_options("input.CATProduct");
A3DExport export_options("output.step");

A3DStatus status = loader.Convert(import_options, export_options);

You can also customize import and export parameters through the wrapper:

A3DImport import_options("input.CATProduct");
import_options.m_sLoadData.m_sGeneral.m_bReadPmis = A3D_TRUE;

A3DExport export_options("output.jt");
export_options.m_sExportData.m_bWritePMI = A3D_TRUE;

A3DStatus status = loader.Convert(import_options, export_options);

Note

The HOOPSExchangeLoader wrapper is best suited for simple conversion workflows. For more control over the model file (traversal, modification, multiple exports), use the C API functions directly.