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.

Supported Options

The following table lists the command-line options recognized by balsam when converting asset files: