# 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:

- Export it to any of our supported formats
- Traverse and manipulate its content
- Unload it from memory

### 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`
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.

## Related Pages

- Getting Started: File Formats
- Example Code: ImportExport Example
- Tutorial: File-to-File Translation
- Programming Guide: PRC
- API Reference: Load & Export Module

Conversation saved
HOOPSY BETA

### Hello! I'm HOOPSY

Your multilingual generative AI assistant for documentation. Ask me anything about HOOPS Exchange in your own language, or choose a sample question below to start a conversation:

What is HOOPS Exchange?
What are the latest release notes for HOOPS Exchange?
How do I start evaluating HOOPS Exchange?
How do I write my first sample application?
How can I get assistance?

HOOPSY may store conversations according to OpenAI's policy. Responses may not always be accurate.

HOOPSY is thinking...