usdFbx

This project is an SdfFileFormat plugin for USD to enable loading and composing of Autodesk Fbx files inside USD layers. The project configures a standalone version and/or a plugin built specifically for Houdini.

MayaUSD is supported, but only a locally built version of MayaUSD has been tested so far. Using the USD libraries that come with published builds of MayaUSD should theoretically work; however, this is uncharted territory.

The plugin is based on the Alembic example bundled with the USD sources so there are a lot of similarities. In the future, this project may receive a refactor to simplify things.

Capabilities and Limitations

Support for the following FBX Node Types
- FbxNodeAttribute::eNull
- FbxNodeAttribute::eMesh
- FbxNodeAttribute::eSkeleton
- FbxNodeAttribute::eCamera
FBX Phong/Lambert materials are converted to UsdPreviewSurface configurations, hardware shaders are not currently supported
Custom FBX Properties convert into USD properties prefixed with the userProperties: property namespace. The Custom Metadatatum will also be set for these
While access to the fileformat itself by USD is multithreaded, any dealings with the FBX SDK itself is single threaded at the moment
Per bone animated properties are recorded to a set of custom properties onto a UsdSkelAnim prim
The plugin does not and will not support any writing capabilities back into FBX from USD. Editing FBX data is recommended to be done on a new sublayer/edittarget
All FBX scenes will be converted to Y-up, 0.01 metersPerUnit (cm)

Requirements

Software/Library	Version
USD	22.08 or later
Python	3.7+
C++ Compiler	Visual Studio (Win), Gcc (Linux), Xcode (Mac)
CMAKE	3.20+
Fbx SDK	2017.1+ (2020.x is recommended)
[Tests Only] Fbx Python Bindings	Any that works with the Python version used
[Houdini Only] Houdini Developer Kit	19.0+

Compiling

The project has been configured with CMAKE, configuration can be done via command line, CMAKE GUI or inside IDEs with integrated CMAKE support.

The important CMAKE Variables to set are

PXR_USD_LOCATION: Root directory of the installed USD distribution
ADSK_FBX_LOCATION: Root Directory of the C++ FBX SDK
USDFBX_BUILD_TESTS: Setting this to ON will create a unit_tests target
SIDEFX_HDK_LOCATION: Root Directory of the Houdini Development Kit. When setting this, a new target called usdFbx_houdini will be added

Note on Python

It is recommended to activate and use a Python Virtual Environment (venv, pipenv, conda, etc.) prior to running the CMAKE configuration. When doing so, it's best to pass -DPython_FIND_VIRTUALENV=ONLY to the CMAKE command to minimize any issues with CMAKE's FindPython

Note on `USDFBX_BUILD_TESTS`

The configuration will check for the existence of pytest on current path. Therefor it is recommended to use a Python Virtual Environment (pipenv to make it easy) prior to configuring with this flag enabled.

Examples

Basic

cmake -B build -G "Visual Studio 17 2022" -T host=x64 -A x64 -DPXR_USD_LOCATION="C:\USD\23.05" -DADSK_FBX_LOCATION="C:\Program Files\Autodesk\FBX\FBX SDK\2020.3.4" -DCMAKE_INSTALL_PREFIX="$(Resolve-Path .)\install"

Using Pipenv

pipenv --python 3.9
pipenv install pytest pytest-order python-dotenv pytest-mock
pipenv install <PATH TO FBX SDK PYTHON PACKAGE>
pipenv shell
cmake -B build -G "Visual Studio 17 2022" -T host=x64 -A x64 -DPXR_USD_LOCATION="C:\USD\23.05" -DADSK_FBX_LOCATION="C:\Program Files\Autodesk\FBX\FBX SDK\2020.3.4" -DPython_FIND_VIRTUALENV=ONLY -DUSDFBX_BUILD_TESTS=ON -DCMAKE_INSTALL_PREFIX="$(Resolve-Path .)\install"

Running Tests

Tests have been written in pytest and requires a Python environment with the following dependencies installed:

Python FbxSDK
pytest
pytest-order
python-dotenv
pytest-mock

With this environment active, running the tests can be done by using CMAKE via the unit_tests target

cmake --build ./build --config RelWithDebInfo --target unit_tests -j 32

Or manually by invoking pytest tests.

When running tests manually however, it is important that you have the following environment variables set correctly:

PYTHONPATH: <USD_DIR>/lib/python
PATH: <USD_DIR>/lib;<USD_DIR>/bin;${PATH}
PXR_PLUGINPATH_NAME: <USDFBX_DIR>/build/plugins/usdFbx/<CONFIG>/resources

Where <USD_DIR> is the location of where USD has been installed to, <USDFBX_DIR> is the local clone of this repository and <CONFIG> is the configuration used to build usdFbx.
The CMAKE unit_tests target does all of the above automatically

📝 NOTE
Most test fixtures generate Fbx data rather than rely on static data. For that, you must have the Fbx python SDK (not the bindings) in PYTHONPATH somewhere or have it installed in your environment.

Using the Plugin

Both examples below use the following USD Layer

#usda 1.0

def "y_up_cm"
(
    prepend references = @./suzanne_y_up_cm.fbx@
)
{
}

Where suzanne_y_up_cm.fbx is a Y-Up, cm scale FBX export of Blender's Suzanne mascot.

When using the Python/C++ API for USD you may also simply use Usd.Stage.Open("suzanne_y_up_cm.fbx")/UsdStage::Open("suzanne_y_up_cm.fbx") rather than wrapping in a native USD layer.

USDVIEW

Add <PATH TO INSTALLED USDFBX/RESOURCES> to your PXR_PLUGINPATH_NAME environment variable in addition to setting up a shell the normal way for using USD. After this run usdview <PATH TO LAYER> where <PATH TO LAYER> points to for example the layer mentioned above.

📝 NOTE
If your build of USD has changed the plugin search environment variable, use that instead of PXR_PLUGINPATH_NAME!

📝 WINDOWS ONLY
Currently, the FBX SDK is dynamically linked, meaning that you must also add <PATH TO INSTALLED USDFBX> to your PATH environment variable! Not doing so will result in moduleNotFound errors.

HOUDINI

📝 NOTE
You must have configured CMAKE with SIDEFX_HDK_LOCATION to be able to use the Houdini plugin!

Simply add <PATH TO INSTALLED USDFBX_HOUDINI/RESOURCES> to your PXR_PLUGINPATH_NAME environment variable and launch Houdini from the same shell. You can then add a reference/sublayer/etc... the layer above, or point directly to an fbx.

Remedy-Entertainment/usdFBX