バルサムアセットインポートツール
Balsamツールは、Qt Quick 3Dのアセットコンディショニングパイプラインの一部であるコマンドラインアプリケーションです。その目的は、Maya、3ds Max、Blenderのようなデジタルコンテンツ作成ツールで作成されたアセットを、Qt Quick 3Dで使用するための効率的なランタイムフォーマットに変換することです。アセットがリアルタイムレンダリングに使用できるようになる前に、アセットコンテンツを解析し、コンディショニングするために大量のリソースが必要となるため、アプリケーションでインターチェンジフォーマットを直接参照することは不可能であり、意味がありません。その代わりに、Balsamツールを使って、交換フォーマットをQMLコンポーネントや、ジオメトリやテクスチャなどのリソースに変換することができます。
使用方法
balsam [options] sourceFilename
使用例
ファイルtestModel.fbx
に含まれる 3D アセットをbalsam
で変換するには、次のコマンドを使用します:
balsam testModel.fbx
以下のファイルが生成されます:
meshes/testModel.mesh
TestModel.qml
QMLコンポーネントを使用することで、Qt Quick 3Dプロジェクトで使用することができます:
import QtQuick3D TestModel { id: modelInstance }
サポートされる3Dアセットタイプ
- Wavefront (.obj)
- COLLADA (.dae)
- FBX (.fbx)
- STL (.stl)
- PLY (.ply)
- GLTF2 (.gltf, .glb)
サポートされているフォーマットのいくつかは、テクスチャ アセットの埋め込みまたは参照も可能です。これらのアセットも、Qtがサポートしていればサポートされます。
画像ベースの照明のベイク
バルサムは、.hdr ファイルからフィルタリング済みのキューブマップ画像を生成することもサポートしています。.hdr拡張子のファイルを入力として指定すると、同じ名前で拡張子が.ktxのファイルが生成されます。アプリケーションは、生成された .ktx ファイルを出荷し、SceneEnvironment::lightProbe に関連付けられたTexture から参照することができます。これにより、画像ベースのライティングに必要なコストのかかるランタイム処理を回避できます。詳細はIBLキューブマップの事前生成を参照してください。
サポートされるオプション
次の表は、アセットファイルの変換時にbalsam
で認識されるコマンドラインオプションの一覧です:
注: 各ブーリアンオプションに対して、--disable-<option-name>
を使用することができます。
オプション | 説明 |
---|---|
--outputPath, -o <outputPath> | 生成されたファイルを置く場所を設定します。デフォルトはカレントディレクトリです。 |
--calculateTangentSpace | インポートしたメッシュの接線とビット接線を計算します。 |
--joinIdenticalVertices | インポートされたすべてのメッシュ内の同一の頂点データセットを特定し、結合します。 |
--generateNormals | すべてのメッシュのすべての面の法線を生成します。 |
--generateSmoothNormals | メッシュ内のすべての頂点に対して滑らかな法線を生成します。 |
--splitLargeMeshes | 大きなメッシュを小さなサブメッシュに分割します。 |
--preTransformVertices | ノードグラフを削除し、ノードのローカル変換行列ですべての頂点を事前変換します。 |
--improveCacheLocality | 頂点キャッシュの局所性を高めるために三角形を並べ替えます。 |
--removeRedundantMaterials | 冗長な/参照されていないマテリアルを検索し、それらを削除します。 |
--fixInfacingNormals | 法線ベクトルが内側を向いているメッシュを特定し、それを反転します。 |
--findDegenerates | すべてのメッシュで縮退プリミティブを検索し、適切な線または点に変換します。 |
--findInvalidData | このステップは、法線ベクトルがゼロになっていたり、無効なUV座標などの無効なデータがないかすべてのメッシュを検索し、それらを削除/修正します。これは、いくつかの一般的なエクスポーターエラーを取り除くことを目的としています。 |
--transformUVCoordinates | このステップは、テクスチャごとの UV 変換を適用し、それらをスタンドアロンのテクスチャ座標チャンネルにベイクします。 |
--findInstances | 重複メッシュを検索し、最初のメッシュへの参照に置き換えます。 |
--optimizeMeshes | メッシュ数を減らす後処理ステップ。 |
--optimizeGraph | シーン階層を最適化する後処理ステップ。 |
--useFloatJointIndices | GLES 2.0用の浮動小数点数としてジョイントインデックスを格納します。 |
--globalScale | このステップはモデルのグローバルスケールを実行します。 |
--globalScaleValue <value> | --globalScale で使用されるグローバルスケール係数。 |
--dropNormals | すべてのメッシュのすべての面の法線を削除します。 |
--removeComponentNormals | メッシュから法線成分を削除します。 |
--removeComponentTangentsAndBitangents | メッシュからタンジェントとビタンジェントのコンポーネントを削除します。 |
--removeComponentColors | メッシュからカラーコンポーネントを削除します。 |
--removeComponentUVs | メッシュからUVコンポーネントを削除します。 |
--removeComponentBoneWeights | メッシュからボーンウェイトを削除します。 |
--removeComponentAnimations | メッシュからアニメーション コンポーネントを削除します。 |
--removeComponentTextures | メッシュから埋め込まれたテクスチャ コンポーネントを削除します。 |
--fbxPreservePivots | FBXアセットによって作成された余分なピボットノードを保持します(深いノード階層を作成できます)。 |
--generateMipMaps | インポートされたすべてのテクスチャコンポーネントが、ミップマップテクスチャフィルタリングのためにミップマップを生成するように強制します。 |
--useBinaryKeyframes | キーフレームデータをバイナリファイルとして記録 |
--generateLightmapUV | ライトマップUVアンラッピングを実行し、メッシュ用に追加のUVチャンネルを生成。このUVデータは、ライトマップベーカーとランタイムライトマッピングで使用されます。 |
--generateMeshLevelsOfDetail | 可能であれば、ソースメッシュを自動的に簡略化してメッシュの詳細レベルを作成します。 |
--recalculateLodNormals | 生成されたメッシュの詳細レベルに対して、必要に応じて新しい法線を計算します。 |
--recalculateLodNormalsMergeAngle <value> | 生成されたメッシュの詳細レベルの法線を再計算する際に、法線のスムージング/マージに考慮する最大角度を度単位で指定します。 |
--recalculateLodNormalsSplitAngle <value> | 生成されたメッシュの詳細レベルの法線を再計算する際に、法線の分割を考慮する最大角度を度単位で指定します。 |
© 2025 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.