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.mesh
  • TestModel.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)
  • 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.

Support for Qt 3D Studio Projects

The Balsam tool also has support for converting projects created with Qt 3D Studio into Qt Quick 3D QML projects.

  • Qt 3D Studio Application (.uia)
  • Qt 3D Studio Presentation (.uip)

The conversion of Qt 3D Studio projects does have some limitations due to differences in features available. Features such as Effects and CustomMaterials are not available and will not be generated. There is also some differences in how Animations are implemented, so there can be differences in behavior on conversion. The conversion process will not be 100% and it is expected that some adjustments will be necessary, but should ease the porting process for existing projects.

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>

OptionDescription
--outputPath, -o <outputPath>Sets the location to place the generated file(s). Default is the current directory.
--calculateTangentSpaceCalculates the tangents and bitangents for the imported meshes.
--joinIdenticalVerticesIdentifies and joins identical vertex data sets within all imported meshes.
--generateNormalsGenerates normals for all faces of all meshes.
--generateSmoothNormalsGenerates smooth normals for all vertices in the mesh.
--splitLargeMeshesSplits large meshes into smaller sub-meshes.
--preTransformVerticesRemoves the node graph and pre-transforms all vertices with the local transformation matrices of their nodes.
--improveCacheLocalityReorders triangles for better vertex cache locality.
--removeRedundantMaterialsSearches for redundant/unreferenced materials and removes them.
--fixInfacingNormalsTries to determine which meshes have normal vectors that are facing inwards and inverts them.
--findDegeneratesThis step searches all meshes for degenerate primitives and converts them to proper lines or points.
--findInvalidDataThis 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.
--transformUVCoordinatesThis step applies per-texture UV transformations and bakes them into stand-alone texture coordinate channels.
--findInstancesThis step searches for duplicate meshes and replaces them with references to the first mesh.
--optimizeMeshesA postprocessing step to reduce the number of meshes.
--optimizeGraphA postprocessing step to optimize the scene hierarchy.
--useFloatJointIndicesStores joint indices as floating point numbers for GLES 2.0.
--globalScaleThis step will perform a global scale of the model.
--globalScaleValue <value>Global Scale factor used by --globalScale.
--dropNormalsDrops normals for all faces of all meshes.
--removeComponentNormalsRemoves Normal component from meshes.
--removeComponentTangentsAndBitangentsRemoves Tangents and Bitangents components from meshes.
--removeComponentColorsRemoves any Color components from meshes.
--removeComponentUVsRemoves any UV components from meshes.
--removeComponentBoneWeightsRemoves any bone weights from meshes.
--removeComponentAnimationsRemoves any animation components from meshes.
--removeComponentTexturesRemoves any embedded texture components from meshes.
--fbxPreservePivotsPreserves extra pivot nodes created by FBX assets (can create deep node hierarchies)
--generateMipMapsForce all imported texture components to generate mip maps for mip map texture filtering
--useBinaryKeyframesRecord keyframe data as binary files

The following table lists the command-line options recognized by balsam when converting Qt 3D Studio projects:

OptionDescription
--createProjectWrapperCreates a wrapper Window component for the imported UIA project. Only valid for UIA imports.
--createIndividualLayersCreates an individual component for each layer instead of including layer contents in presentation components.
--framesPerSecond <value>Specifies how many animation frames are created per second in animations.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.