Minor README updates.
- Better 'tar' invocation that doesn't require GNU tar. - No need for GIT_LFS_SKIP_SMUDGE anymore. - Apply VSCode's MarkDown formatting suggestions.
This commit is contained in:
parent
1d735698ba
commit
be627fa228
64
README.md
64
README.md
|
@ -1,4 +1,5 @@
|
||||||
# FBX2glTF
|
# FBX2glTF
|
||||||
|
|
||||||
[](https://opensource.org/licenses/BSD-3-Clause)
|
[](https://opensource.org/licenses/BSD-3-Clause)
|
||||||
|
|
||||||
This is a command line tool for converting 3D model assets on Autodesk's
|
This is a command line tool for converting 3D model assets on Autodesk's
|
||||||
|
@ -17,11 +18,13 @@ Bleeding-edge binaries for Windows may be found [here](https://ci.appveyor.com/p
|
||||||
## Running
|
## Running
|
||||||
|
|
||||||
The tool can be invoked like so:
|
The tool can be invoked like so:
|
||||||
|
|
||||||
```
|
```
|
||||||
> FBX2glTF ~/models/butterfly.fbx
|
> FBX2glTF ~/models/butterfly.fbx
|
||||||
```
|
```
|
||||||
|
|
||||||
Or perhaps, as part of a more complex pipeline:
|
Or perhaps, as part of a more complex pipeline:
|
||||||
|
|
||||||
```
|
```
|
||||||
> FBX2glTF --binary --draco --verbose \
|
> FBX2glTF --binary --draco --verbose \
|
||||||
--input ~/models/source/butterfly.fbx \
|
--input ~/models/source/butterfly.fbx \
|
||||||
|
@ -33,6 +36,7 @@ There are also some friendly & hands-on instructions available [over at Facebook
|
||||||
### CLI Switches
|
### CLI Switches
|
||||||
|
|
||||||
You can always run the binary with --help to see what options it takes:
|
You can always run the binary with --help to see what options it takes:
|
||||||
|
|
||||||
```
|
```
|
||||||
FBX2glTF 0.9.7: Generate a glTF 2.0 representation of an FBX model.
|
FBX2glTF 0.9.7: Generate a glTF 2.0 representation of an FBX model.
|
||||||
Usage: FBX2glTF [OPTIONS] [FBX Model]
|
Usage: FBX2glTF [OPTIONS] [FBX Model]
|
||||||
|
@ -106,7 +110,7 @@ Some of these switches are not obvious:
|
||||||
- `--compute-normals` controls when automatic vertex normals should be computed
|
- `--compute-normals` controls when automatic vertex normals should be computed
|
||||||
from the mesh. By default, empty normals (which are forbidden by glTF) are
|
from the mesh. By default, empty normals (which are forbidden by glTF) are
|
||||||
replaced. A choice of 'missing' implies 'broken', but additionally creates
|
replaced. A choice of 'missing' implies 'broken', but additionally creates
|
||||||
normals for models that lack them completely.
|
normals for models that lack them completely.
|
||||||
- `--no-flip-v` will actively disable v coordinat flipping. This can be useful
|
- `--no-flip-v` will actively disable v coordinat flipping. This can be useful
|
||||||
if your textures are pre-flipped, or if for some other reason you were already
|
if your textures are pre-flipped, or if for some other reason you were already
|
||||||
in a glTF-centric texture coordinate system.
|
in a glTF-centric texture coordinate system.
|
||||||
|
@ -116,7 +120,7 @@ Some of these switches are not obvious:
|
||||||
will be chosen by default if you supply none of the others. Material switches
|
will be chosen by default if you supply none of the others. Material switches
|
||||||
are documented further below.
|
are documented further below.
|
||||||
- If you supply any `-keep-attribute` option, you enable a mode wherein you must
|
- If you supply any `-keep-attribute` option, you enable a mode wherein you must
|
||||||
supply it repeatedly to list *all* the vertex attributes you wish to keep in
|
supply it repeatedly to list _all_ the vertex attributes you wish to keep in
|
||||||
the conversion process. This is a way to trim the size of the resulting glTF
|
the conversion process. This is a way to trim the size of the resulting glTF
|
||||||
if you know the FBX contains superfluous attributes. The supported arguments
|
if you know the FBX contains superfluous attributes. The supported arguments
|
||||||
are `position`, `normal`, `tangent`, `color`, `uv0`, and `uv1`.
|
are `position`, `normal`, `tangent`, `color`, `uv0`, and `uv1`.
|
||||||
|
@ -144,10 +148,12 @@ all of which are automatically downloaded and/or built.
|
||||||
build system will not successfully locate any other version.
|
build system will not successfully locate any other version.
|
||||||
|
|
||||||
### Linux and MacOS X
|
### Linux and MacOS X
|
||||||
|
|
||||||
Your development environment will need to have:
|
Your development environment will need to have:
|
||||||
|
|
||||||
- build essentials (gcc for Linux, clang for Mac)
|
- build essentials (gcc for Linux, clang for Mac)
|
||||||
- cmake
|
- cmake
|
||||||
- python 3.* and associated pip3/pip command
|
- python 3.\* and associated pip3/pip command
|
||||||
- zstd
|
- zstd
|
||||||
|
|
||||||
Then, compilation on Unix machines will look something like:
|
Then, compilation on Unix machines will look something like:
|
||||||
|
@ -165,11 +171,11 @@ else
|
||||||
fi
|
fi
|
||||||
|
|
||||||
# Fetch Project
|
# Fetch Project
|
||||||
> GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/facebookincubator/FBX2glTF.git
|
> git clone https://github.com/facebookincubator/FBX2glTF.git
|
||||||
> cd FBX2glTF
|
> cd FBX2glTF
|
||||||
|
|
||||||
# Fetch and unpack FBX SDK
|
# Fetch and unpack FBX SDK
|
||||||
> curl -sL "${FBXSDK_TARBALL}" | tar xz --strip-components=1 --wildcards */sdk
|
> curl -sL "${FBXSDK_TARBALL}" | tar xz --strip-components=1 --include */sdk/
|
||||||
# Then decompress the contents
|
# Then decompress the contents
|
||||||
> zstd -d -r --rm sdk
|
> zstd -d -r --rm sdk
|
||||||
|
|
||||||
|
@ -198,10 +204,11 @@ versions of the IDE are unlikely to successfully build the tool.
|
||||||
|
|
||||||
Note that the `CMAKE_BUILD_TYPE` variable from the Unix Makefile system is
|
Note that the `CMAKE_BUILD_TYPE` variable from the Unix Makefile system is
|
||||||
entirely ignored here; it is when you open the generated solution that
|
entirely ignored here; it is when you open the generated solution that
|
||||||
you will be choose one of the canonical build types — *Debug*,
|
you will be choose one of the canonical build types — _Debug_,
|
||||||
*Release*, *MinSizeRel*, and so on.
|
_Release_, _MinSizeRel_, and so on.
|
||||||
|
|
||||||
## Conversion Process
|
## Conversion Process
|
||||||
|
|
||||||
The actual translation begins with the FBX SDK parsing the input file, and ends
|
The actual translation begins with the FBX SDK parsing the input file, and ends
|
||||||
with the generation of the descriptive `JSON` that forms the core of glTF, along
|
with the generation of the descriptive `JSON` that forms the core of glTF, along
|
||||||
with binary buffers that hold geometry and animations (and optionally also
|
with binary buffers that hold geometry and animations (and optionally also
|
||||||
|
@ -213,13 +220,14 @@ process happens in reverse when we construct meshes and materials that conform
|
||||||
to the expectations of the glTF format.
|
to the expectations of the glTF format.
|
||||||
|
|
||||||
### Animations
|
### Animations
|
||||||
|
|
||||||
Every animation in the FBX file becomes an animation in the glTF file. The
|
Every animation in the FBX file becomes an animation in the glTF file. The
|
||||||
method used is one of "baking": we step through the interval of time spanned by
|
method used is one of "baking": we step through the interval of time spanned by
|
||||||
the animation, keyframe by keyframe, calculate the local transform of each
|
the animation, keyframe by keyframe, calculate the local transform of each
|
||||||
node, and whenever we find any node that's rotated, translated or scaled, we
|
node, and whenever we find any node that's rotated, translated or scaled, we
|
||||||
record that fact in the output.
|
record that fact in the output.
|
||||||
|
|
||||||
Beyond skeleton-based animation, *Blend Shapes* are also supported; they are
|
Beyond skeleton-based animation, _Blend Shapes_ are also supported; they are
|
||||||
read from the FBX file on a per-mesh basis, and clips can use them by varying
|
read from the FBX file on a per-mesh basis, and clips can use them by varying
|
||||||
the weights associated with each one.
|
the weights associated with each one.
|
||||||
|
|
||||||
|
@ -228,6 +236,7 @@ drawback of creating potentially very large files. The more complex the
|
||||||
animation rig, the less avoidable this data explosion is.
|
animation rig, the less avoidable this data explosion is.
|
||||||
|
|
||||||
There are three future enhancements we hope to see for animations:
|
There are three future enhancements we hope to see for animations:
|
||||||
|
|
||||||
- Version 2.0 of glTF brought us support for expressing quadratic animation
|
- Version 2.0 of glTF brought us support for expressing quadratic animation
|
||||||
curves, where previously we had only had linear. Not coincidentally, quadratic
|
curves, where previously we had only had linear. Not coincidentally, quadratic
|
||||||
splines are one of the key ways animations are expressed inside the FBX. When
|
splines are one of the key ways animations are expressed inside the FBX. When
|
||||||
|
@ -257,33 +266,37 @@ old workflow often contain baked lighting of the type that would arise naturally
|
||||||
in a PBR environment.
|
in a PBR environment.
|
||||||
|
|
||||||
Some material settings remain well supported and transfer automatically:
|
Some material settings remain well supported and transfer automatically:
|
||||||
- Emissive constants and textures
|
|
||||||
- Occlusion maps
|
- Emissive constants and textures
|
||||||
- Normal maps
|
- Occlusion maps
|
||||||
|
- Normal maps
|
||||||
|
|
||||||
This leaves the other traditional settings, first of Lambert:
|
This leaves the other traditional settings, first of Lambert:
|
||||||
- Ambient — this is anathema in the PBR world, where such effects should
|
|
||||||
emerge naturally from the fundamental colour of the material and any ambient
|
- Ambient — this is anathema in the PBR world, where such effects should
|
||||||
lighting present.
|
emerge naturally from the fundamental colour of the material and any ambient
|
||||||
- Diffuse — the material's direction-agnostic, non-specular reflection,
|
lighting present.
|
||||||
and additionally, with Blinn/Phong:
|
- Diffuse — the material's direction-agnostic, non-specular reflection,
|
||||||
- Specular — a more polished material's direction-sensitive reflection,
|
and additionally, with Blinn/Phong:
|
||||||
- Shininess — just how polished the material is; a higher value here yields a
|
- Specular — a more polished material's direction-sensitive reflection,
|
||||||
more mirror-like surface.
|
- Shininess — just how polished the material is; a higher value here yields a
|
||||||
|
more mirror-like surface.
|
||||||
|
|
||||||
(All these can be either constants or textures.)
|
(All these can be either constants or textures.)
|
||||||
|
|
||||||
#### Exporting as Unlit
|
#### Exporting as Unlit
|
||||||
|
|
||||||
If you have a model was constructed using an unlit workflow, e.g. a photogrammetry
|
If you have a model was constructed using an unlit workflow, e.g. a photogrammetry
|
||||||
capture or a landscape with careful baked-in lighting, you may choose to export
|
capture or a landscape with careful baked-in lighting, you may choose to export
|
||||||
it using the --khr-materials-common switch. This incurs a dependency on the glTF
|
it using the --khr-materials-common switch. This incurs a dependency on the glTF
|
||||||
extension 'KHR_materials_unlit; a client that accepts that extension is making
|
extension 'KHR_materials_unlit; a client that accepts that extension is making
|
||||||
a promise it'll do its best to render pixel values without lighting calculations.
|
a promise it'll do its best to render pixel values without lighting calculations.
|
||||||
|
|
||||||
**Note that at the time of writing, this glTF extension is still undergoing the
|
**Note that at the time of writing, this glTF extension is still undergoing the
|
||||||
ratification process**
|
ratification process**
|
||||||
|
|
||||||
#### Exporting as Metallic-Roughness PBR
|
#### Exporting as Metallic-Roughness PBR
|
||||||
|
|
||||||
Given the command line flag --pbr-metallic-roughness, we throw ourselves into
|
Given the command line flag --pbr-metallic-roughness, we throw ourselves into
|
||||||
the warm embrace of glTF 2.0's PBR preference.
|
the warm embrace of glTF 2.0's PBR preference.
|
||||||
|
|
||||||
|
@ -296,6 +309,7 @@ that route should be digested propertly by FBX2glTF.
|
||||||
when hooked up to Maya.)
|
when hooked up to Maya.)
|
||||||
|
|
||||||
## Draco Compression
|
## Draco Compression
|
||||||
|
|
||||||
The tool will optionally apply [Draco](https://github.com/google/draco)
|
The tool will optionally apply [Draco](https://github.com/google/draco)
|
||||||
compression to the geometric data of each mesh (vertex indices, positions,
|
compression to the geometric data of each mesh (vertex indices, positions,
|
||||||
normals, per-vertex color, and so on). This can be dramatically effective
|
normals, per-vertex color, and so on). This can be dramatically effective
|
||||||
|
@ -309,16 +323,18 @@ viewer that is willing and able to decompress the data.
|
||||||
ratification process.**
|
ratification process.**
|
||||||
|
|
||||||
## Future Improvements
|
## Future Improvements
|
||||||
|
|
||||||
This tool is under continuous development. We do not have a development roadmap
|
This tool is under continuous development. We do not have a development roadmap
|
||||||
per se, but some aspirations have been noted above. The canonical list of active
|
per se, but some aspirations have been noted above. The canonical list of active
|
||||||
TODO items can be found
|
TODO items can be found
|
||||||
[on GitHub](https://github.com/facebookincubator/FBX2glTF/labels/enhancement).
|
[on GitHub](https://github.com/facebookincubator/FBX2glTF/labels/enhancement).
|
||||||
|
|
||||||
|
|
||||||
## Authors
|
## Authors
|
||||||
- Pär Winzell
|
|
||||||
- J.M.P. van Waveren
|
- Pär Winzell
|
||||||
- Amanda Watson
|
- J.M.P. van Waveren
|
||||||
|
- Amanda Watson
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
FBX2glTF is licensed under the [3-clause BSD license](LICENSE).
|
FBX2glTF is licensed under the [3-clause BSD license](LICENSE).
|
||||||
|
|
Loading…
Reference in New Issue