2025年Balsam资产导入工具

大家好，我是讯享网，很高兴认识大家。

Balsam Asset Import Tool

Balsam资产导入工具

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.

Balsam工具是一个命令行应用程序，是Qt Quick 3D资产调节管道的一部分。其目的是获取在数字内容创建工具（如Maya、3ds Max或Blender）中创建的资源，并将其转换为有效的运行时格式，以便与Qt Quick 3D一起使用。在应用程序中直接引用交换格式是不可能的，也没有意义的，因为需要大量资源来解析和调整资产的内容，然后才能将其用于实时呈现。相反，交换格式可以通过Balsam工具转换为QML组件和资源，如几何体和纹理。

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:

转换文件testModel.fbx中包含的三维资源，将使用以下命令：

讯享网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:

然后可以通过使用QML组件在Qt Quick 3D项目中使用：

import QtQuick3D TestModel { id: modelInstance }

Supported 3D Asset Types

支持的3D资产类型

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.

支持的某些格式还允许嵌入或引用纹理资源。这些资产也受到支持，前提是Qt也支持它们。

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.

Balsam还支持从.hdr文件生成预过滤的立方体映射图像。将扩展名为.hdr的文件指定为输入会生成一个名称相同但扩展名为.ktx的文件。然后，应用程序可以发送生成的.ktx文件，并从与SceneEnvironment::lightProbe关联的纹理中引用该文件。这避免了基于图像的照明所需的昂贵的运行时处理。有关详细信息，请参见预生成IBL立方体映射。

Supported Options

支持的选项

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

下表列出了balsam在转换资产文件时识别的命令行选项：

Note: For each boolean option it is possible to use --disable-<option-name>

注意：对于每个布尔选项，可以使用--disable-＜选项名称＞

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. 讯享网此步骤将搜索所有网格中的无效数据，如归零的法向量或无效的UV坐标，并删除/修复它们。这是为了消除一些常见的导出器错误。
`--transformUVCoordinates`	This step applies per-texture UV transformations and bakes them into stand-alone texture coordinate channels. 此步骤应用每纹理UV变换并将其烘焙到独立纹理坐标通道中。
`--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. 将联合索引存储为GLES 2.0的浮点数。
`--globalScale`	This step will perform a global scale of the model. 此步骤将执行模型的全局缩放。
`--globalScaleValue <value>`	Global Scale factor used by `--globalScale`. --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. 从网格中删除任何UV组件。
`--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) 保留由FBX资源创建的额外轴节点（可以创建深度节点层次）
`--generateMipMaps`	Force all imported texture components to generate mip maps for mip map texture filtering 强制所有导入的纹理组件生成用于mip贴图纹理过滤的mip贴图
`--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.

© 2022 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.