1// Copyright (C) 2019 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qtquick3d-tool-balsam.html
6\title Balsam Asset Import Tool
7\brief Command line tool for importing assets for use with Qt Quick 3D
9The Balsam tool is a command line application that is part of Qt Quick 3D's
10asset conditioning pipeline. The purpose is to take assets created in digital
11content creation tools like
12\l{https://www.autodesk.com/products/maya/overview}{Maya},
13\l{https://www.autodesk.com/products/3ds-max/overview}{3ds Max}, or
14\l{https://www.blender.org/}{Blender} and convert them into an efficient runtime
15format for use with Qt Quick 3D. It is not possible, nor does it make sense to
16reference the interchange formats directly in applications because a large amount
17of resources are needed to parse and condition the content of the asset before it
18is usable for realtime rendering. Instead the interchange formats can be
19converted via the Balsam tool into QML Components and resources like geometry and
24balsam [options] sourceFilename
27\section1 Example Usage
29To convert a 3D asset contained in the file \c testModel.fbx with \c balsam
30the following command would be used:
36This would generate the following files:
38 \li \c meshes/testModel.mesh
42Which can then be used in a Qt Quick 3D project by using that QML Component:
51\section1 Supported 3D Asset Types
59 \li GLTF2 (.gltf, .glb)
62Some of the formats supported also allow for either embedding or referencing of
63texture assets. These assets are also supported, provided Qt also has support
66\section1 Baking for Image-Based Lighting
68Balsam also supports generating a pre-filtered cubemap image from .hdr
69files. Specifying a file with .hdr extension as the input results in generating
70a file with the same name but with an extension of .ktx. The application can
71then ship the resulting .ktx file and reference that from the \l Texture
72associated with \l SceneEnvironment::lightProbe. This avoids the costly runtime
73processing that is necessary for image-based lighting. See \l{Pre-generating IBL
74cubemap} for more details.
76\section1 Supported Options
78The following table lists the command-line options recognized by \c balsam when
79converting asset files:
81\note For each boolean option it is possible to use \c{--disable-<option-name>}.
84\header \li Option \li Description
85\row \li \c {--outputPath, -o <outputPath>} \li Sets the location to place the
86generated file(s). Default is the current directory.
87\row \li \c {--calculateTangentSpace} \li Calculates the tangents and
88bitangents for the imported meshes.
89\row \li \c {--joinIdenticalVertices} \li Identifies and joins identical vertex
90 data sets within all imported meshes.
91\row \li \c {--generateNormals} \li Generates normals for all faces of all
93\row \li \c {--generateSmoothNormals} \li Generates smooth normals for all
95\row \li \c {--splitLargeMeshes} \li Splits large meshes into smaller
97\row \li \c {--preTransformVertices} \li Removes the node graph and
98pre-transforms all vertices with the local transformation matrices of
100\row \li \c {--improveCacheLocality} \li Reorders triangles for better vertex
102\row \li \c {--removeRedundantMaterials} \li Searches for
103redundant/unreferenced materials and removes them.
104\row \li \c {--fixInfacingNormals} \li Tries to determine which meshes have
105normal vectors that are facing inwards and inverts them.
106\row \li \c {--findDegenerates} \li This step searches all meshes for
107degenerate primitives and converts them to proper lines or points.
108\row \li \c {--findInvalidData} \li This step searches all meshes for invalid
109data, such as zeroed normal vectors or invalid UV coords and removes/fixes
110them. This is intended to get rid of some common exporter errors.
111\row \li \c {--transformUVCoordinates} \li This step applies per-texture UV
112transformations and bakes them into stand-alone texture coordinate channels.
113\row \li \c {--findInstances} \li This step searches for duplicate meshes and
114replaces them with references to the first mesh.
115\row \li \c {--optimizeMeshes} \li A postprocessing step to reduce the number
117\row \li \c {--optimizeGraph} \li A postprocessing step to optimize the scene
119\row \li \c {--useFloatJointIndices} \li Stores joint indices as floating point
121\row \li \c {--globalScale} \li This step will perform a global scale of the
123\row \li \c {--globalScaleValue <value>} \li Global Scale factor used by
125\row \li \c {--dropNormals} \li Drops normals for all faces of all meshes.
126\row \li \c {--removeComponentNormals} \li Removes Normal component from
128\row \li \c {--removeComponentTangentsAndBitangents} \li Removes Tangents and
129Bitangents components from meshes.
130\row \li \c {--removeComponentColors} \li Removes any Color components from
132\row \li \c {--removeComponentUVs} \li Removes any UV components from meshes.
133\row \li \c {--removeComponentBoneWeights} \li Removes any bone weights from
135\row \li \c {--removeComponentAnimations} \li Removes any animation components
137\row \li \c {--removeComponentTextures} \li Removes any embedded texture
138components from meshes.
139\row \li \c {--fbxPreservePivots} \li Preserves extra pivot nodes created by
140FBX assets (can create deep node hierarchies)
141\row \li \c {--generateMipMaps} \li Force all imported texture components to
142generate mip maps for mip map texture filtering
143\row \li \c {--useBinaryKeyframes} \li Record keyframe data as binary files
145\row \li \c {--generateLightmapUV} \li Perform lightmap UV unwrapping and
146generate an additional UV channel for the meshes. This UV data is then used by
147the \l{Lightmaps and Global Illumination}{lightmap baker and during run-time
150\row \li \c {--generateMeshLevelsOfDetail} \li When possible create mesh Levels
151of Detail by automatically simplifying the source mesh.
153\row \li \c {--recalculateLodNormals} \li Calculate new normals when necessary
154for Generated Mesh levels of detail.
156\row \li \c {--recalculateLodNormalsMergeAngle <value>} \li Maximum angle in
157degrees to consider for normal smoothing/merging when recalculating normals
158for Generated Mesh levels of detail.
160\row \li \c {--recalculateLodNormalsSplitAngle <value>} \li Maximum angle in
161degrees to consider for normal spliting when recalculating normals for
162Generated Mesh levels of detail.