Balsam Asset Import Tool
The Balsam tool is a command line application that is part of Qt Quick 3D's asset conditioning pipeline. The purpose is to take assets created in digital content creation tools like Maya, 3ds Max, or Blender and convert them into an efficient runtime format for use with Qt Quick 3D. It is not possible, nor does it make sense to reference the interchange formats directly in applications because a large amount of resources are needed to parse and condition the content of the asset before it is usable for realtime rendering. Instead the interchange formats can be converted via the Balsam tool into QML Components and resources like geometry and textures.
Usage:
balsam [options] sourceFilename
Example Usage
To convert a 3D asset contained in the file testModel.fbx with balsam the following command would be used:
balsam testModel.fbx
This would generate the following files:
meshes/testModel.meshTestModel.qml
Which can then be used in a Qt Quick 3D project by using that QML Component:
import QtQuick3D
TestModel {
id: modelInstance
}
Supported 3D Asset Types
- Wavefront (.obj)
- COLLADA (.dae)
- FBX (.fbx)
- STL (.stl)
- PLY (.ply)
- GLTF2 (.gltf, .glb)
Some of the formats supported also allow for either embedding or referencing of texture assets. These assets are also supported, provided Qt also has support for them.
Baking for Image-Based Lighting
Balsam also supports generating a pre-filtered cubemap image from .hdr files. Specifying a file with .hdr extension as the input results in generating a file with the same name but with an extension of .ktx. The application can then ship the resulting .ktx file and reference that from the Texture associated with SceneEnvironment::lightProbe. This avoids the costly runtime processing that is necessary for image-based lighting. See Pre-generating IBL cubemap for more details.
Supported Options
The following table lists the command-line options recognized by balsam when converting asset files:
Note: For each boolean option it is possible to use --disable-<option-name>.
| Option | Description |
|---|---|
--outputPath, -o <outputPath> | Sets the location to place the generated file(s). Default is the current directory. |
--calculateTangentSpace | Calculates the tangents and bitangents for the imported meshes. |
--joinIdenticalVertices | Identifies and joins identical vertex data sets within all imported meshes. |
--generateNormals | Generates normals for all faces of all meshes. |
--generateSmoothNormals | Generates smooth normals for all vertices in the mesh. |
--splitLargeMeshes | Splits large meshes into smaller sub-meshes. |
--preTransformVertices | Removes the node graph and pre-transforms all vertices with the local transformation matrices of their nodes. |
--improveCacheLocality | Reorders triangles for better vertex cache locality. |
--removeRedundantMaterials | Searches for redundant/unreferenced materials and removes them. |
--fixInfacingNormals | Tries to determine which meshes have normal vectors that are facing inwards and inverts them. |
--findDegenerates | This step searches all meshes for degenerate primitives and converts them to proper lines or points. |
--findInvalidData | This step searches all meshes for invalid data, such as zeroed normal vectors or invalid UV coords and removes/fixes them. This is intended to get rid of some common exporter errors. |
--transformUVCoordinates | This step applies per-texture UV transformations and bakes them into stand-alone texture coordinate channels. |
--findInstances | This step searches for duplicate meshes and replaces them with references to the first mesh. |
--optimizeMeshes | A postprocessing step to reduce the number of meshes. |
--optimizeGraph | A postprocessing step to optimize the scene hierarchy. |
--useFloatJointIndices | Stores joint indices as floating point numbers for GLES 2.0. |
--globalScale | This step will perform a global scale of the model. |
--globalScaleValue <value> | Global Scale factor used by --globalScale. |
--dropNormals | Drops normals for all faces of all meshes. |
--removeComponentNormals | Removes Normal component from meshes. |
--removeComponentTangentsAndBitangents | Removes Tangents and Bitangents components from meshes. |
--removeComponentColors | Removes any Color components from meshes. |
--removeComponentUVs | Removes any UV components from meshes. |
--removeComponentBoneWeights | Removes any bone weights from meshes. |
--removeComponentAnimations | Removes any animation components from meshes. |
--removeComponentTextures | Removes any embedded texture components from meshes. |
--fbxPreservePivots | Preserves extra pivot nodes created by FBX assets (can create deep node hierarchies) |
--generateMipMaps | Force all imported texture components to generate mip maps for mip map texture filtering |
--useBinaryKeyframes | Record keyframe data as binary files |
--generateLightmapUV | Perform lightmap UV unwrapping and generate an additional UV channel for the meshes. This UV data is then used by the lightmap baker and during run-time lightmapping. |
--generateMeshLevelsOfDetail | When possible create mesh Levels of Detail by automatically simplifying the source mesh. |
--recalculateLodNormals | Calculate new normals when necessary for Generated Mesh levels of detail. |
--recalculateLodNormalsMergeAngle <value> | Maximum angle in degrees to consider for normal smoothing/merging when recalculating normals for Generated Mesh levels of detail. |
--recalculateLodNormalsSplitAngle <value> | Maximum angle in degrees to consider for normal spliting when recalculating normals for Generated Mesh levels of detail. |