rapidobj

The rapidobj::MaterialLibrary object controls how .mtl files are located and loaded during parsing. It can be used to specify search paths (relative or absolute), provide material definitions as raw strings, or instruct the parser to ignore materials entirely.

Common Constructors:

• Default(): For ParseFile, searches the .obj file's directory. For ParseStream, ignores materials but populates Mesh::material_ids.
• SearchPath(path, policy): Specifies a single search path. Relative paths are relative to the .obj file's parent folder and only work with ParseFile.
• SearchPaths(paths, policy): Specifies multiple paths to be searched in order. The first match is used.
• String(text): Provides material definitions directly via a string.
• Ignore(): Completely ignores all material libraries; Materials and Mesh::material_ids will be empty.

// Search multiple paths in order
MaterialLibrary mtllib = MaterialLibrary::SearchPaths({ "materials", "../materials", "." });
Result result = ParseFile("/home/user/teapot/teapot.obj", mtllib);

// Define materials via string
static constexpr auto materials = R"(
    newmtl red
    Kd 1 0 0
)";
Result result = ParseFile("/home/user/teapot/teapot.obj", MaterialLibrary::String(materials));

You can install rapidobj to your system directories using CMake. This allows you to use find_package in your own projects.

Installation Steps

1. Configure and generate the build files from the rapidobj directory: cmake -B build .
2. Install the package (requires administrative access): cd build && sudo make install

Usage in your CMakeLists.txt

Once installed, use find_package to link against the rapidobj::rapidobj target. Note that the header is placed in a rapidobj subfolder.

Note: When using the system installation, the include directive must be #include "rapidobj/rapidobj.hpp".

# Build and install
cmake -B build .
cd build
sudo make install

add_executable(my_app my_src.cpp)

find_package(RapidObj REQUIRED)

target_link_libraries(my_app PRIVATE rapidobj::rapidobj)

// Required include path for system installation
#include "rapidobj/rapidobj.hpp"

If you want to install rapidobj to a specific folder (e.g., in your home directory) instead of system directories, use the RAPIDOBJ_INCLUDE_DIR and RAPIDOBJ_CMAKE_DIR CMake cache variables.

Installation Steps

1. Configure with custom paths: cmake -B build -DRAPIDOBJ_INCLUDE_DIR=${HOME}/local/include -DRAPIDOBJ_CMAKE_DIR=${HOME}/local/cmake .
2. Install (no sudo required): cd build && make install

Usage in your CMakeLists.txt

Since the installation is in a non-standard location, you must provide a hint to find_package using the HINTS argument pointing to your custom CMake directory.

# Configure for local installation
cmake -B build -DRAPIDOBJ_INCLUDE_DIR=${HOME}/local/include -DRAPIDOBJ_CMAKE_DIR=${HOME}/local/cmake .

# Install
cd build
make install

add_executable(my_app my_src.cpp)

# Use HINTS to locate the custom installation
find_package(RapidObj REQUIRED HINTS $ENV{HOME}/local/cmake)

target_link_libraries(my_app PRIVATE rapidobj::rapidobj)

You can include rapidobj directly within your project structure without a system-wide installation. There are two primary methods:

Method 1: Manual Embedding

1. Create a thirdparty folder in your project root.
2. Copy the rapidobj source into that folder.
3. Use add_subdirectory in your CMakeLists.txt.

Method 2: FetchContent (Automated)

Use CMake's FetchContent module to automatically download and integrate rapidobj from its GitHub repository during the configuration step.

# Method 1: Manual subdirectory
add_executable(my_app my_src.cpp)
add_subdirectory(thirdparty/rapidobj)
target_link_libraries(my_app PRIVATE rapidobj::rapidobj)

# Method 2: FetchContent
add_executable(my_app my_src.cpp)

include(FetchContent)

FetchContent_Declare(rapidobj
    GIT_REPOSITORY  https://github.com/guybrush77/rapidobj.git
    GIT_TAG         origin/master)

FetchContent_MakeAvailable(rapidobj)

target_link_libraries(my_app PRIVATE rapidobj::rapidobj)

To calculate the total number of triangles in an .obj file, use rapidobj::ParseFile to load the data, followed by rapidobj::Triangulate to ensure all faces are converted to triangles. You can then iterate through the result.shapes and sum the size of shape.mesh.num_face_vertices to get the total triangle count.

#include "rapidobj/rapidobj.hpp"

#include <iostream>

int main()
{
    rapidobj::Result result = rapidobj::ParseFile("/path/to/my.obj");

    if (result.error) {
        std::cout << result.error.code.message() << '\n';
        return EXIT_FAILURE;
    }

    bool success = rapidobj::Triangulate(result);

    if (!success) {
        std::cout << result.error.code.message() << '\n';
        return EXIT_FAILURE;
    }

    size_t num_triangles{};

    for (const auto& shape : result.shapes) {
        num_triangles += shape.mesh.num_face_vertices.size();
    }

    std::cout << "Shapes:    " << result.shapes.size() << '\n';
    std::cout << "Materials: " << result.materials.size() << '\n';
    std::cout << "Triangles: " << num_triangles << '\n';

    return EXIT_SUCCESS;
}