{"id":13574636,"url":"https://github.com/facebookincubator/FBX2glTF","last_synced_at":"2025-04-04T15:31:30.632Z","repository":{"id":37431262,"uuid":"106060594","full_name":"facebookincubator/FBX2glTF","owner":"facebookincubator","description":"A command-line tool for the conversion of 3D model assets on the FBX file format to the glTF file format.","archived":false,"fork":false,"pushed_at":"2024-06-11T06:27:30.000Z","size":8567,"stargazers_count":2157,"open_issues_count":99,"forks_count":343,"subscribers_count":83,"default_branch":"main","last_synced_at":"2025-04-02T02:09:50.613Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/facebookincubator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-07T00:18:31.000Z","updated_at":"2025-04-01T09:41:27.000Z","dependencies_parsed_at":"2022-07-19T01:32:59.620Z","dependency_job_id":"a0470117-9155-400c-80b0-5b3fd0896d33","html_url":"https://github.com/facebookincubator/FBX2glTF","commit_stats":{"total_commits":227,"total_committers":26,"mean_commits":8.73076923076923,"dds":0.5110132158590308,"last_synced_commit":"739ee5db94b0ca9eabe2b6ed92f32d13175072a3"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookincubator%2FFBX2glTF","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookincubator%2FFBX2glTF/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookincubator%2FFBX2glTF/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebookincubator%2FFBX2glTF/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facebookincubator","download_url":"https://codeload.github.com/facebookincubator/FBX2glTF/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247202822,"owners_count":20900847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T15:00:53.221Z","updated_at":"2025-04-04T15:31:30.602Z","avatar_url":"https://github.com/facebookincubator.png","language":"C++","funding_links":[],"categories":["C++","Tools, Pipeline \u0026 Utilities"],"sub_categories":["Conversion Tools"],"readme":"# FBX2glTF\n\n[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)\n\nThis is a command line tool for converting 3D model assets on Autodesk's\nvenerable [FBX](https://www.autodesk.com/products/fbx/overview) format to\n[glTF 2.0](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0),\na modern runtime asset delivery format.\n\nPrecompiled binaries releases for Windows, Mac OS X and Linux may be\nfound [here](https://github.com/facebookincubator/FBX2glTF/releases).\n\nBleeding-edge binaries for Windows may be found [here](https://ci.appveyor.com/project/Facebook/fbx2gltf/build/artifacts). Linux and Mac OS X to come; meanwhile, you can [build your own](#building-it-on-your-own).\n\n[![Build Status](https://travis-ci.com/facebookincubator/FBX2glTF.svg?branch=master)](https://travis-ci.com/facebookincubator/FBX2glTF)\n[![Build status](https://ci.appveyor.com/api/projects/status/5mq4vbc44vmyec4w?svg=true)](https://ci.appveyor.com/project/Facebook/fbx2gltf)\n\n## Running\n\nThe tool can be invoked like so:\n\n```\n \u003e FBX2glTF ~/models/butterfly.fbx\n```\n\nOr perhaps, as part of a more complex pipeline:\n\n```\n \u003e FBX2glTF --binary --draco --verbose \\\n          --input ~/models/source/butterfly.fbx \\\n          --output ~/models/target/butterfly.glb\n```\n\nThere are also some friendly \u0026 hands-on instructions available [over at Facebook](https://developers.facebook.com/docs/sharing/3d-posts/glb-tutorials/#convert-from-fbx).\n\n### CLI Switches\n\nYou can always run the binary with --help to see what options it takes:\n\n```\nFBX2glTF 0.9.7: Generate a glTF 2.0 representation of an FBX model.\nUsage: FBX2glTF [OPTIONS] [FBX Model]\n\nPositionals:\n  FBX Model FILE              The FBX model to convert.\n\nOptions:\n  -h,--help                   Print this help message and exit\n  -v,--verbose                Include blend shape tangents, if reported present by the FBX SDK.\n  -V,--version\n  -i,--input FILE             The FBX model to convert.\n  -o,--output TEXT            Where to generate the output, without suffix.\n  -e,--embed                  Inline buffers as data:// URIs within generated non-binary glTF.\n  -b,--binary                 Output a single binary format .glb file.\n  --long-indices (never|auto|always)\n                              Whether to use 32-bit indices.\n  --compute-normals (never|broken|missing|always)\n                              When to compute vertex normals from mesh geometry.\n  --anim-framerate (bake24|bake30|bake60)\n                              Select baked animation framerate.\n  --flip-u                    Flip all U texture coordinates.\n  --no-flip-u                 Don't flip U texture coordinates.\n  --flip-v                    Flip all V texture coordinates.\n  --no-flip-v                 Don't flip V texture coordinates.\n  --no-khr-lights-punctual    Don't use KHR_lights_punctual extension to export FBX lights.\n  --user-properties           Transcribe FBX User Properties into glTF node and material 'extras'.\n  --blend-shape-normals       Include blend shape normals, if reported present by the FBX SDK.\n  --blend-shape-tangents      Include blend shape tangents, if reported present by the FBX SDK.\n  -k,--keep-attribute (position|normal|tangent|binormial|color|uv0|uv1|auto) ...\n                              Used repeatedly to build a limiting set of vertex attributes to keep.\n  --fbx-temp-dir DIR          Temporary directory to be used by FBX SDK.\n\n\nMaterials:\n  --pbr-metallic-roughness    Try to glean glTF 2.0 native PBR attributes from the FBX.\n  --khr-materials-unlit       Use KHR_materials_unlit extension to request an unlit shader.\n\n\nDraco:\n  -d,--draco                  Apply Draco mesh compression to geometries.\n  --draco-compression-level INT in [0 - 10]=7\n                              The compression level to tune Draco to.\n  --draco-bits-for-position INT in [1 - 32]=14\n                              How many bits to quantize position to.\n  --draco-bits-for-uv INT in [1 - 32]=10\n                              How many bits to quantize UV coordinates to.\n  --draco-bits-for-normals INT in [1 - 32]=10\n                              How many bits to quantize nornals to.\n  --draco-bits-for-colors INT in [1 - 32]=8\n                              How many bits to quantize colors to.\n  --draco-bits-for-other INT in [1 - 32]=8\n                              How many bits to quantize all other vertex attributes to.\n```\n\nSome of these switches are not obvious:\n\n- `--embed` is the way to get a single distributable file without using the\n  binary format. It encodes the binary buffer(s) as a single base64-encoded\n  `data://` URI. This is a very slow and space-consuming way to accomplish what\n  the binary format was invented to do simply and efficiently, but it can be\n  useful e.g. for loaders that don't understand the .glb format.\n- `--flip-u` and `--flip-v`, when enabled, will apply a `x -\u003e (1.0 - x)`\n  function to all `u` or `v` texture coordinates respectively. The `u` version\n  is perhaps not commonly used, but flipping `v` is **the default behaviour**.\n  Your FBX is likely constructed with the assumption that `(0, 0)` is bottom\n  left, whereas glTF has `(0, 0)` as top left. To produce spec-compliant glTF,\n  we must flip the texcoords. To request unflipped coordinates:\n- `--long-indices` lets you force the use of either 16-bit or 32-bit indices.\n  The default option is auto, which make the choice on a per-mesh-size basis.\n- `--compute-normals` controls when automatic vertex normals should be computed\n  from the mesh. By default, empty normals (which are forbidden by glTF) are\n  replaced. A choice of 'missing' implies 'broken', but additionally creates\n  normals for models that lack them completely.\n- `--no-flip-v` will actively disable v coordinat flipping. This can be useful\n  if your textures are pre-flipped, or if for some other reason you were already\n  in a glTF-centric texture coordinate system.\n- All three material options are, in their own way, works in progress, but the\n  `--pbr-metallic-roughness` switch is at least compliant with the core spec;\n  unlike the others, it does not depend on an unratified extension. That option\n  will be chosen by default if you supply none of the others. Material switches\n  are documented further below.\n- If you supply any `-keep-attribute` option, you enable a mode wherein you must\n  supply it repeatedly to list _all_ the vertex attributes you wish to keep in\n  the conversion process. This is a way to trim the size of the resulting glTF\n  if you know the FBX contains superfluous attributes. The supported arguments\n  are `position`, `normal`, `tangent`, `color`, `uv0`, and `uv1`.\n- When **blend shapes** are present, you may use `--blend-shape-normals` and\n  `--blend-shape-tangents` to include normal and tangent attributes in the glTF\n  morph targets. They are not included by default because they rarely or never\n  seem to be correctly present in the actual FBX source, which means the SDK\n  must be computing them from geometry, unasked? In any case, they are beyond\n  the control of the artist, and can yield strange crinkly behaviour. Since\n  they also take up significant space in the output file, we made them opt-in.\n\n## Building it on your own\n\nWe currently depend on the open source projects\n[Draco](https://github.com/google/draco),\n[MathFu](https://github.com/google/mathfu),\n[Json](https://github.com/nlohmann/json),\n[cppcodec](https://github.com/tplgy/cppcodec),\n[CLI11](https://github.com/CLIUtils/CLI11),\n[stb](https://github.com/nothings/stb),\nand [fmt](https://github.com/fmtlib/fmt);\nall of which are automatically downloaded and/or built.\n\n**At present, only version 2019.2 of the FBX SDK is supported**. The\nbuild system will not successfully locate any other version.\n\n### Linux and MacOS X\n\nYour development environment will need to have:\n\n- build essentials (gcc for Linux, clang for Mac)\n- cmake\n- python 3.\\* and associated pip3/pip command\n- zstd\n\nThen, compilation on Unix machines will look something like:\n\n```\n# Determine SDK location \u0026 build settings for Linux vs (Recent) Mac OS X\n\u003e if [[ \"$OSTYPE\" == \"darwin\"* ]]; then\n    export CONAN_CONFIG=\"-s compiler=apple-clang -s compiler.version=10.0 -s compiler.libcxx=libc++\"\n    export FBXSDK_TARBALL=\"https://github.com/zellski/FBXSDK-Darwin/archive/2019.2.tar.gz\"\nelif [[ \"$OSTYPE\" == \"linux\"* ]]; then\n    export CONAN_CONFIG=\"-s compiler.libcxx=libstdc++11\"\n    export FBXSDK_TARBALL=\"https://github.com/zellski/FBXSDK-Linux/archive/2019.2.tar.gz\"\nelse\n    echo \"This snippet only handles Mac OS X and Linux.\"\nfi\n\n# Fetch Project\n\u003e git clone https://github.com/facebookincubator/FBX2glTF.git\n\u003e cd FBX2glTF\n\n# Fetch and unpack FBX SDK\n\u003e curl -sL \"${FBXSDK_TARBALL}\" | tar xz --strip-components=1 --include */sdk/\n# Then decompress the contents\n\u003e zstd -d -r --rm sdk\n\n# Install and configure Conan, if needed\n\u003e pip3 install conan # or sometimes just \"pip\"; you may need to install Python/PIP\n\u003e conan remote add --force bincrafters https://api.bintray.com/conan/bincrafters/public-conan\n\n# Initialize \u0026 run build\n\u003e conan install . -i build -s build_type=Release ${CONAN_CONFIG}\n\u003e conan build . -bf build\n```\n\nIf all goes well, you will end up with a statically linked executable in `./build/FBX2glTF`.\n\n### Windows\n\n\u003cTODO\u003e the below is out of date\n\nWindows users may [download](https://cmake.org/download) CMake for Windows,\ninstall it and [run it](https://cmake.org/runningcmake/) on the FBX2glTF\ncheckout (choose a build directory distinct from the source).\n\nAs part of this process, you will be asked to choose which generator\nto use. **At present, only Visual Studio 2017 or 2019 is supported.** Older\nversions of the IDE are unlikely to successfully build the tool.\n\nNote that the `CMAKE_BUILD_TYPE` variable from the Unix Makefile system is\nentirely ignored here; it is when you open the generated solution that\nyou will be choose one of the canonical build types — _Debug_,\n_Release_, _MinSizeRel_, and so on.\n\n## Conversion Process\n\nThe actual translation begins with the FBX SDK parsing the input file, and ends\nwith the generation of the descriptive `JSON` that forms the core of glTF, along\nwith binary buffers that hold geometry and animations (and optionally also\nemedded resources such as textures.)\n\nIn the process, each mesh is ripped apart into a long list of triangles and\ntheir associated vertices, with a material assigned to each one. A similar\nprocess happens in reverse when we construct meshes and materials that conform\nto the expectations of the glTF format.\n\n### Animations\n\nEvery animation in the FBX file becomes an animation in the glTF file. The\nmethod used is one of \"baking\": we step through the interval of time spanned by\nthe animation, keyframe by keyframe, calculate the local transform of each\nnode, and whenever we find any node that's rotated, translated or scaled, we\nrecord that fact in the output.\n\nBeyond skeleton-based animation, _Blend Shapes_ are also supported; they are\nread from the FBX file on a per-mesh basis, and clips can use them by varying\nthe weights associated with each one.\n\nThe baking method has the benefit of being simple and precise. It has the\ndrawback of creating potentially very large files. The more complex the\nanimation rig, the less avoidable this data explosion is.\n\nThere are three future enhancements we hope to see for animations:\n\n- Version 2.0 of glTF brought us support for expressing quadratic animation\n  curves, where previously we had only had linear. Not coincidentally, quadratic\n  splines are one of the key ways animations are expressed inside the FBX. When\n  we find such a curve, it would be more efficient to output it without baking\n  it into a long sequence of linear approximations.\n- We do not yet ever generate\n  [sparse accessors](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#sparse-accessors),\n  but many animations (especially morph targets) would benefit from this\n  storage optimisation.\n- Perhaps most useful in practice is the idea of compressing animation curves\n  the same way we use Draco to compress meshes (see below). Like geometry,\n  animations are highly redundant — each new value is highly predictable from\n  preceding values. If Draco extends its support for animations (it's on their\n  roadmap), or if someone else develops a glTF extension for animation\n  compression, we will likely add support in this tool.\n\n### Materials\n\nWith glTF 2.0, we leaped headlong into physically-based rendering (PBR), where\nthe canonical way of expressing what a mesh looks like is by describing its\nvisible material in fundamental attributes like \"how rough is this surface\".\n\nBy contrast, FBX's material support remains largely in the older world of\nLambert and Phong, with simpler and more direct illumination and shading\nmodels. These modes are inherently incompatible — for example, textures in the\nold workflow often contain baked lighting of the type that would arise naturally\nin a PBR environment.\n\nSome material settings remain well supported and transfer automatically:\n\n- Emissive constants and textures\n- Occlusion maps\n- Normal maps\n\nThis leaves the other traditional settings, first of Lambert:\n\n- Ambient — this is anathema in the PBR world, where such effects should\n  emerge naturally from the fundamental colour of the material and any ambient\n  lighting present.\n- Diffuse — the material's direction-agnostic, non-specular reflection,\n  and additionally, with Blinn/Phong:\n- Specular — a more polished material's direction-sensitive reflection,\n- Shininess — just how polished the material is; a higher value here yields a\n  more mirror-like surface.\n\n(All these can be either constants or textures.)\n\n#### Exporting as Unlit\n\nIf you have a model was constructed using an unlit workflow, e.g. a photogrammetry\ncapture or a landscape with careful baked-in lighting, you may choose to export\nit using the --khr-materials-common switch. This incurs a dependency on the glTF\nextension 'KHR_materials_unlit; a client that accepts that extension is making\na promise it'll do its best to render pixel values without lighting calculations.\n\n**Note that at the time of writing, this glTF extension is still undergoing the\nratification process**\n\n#### Exporting as Metallic-Roughness PBR\n\nGiven the command line flag --pbr-metallic-roughness, we throw ourselves into\nthe warm embrace of glTF 2.0's PBR preference.\n\nAs mentioned above, there is little consensus in the world on how PBR should be\nrepresented in FBX. At present, we support only one format: Stingray PBS. This\nis a feature that comes bundled with Maya, and any PBR model exported through\nthat route should be digested propertly by FBX2glTF.\n\n(A happy note: Allegorithmic's Substance Painter also exports Stingray PBS,\nwhen hooked up to Maya.)\n\n## Draco Compression\n\nThe tool will optionally apply [Draco](https://github.com/google/draco)\ncompression to the geometric data of each mesh (vertex indices, positions,\nnormals, per-vertex color, and so on). This can be dramatically effective\nin reducing the size of the output file, especially for static models.\n\nEnabling this feature adds an expressed required dependency in the glTF on the\n`KHR_draco_geometry_compression` extension, and can thus only be loaded by a\nviewer that is willing and able to decompress the data.\n\n**Note that at the time of writing, this glTF extension is still undergoing the\nratification process.**\n\n## Future Improvements\n\nThis tool is under continuous development. We do not have a development roadmap\nper se, but some aspirations have been noted above. The canonical list of active\nTODO items can be found\n[on GitHub](https://github.com/facebookincubator/FBX2glTF/labels/enhancement).\n\n## Authors\n\n- Pär Winzell\n- J.M.P. van Waveren\n- Amanda Watson\n\n## License\n\nFBX2glTF is licensed under the [3-clause BSD license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebookincubator%2FFBX2glTF","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacebookincubator%2FFBX2glTF","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebookincubator%2FFBX2glTF/lists"}