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:

要使用balsam转换文件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

支持的三维资产类型

• 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.

支持的某些格式还允许嵌入或引用纹理资源。这些资产也得到了支持，前提是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-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. 此步骤在所有网格中搜索无效数据，例如归零的法线矢量或无效的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. ​执行光照贴图UV展开并为网格生成额外的UV通道。然后，光照贴图烘焙器和运行时光照贴图过程中会使用此UV数据。​
--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. 重新计算“生成的网格”详细级别的法线时，法线拆分要考虑的最大角度（以度为单位）。

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