akarpetc/guc

glTF to USD converter with MaterialX support

guc

guc is a glTF to Universal Scene Description (USD) converter.

Unlike...

• gltf2usd, it aims to be more than a PoC
• usd_from_gltf, it is not AR Quick Look centric
• Apple's USDZ Tools, it is open-source and freely available

guc furthermore supports near-lossless material translation via the MaterialX standard. Shading networks can be encoded as UsdShade and flattened for backwards compatibility.

All glTF features except animation and skinning are implemented and get continuously tested in guc's test suite.

Wayfair's Iridescent Dish with Olives (CC BY) converted to USD+MaterialX with guc and rendered in hdStorm (left). The same model in Khronos's glTF Sample Viewer (right).

Build

You need USD v22.11+ (e.g. v23.08) with MaterialX and OpenImageIO support enabled.

Do a recursive clone of the repository and set up a build folder:

git clone https://github.com/pablode/guc --recursive
mkdir guc/build && cd guc/build

Pass following parameters in the CMake generation phase:

cmake .. -Wno-dev \
         -Dpxr_DIR=<USD_INSTALL_DIR> \
         -DCMAKE_BUILD_TYPE=Release

Build the executable:

cmake --build . -j8 --target guc --config Release

Note: set BUILD_SHARED_LIBS for shared builds, and CMAKE_MSVC_RUNTIME_LIBRARY to USD's MSVC ABI.

Usage

Usage: guc <gltf_path> <usd_path> [options]

Options:
--emit-mtlx                             Emit MaterialX materials in addition to UsdPreviewSurfaces
--mtlx-as-usdshade                      Convert and inline MaterialX materials with UsdMtlx
--explicit-colorspace-transforms        Explicitly transform colorspaces using MaterialX nodes
--gltf-pbr-impl runtime|file|flattened  How the MaterialX glTF PBR is provided. Default: runtime
--hdstorm-compat                        Apply compatibility tweaks for the USD hdStorm renderer
--default-material-variant              Index of the material variant that is selected by default

Both glTF and GLB file types are valid input. USDA, USDC and USDZ formats can be written.

An example asset conversion is described in the Structure Mapping document.

Note: imaging of USD+MaterialX assets may be incorrect due to a number of current Ecosystem Limitations.

Extension support

Name	Status
KHR_lights_punctual	✅ Partial 1
KHR_materials_clearcoat	✅ Complete
KHR_materials_emissive_strength	✅ Complete
KHR_materials_ior	✅ Complete
KHR_materials_iridescence	✅ Complete
KHR_materials_sheen	✅ Complete
KHR_materials_specular	✅ Complete
KHR_materials_transmission	✅ Complete
KHR_materials_unlit	🚧 Planned
KHR_materials_variants	✅ Complete
KHR_materials_volume	✅ Partial 2
KHR_texture_transform	✅ Complete

^[1] Spotlight cone falloff is ignored.
^[2] Thickness is not supported by the MaterialX glTF PBR implementation.

Sdf plugin

The usdGlTF library implements USD's Sdf file format interface. Enable the CMake option and install it as follows:

cmake --install . --component usdGlTF --config Release --prefix <USD_INSTALL_DIR>/plugin/usd

Note: the plugin only emits MaterialX materials if the USDGLTF_ENABLE_MTLX environment variable is set.

License

   Copyright 2022 Pablo Delgado Krämer

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.