Инструмент импорта активов Balsam

Инструмент Balsam — это командная строка приложения, являющаяся частью конвейера подготовки активов Qt Quick 3D. Его предназначение — принимать активы, созданные в инструментах создания цифрового контента, таких как Maya, 3ds Max или Blender, и преобразовывать их в эффективный формат выполнения для использования с Qt Quick 3D. Невозможно, и это не имеет смысла, напрямую ссылаться на форматы обмена в приложениях, потому что для разбора и подготовки содержимого актива перед его использованием для рендеринга в реальном времени требуется большое количество ресурсов. Вместо этого форматы обмена могут быть преобразованы с помощью инструмента Balsam в компоненты QML и ресурсы, такие как геометрия и текстуры.

Использование:

balsam [options] sourceFilename

Пример использования

Для преобразования 3D актива, содержащегося в файле testModel.fbx с balsam будет использоваться следующая команда:

balsam testModel.fbx

Это сгенерирует следующие файлы:

meshes/testModel.mesh
TestModel.qml

которые затем можно использовать в проекте Qt Quick 3D, используя этот компонент QML:

import QtQuick3D

TestModel {
   id: modelInstance
}

Поддерживаемые типы 3D активов

Wavefront (.obj)
COLLADA (.dae)
FBX (.fbx)
STL (.stl)
GLTF2 (.gltf, .glb)

Некоторые из поддерживаемых форматов также позволяют встраивать или ссылаться на текстурные активы. Эти активы также поддерживаются, при условии, что Qt также поддерживает их.

Поддержка проектов 3D Studio

Инструмент Balsam также поддерживает преобразование проектов, созданных с помощью Qt 3D Studio, в проекты Qt Quick 3D QML.

Приложение Qt 3D Studio (.uia)
Презентация Qt 3D Studio (.uip)

Преобразование проектов Qt 3D Studio имеет некоторые ограничения из-за различий в доступных функциях. Функции, такие как Эффекты и CustomMaterials, недоступны и не будут сгенерированы. Также есть некоторые различия в реализации анимаций, поэтому при преобразовании могут быть различия в поведении. Процесс преобразования не будет на 100% и ожидается, что некоторые корректировки потребуются, но это должно облегчить процесс переноса существующих проектов.

Поддерживаемые параметры

В следующей таблице перечислены параметры командной строки, распознаваемые balsam при преобразовании файлов активов:

Примечание: Для каждого логического параметра можно использовать --disable-<имя_параметра>

Параметр	Описание
`--outputPath, -o <outputPath>`	Устанавливает расположение для размещения сгенерированного файла(ов). По умолчанию — текущий каталог.
`--calculateTangentSpace`	Вычисляет касательные и бинормали для импортированных мешей.
`--joinIdenticalVertices`	Идентифицирует и объединяет идентичные наборы данных вершин внутри всех импортированных мешей.
`--generateNormals`	Генерирует нормали для всех граней всех мешей.
`--generateSmoothNormals`	Генерирует гладкие нормали для всех вершин в меше.
`--splitLargeMeshes`	Разбивает большие меши на более мелкие подмеши.
`--preTransformVertices`	Удаляет граф узлов и предварительно преобразует все вершины с локальными матрицами преобразования их узлов.
`--limitBoneWeights`	Ограничивает количество костей, одновременно влияющих на одну вершину, максимальным значением (4).
`--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`	Принудительно генерирует mip-карты для всех импортированных текстур для фильтрации mip-текстур
`--useBinaryKeyframes`	Запись данных ключевых кадров в виде бинарных файлов

В следующей таблице перечислены параметры командной строки, распознаваемые balsam при преобразовании проектов Qt 3D Studio:

Параметр	Описание
`--createProjectWrapper`	Создаёт обёртку компонента окна для импортированного проекта UIA. Действителен только для импорта UIA.
`--createIndividualLayers`	Создаёт отдельный компонент для каждого слоя вместо включения содержимого слоя в компоненты представления.
`--framesPerSecond <value>`	Указывает, сколько кадров анимации создаётся в секунду в анимациях.

© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-6.0/qtquick3d-tool-balsam.html