Building with HOOPS Access

After the package is unpacked and the license is activated, this page describes how to compile and link a program against HOOPS Access.

Pick the tab that matches your situation. Building Your Own Application is the recommended route for any new project; the legacy tab is kept for projects that were link against the old obfuscated source distribution.

Building Your Own ApplicationLegacy Approach (Obfuscated Source Code)

The package is a binary distribution. You only compile your code, and then link it to the pre-compiled libraries.

Package Contents

The HoopsSAM library is designed to link against the third-party packages bundled with the distribution. These packages are tested with HOOPS SAM to ensure compatibility. The distribution includes libraries such as Abaqus, Ansys DPF, Blosc, CGNS, GKLib, HDF5, Intel MKL, Intel OpenMP, and METIS. The exact versions are listed in the corresponding third-party folders and are documented in the release notes for the package. Each third-party software is redistributed under its respective license terms. Tech Soft 3D is not the author of those packages, and redistribution is subject to the license terms included with the distribution. See the appropriate release note page to find a list of the provided packages with their versions. This information is only available starting HOOPS SAM 2.5.0.

The extracted package root is named according to the platform it was generarted on, for example HOOPS_Solve_Access_Mesh_<version>_Windows_x86-64_v142\ on Windows and HOOPS_Solve_Access_Mesh_<version>_Linux_x86-64_glibc235/ on Linux. The HOOPS SAM releases use the Semantic Versioning scheme. The include file base.h defines two macros that can be used to retrieve version information:

• SYS_VERSION defines a hexadecimal value built up from the major, minor, and patch version numbers. This value is guaranteed to be monotonically increasing for each new release.
• SYS_VERSIONSTR defines a string built up from the major, minor, and patch version numbers. It may also contain pre-release or other supplemental information if available.

WindowsLinux

HOOPS_Solve_Access_Mesh_<version>_Windows_x86-64_v142\
│
├── include\                                <- the HEADER files + source files for bindings of FORTRAN, C++, and C#
│   ├── sam\                                <- C API:   base, vis, vdm, vfe, vfs, vfx, msh
│   └── samcpp\                             <- C++ API: core, access
│
├── lib\                                    <- IMPORT libraries, used by the LINKER
│   ├── HoopsSAM_core.lib                   <- Foundation.
│   ├── HoopsSAM_access.lib                 <- Access library: reading and writing CAE files.
│   ├── HoopsSAM_mesh.lib                   <- Mesh library: meshing functionality.
│   ├── HoopsSAM_solve.lib                  <- Solve library: solving functionality.
│   ├── HoopsSAM_linearAlgebraCore.lib      <- linear algebra core functionality used by solve and mesh (internally)
│   ├── HoopsSAM_static_MD.lib              <- static variant, /MD runtime
│   ├── HoopsSAM_static_MT.lib              <- static variant, /MT runtime
│   ├── DataProviderHostLib.lib             <- data provider host library
│   ├── DataProviderPluginHeaders.lib       <- data provider plugin headers library
│   └── zlibstatic.lib                      <- static variant of zlib

│
├── bin\                                    <- the DLLs, loaded by the PROGRAM at run time
│   ├── HoopsSAM_core.dll
│   ├── HoopsSAM_access.dll
│   ├── HoopsSAM_mesh.dll
│   ├── HoopsSAM_solve.dll
│   ├── HoopsSAM_linearAlgebraCore.dll
│   ├── HoopsSAMcs.dll                      <- C# wrapper DLL for HoopsSAM
│   ├── exchangePlugin\                     <- plugin for exchange library
│   ├── openfoamPlugin\                     <- plugin for OpenFOAM reader
│   ├── vtkPlugin\                          <- plugin for VTK readers
│   └── dynamicLoadingLibraries\            <- wrapper libraries for Abaqus, AutoDyn and SAMCEF readers
│
├── thirdparty\                             <- helper libraries/ vendor SDKS
│   ├── intelopenmp-<version>-win64\
│   ├── intelmkl.win-x64\
│   ├── hdf5-<version>-win64\
│   ├── abaqus-odb_api-<year>-win64\
│   └── ...
│
├── Examples\                               <- ready-made sample programs (sam, legacy)
├── cmake\                                  <- helper modules used by the examples
├── DataProviderFramework\                  <- plugin SDKs framework
├── dynamicLoadingWrapperSource\            <- source of the reader wrappers
├── migration_scripts\                      <- scripts to help with migrating between major versions
├── VersionInfo.json
└── README.txt

Important

The files in lib are primarily import libraries used during linking, while the DLLs in bin are loaded at runtime. The only exceptions are the two static libraries.

The next step is to focus on building the program and connecting it to the required components:

Folder	Job
include	C++C #include "samcpp/access/access.h" #include "samcpp/core/core.h"
lib	WindowsLinux HoopsSAM_access.lib HoopsSAM_core.lib
thirdparty	Dependency libraries (Intel OpenMP, HDF5, Zlib and vendor SDKs)

Step 1 - Create Your Project Folder

Create an empty folder named AccessExample for the project. It does not need to live next to the distribution. The project consists of two files:

AccessExample/
├── CMakeLists.txt      <- the recipe (Step 3)
└── main.cpp            <- your program (Step 2)

Step 2 - Write A Very Small Program

Create main.cpp. The program below opens a CAE file given on the command line and prints its table of contents.

C++C

#include "samcpp/core/core.h"
#include "samcpp/access/access.h"
#include "sam/hoops_license.h"
#include <iostream>

/*----------------------------------------------------------------------
                    Print Table of Contents
----------------------------------------------------------------------*/
int
main(int argc, char** argv)
{
    char inputFile[cae::core::MAX_NAME_LENGTH] = {};
    // Check input arguments
    if (argc < 2) {
        std::cerr << "Usage: " << argv[0] << " inputfile [appendfile]\n";
        std::cerr << " inputfile is blank, 'bumper.unv' is assumed\n";
        strcpy(inputFile, "bumper.unv");
    }
    else {
        strcpy(inputFile, argv[1]);
    }

    cae::core::license::validate(HOOPS_LICENSE);

    // Open file
    cae::access::DataSource dataSource;
    cae::core::Status status = dataSource.openFile(inputFile, nullptr);

    // Check for error
    if (!status) {
        std::cerr << "Error: opening file " << inputFile << '\n';
        exit(1);
    }

    // Set verbose mode and print table of contents
    dataSource.setIntegerParameter(cae::access::DataSource::IntegerParameter::VERBOSE, 1);
    dataSource.printTableOfContents("*");

    return 0;
}

Warning

The HOOPS_LICENSE must be validated before any calls to the HOOPS Access API functions. Please refer to Installing HOOPS Access for more details.

Step 3 - Write The CMakeLists.txt

Create CMakeLists.txt next to main.cpp (Step 2). Pick the flavour you want: link against the shared libraries (the usual choice), or link everything into one self-contained executable. The library names differ per platform, so there is one tab per combination.

Shared Linking - WindowsShared Linking - LinuxStatic Linking - WindowsStatic Linking - Linux

cmake_minimum_required(VERSION 3.21)

project(AccessExample LANGUAGES CXX)

# --- 1. Path to unpacked distribution------------------------------
set(SAM_ROOT "" CACHE PATH "Root of the HOOPS Solve, Access & Mesh distribution")

set(SAM_INCLUDE_DIR "${SAM_ROOT}/include")
set(SAM_LIB_DIR     "${SAM_ROOT}/lib")

# --- 2. executable --------------------------------------------------------
add_executable(access_example main.cpp)
target_compile_features(access_example PRIVATE cxx_std_17)

# --- 3. Headers -------------------------------------------------------------
target_include_directories(access_example PRIVATE "${SAM_INCLUDE_DIR}")

# --- 4. Libraries -----------------------------------------------------------
target_link_libraries(access_example PRIVATE
    "${SAM_LIB_DIR}/HoopsSAM_access.lib"
    "${SAM_LIB_DIR}/HoopsSAM_core.lib")

install(TARGETS access_example RUNTIME DESTINATION bin)

Note

The transitive dependencies of the main libraries (HoopsSAM_access and HoopsSAM_core) are not automatically found at runtime. They are available in the thirdparty folders, so you need to add them to PATH - see Dependencies.

Step 4 - Configure And Build

WindowsLinux

The Visual Studio generator is multi-configuration: you do not choose the build type when you configure, you choose it when you build.

cmake -S . -B AccessExample ^
      -G "Visual Studio 16 2019" -A x64 ^
      -DSAM_ROOT=C:\path\to\HOOPS_Solve_Access_Mesh_<version>_Windows_x86-64_v142

cmake --build AccessExample --config Release

Step 5 - Run It

Compilation and linking alone are not sufficient. At runtime, the program must locate the shared libraries, and HOOPS Access may also load additional reader libraries on demand. The required search paths are provided through environment variables: PATH on Windows and LD_LIBRARY_PATH on Linux.

Note

This step is still required even when linking statically. Only the HoopsSAM_* libraries (and zlib) are embedded in the executable; Intel OpenMP, HDF5, and the reader libraries remain external and are loaded on demand. The thirdparty folders below must therefore remain accessible in either configuration.

WindowsLinux

set SAM_ROOT=C:\path\to\HOOPS_Solve_Access_Mesh_<version>_Windows_x86-64_v142

set PATH=%SAM_ROOT%\bin;%PATH%
set PATH=%SAM_ROOT%\thirdparty\intelopenmp-2023.1.0-win64\bin;%PATH%
set PATH=%SAM_ROOT%\thirdparty\hdf5-1.14.5-win64\bin;%PATH%

AccessExample\Release\access_example.exe "%SAM_ROOT%\Examples\sam\vdm\bumper.unv"

Congratulations, your first program is built with HOOPS Access.

Note

This example did not required to load any third party libraries. But, in general, most of the CAE readers require additional third party libraries espeacially for result files. These third party libraries has to be loaded when needed. This deserves a page of its own: see Dependencies.

Dependencies

A HOOPS Access application depends on it’s main libraries and, for some file formats, additional reader components that are loaded only when required. Many common formats are supported directly by the core libraries, while proprietary or vendor-specific formats may require extra third-party dependencies. Environment variables define the search paths used to locate these components. The section below describes the third-party libraries bundled with the package and the variables used to locate them.

The Third-Party Libraries Of HOOPS Access provided with the package

LibraryType / thirdparty folder	Requirement	Needed for	Environment variable	Wrapper library or Vendor library
ABAQUS (abaqus-odb_api-<year>-*)	Optional	Abaqus results	CEE_SAM_READER_ODB_LIBRARY_DIR	dynamically loaded through OdbWrapper_<year>.so / OdbWrapper_<year>.dll
Ansys DPF (ansys-dpf-*)	Optional	Ansys results	-	- (mapdlOperatorsCore.dll / libmapdlOperatorsCore.so dynamically loaded without a wrapper)
BLOSC (c-blosc-*)	Optional	Compressed HDF5 files (Nastran H5)	CEE_SAM_READER_BLOSC_LIBRARY_DIR	- (blosc.dll / libblosc*.so dynamically loaded without a wrapper)
CGNS (cgns-*)	Optional	CGNS results	CEE_SAM_READER_CGNS_LIBRARY_DIR	- (cgnsdll.dll / libcgns*.so dynamically loaded without a wrapper)
HDF5 (hdf5-*)	Mandatory	HDF5-based formats	-	dynamically linked
Intel OpenMP (intelopenmp-*)	Mandatory	Widely used for parallelism	-	dynamically linked
Zlib (in lib, not thirdparty)	Required for static linking	HDF5-based formats	-	statically linked (zlibstatic.lib / libzstatic.a)

The following table describes the third-party libraries that are not included in the package; they must be installed separately and are loaded on demand.

LibraryType / thirdparty folder	Requirement	Needed for	Environment variable	Wrapper library or Vendor library
ANSYS_AUTODYN (ansys-autodyn-*)	Optional	Autodyn results	CEE_SAM_READER_AUTODYN_LIBRARY_DIR	dynamically loaded through AutodynWrapper
ANSYS_CFX (ansys-cfx-*)	Optional	CFX results	CEE_SAM_READER_ANSYS_CFX_LIBRARY_DIR	dynamically loaded through Ansys_CfxWrapper
FEMZIP (femzip-*)	Optional	FEMZIP-compressed LS-DYNA files	CEE_SAM_READER_FEMZIP_LIBRARY_DIR	- (femzip_a_dyna_sidact_generic.dll / libfemzip_a_dyna_sidact_generic.so dynamically loaded without a wrapper) See the warning below.
H3D (altair-h3d-*)	Optional	Altair results	CEE_SAM_READER_H3D_LIBRARY_DIR	- (h3dreader.dll / libh3dreader.so dynamically loaded without a wrapper)
SAMCEF (samcef-*)	Optional	Samcef results	CEE_SAM_READER_SAMCEF_LIBRARY_DIR	dynamically loaded through SamcefWrapper
STARCCM (starccm-libccmio-*)	Optional	STAR-CCM+ results	CEE_SAM_READER_STARCCM_LIBRARY_DIR	- (ccmio.dll, adf.dll / libccmio.so, libadf.so dynamically loaded without a wrapper)

Warning

Due to distribution restrictions, the Ansys CFX static libraries must be installed separately. The wrapper library source is provided in $SAM_ROOT/dynamicLoadingWrapperSource/Ansys_Cfx. Use the CMakeLists.txt file in that folder to compile the wrapper library.

The Library Search

The Intel OpenMP and HDF5 libraries are mandatory dynamically linked dependencies that HOOPS Access must find at run time. The reader libraries, on the other hand, are optional and are loaded on demand. There are three ways to tell HOOPS Access where to look for them, listed below in order of precedence (using the ODB reader as an example):

1. An API setting, taking the highest precedence (setCustomDynamicLoadingLibraryDirectoryPath()).

   C++C

   cae::access::Options    options;
   cae::access::DataSource datasource;
   
   /* Specify the Abaqus ODB reader library path */
   options.setCustomDynamicLoadingLibraryDirectoryPath(
       cae::access::Options::LibraryType::ABAQUS,
       "/path/to/SAM_ROOT/lib/dynamicLoadingLibraries/odb/2026");
   
   /* Set the Abaqus ODB version (currently versioning only applicable to ODB files) */
   options.setString(cae::access::Options::StringType::ABALIB_ODBVERSION, "2026");
   
   datasource.openFile("your_odb_file.odb", &options);
   

2. Environment variables as mentioned in the tables above (CEE_SAM_READER_<NAME>_LIBRARY_DIR).

   WindowsLinux

   set CEE_SAM_READER_ODB_LIBRARY_DIR=%SAM_ROOT%\bin\dynamicLoadingLibraries\odb\2026
   

3. Finally, the system’s default search path, such as LD_LIBRARY_PATH on Linux or PATH on Windows.

   WindowsLinux

   set PATH=%SAM_ROOT%\bin;%PATH%
   set PATH=%SAM_ROOT%\thirdparty\intelopenmp-2023.1.0-win64\bin;%PATH%
   set PATH=%SAM_ROOT%\thirdparty\hdf5-1.14.5-win64\bin;%PATH%
   set PATH=%SAM_ROOT%\thirdparty\abaqus-odb_api-2026-win64\lib;%PATH%
   set PATH=%SAM_ROOT%\bin\dynamicLoadingLibraries\odb\2026;%PATH%
   

Tip

For readers with wrapper libraries (Abaqus, AutoDyn, Ansys CFX, and SAMCEF), the wrapper libraries can be relocated from SAM_ROOT/lib/dynamicLoadingLibraries to the corresponding third-party library installation directory. This approach requires only a single library path for both the wrapper and the third-party library.

Note

Custom dynamic loading library names can be configured using one of the following APIs :setCustomDynamicLoadingLibraryName() or vdm_OptionsSetCustomDynamicLoadingLibraryNames().

Need Help ?

The project is now ready for use with HOOPS Access. For additional support, refer to the support resources or the forum.