Herramienta de importación de activos Balsam
La herramienta Balsam es una aplicación que forma parte de la tubería de acondicionamiento de activos de Qt Quick 3D. El propósito es tomar activos creados en herramientas de creación de contenido digital como Maya, 3ds Max o Blender y convertirlos en un formato de ejecución eficiente para su uso con Qt Quick 3D. No es posible, ni tiene sentido, hacer referencia a los formatos de intercambio directamente en las aplicaciones porque se necesita una gran cantidad de recursos para analizar y acondicionar el contenido del activo antes de que sea utilizable para el renderizado en tiempo real. En su lugar, los formatos de intercambio pueden convertirse mediante la herramienta Balsam en componentes QML y recursos como geometría y texturas.
Herramienta de línea de comandos Balsam
Para ejecutar Balsam a través de la línea de comandos, llame al ejecutable balsam de la siguiente manera:
balsam [options] sourceFilename
Para convertir un activo 3D contenido en el archivo testModel.fbx con balsam se utilizaría el siguiente comando:
balsam testModel.fbxEsto generaría los siguientes archivos:
meshes/testModel.meshTestModel.qml
Que luego pueden ser utilizados en un proyecto 3D Qt Quick utilizando ese Componente QML:
import QtQuick3D
TestModel {
id: modelInstance
}Nota: El nombre del archivo de malla generado depende del nombre o nombres de malla definidos en el archivo fuente (en este ejemplo, el archivo FBX) y puede diferir de testModel.mesh.
Interfaz de usuario de Balsam
También existe una interfaz gráfica de usuario para Balsam llamada balsamui que se suministra junto con el ejecutable balsam. En balsamui puede seleccionar los archivos de entrada y el directorio de salida, y las opciones de línea de comandos del ejecutable balsam se asignan a elementos interactivos:
Tipos de activos 3D compatibles
- Wavefront (.obj)
- COLLADA (.dae)
- FBX (.fbx)
- STL (.stl)
- PLY (.ply)
- GLTF2 (.gltf, .glb)
Algunos de los formatos admitidos también permiten incrustar o referenciar activos de textura. Estos activos también se admiten, siempre que Qt también tenga soporte para ellos.
Generación de iluminación basada en imágenes
Balsam también permite generar una imagen cubemap prefiltrada a partir de archivos .hdr. Especificando un archivo con extensión .hdr como entrada se genera un archivo con el mismo nombre pero con extensión .ktx. La aplicación puede entonces enviar el archivo .ktx resultante y referenciarlo desde la página Texture asociada a SceneEnvironment::lightProbe. Esto evita el costoso procesamiento en tiempo de ejecución que es necesario para la iluminación basada en imágenes. Ver Pre-generating IBL cubemap para más detalles.
Opciones admitidas
La siguiente tabla enumera las opciones de línea de comandos reconocidas por balsam al convertir archivos de activos:
Nota: Para cada opción booleana es posible utilizar --disable-<option-name>.
| Opción | Descripción |
|---|---|
--outputPath, -o <outputPath> | Establece la ubicación en la que se colocarán los archivos generados. Por defecto es el directorio actual. |
--calculateTangentSpace | Calcula las tangentes y bitangentes de las mallas importadas. |
--joinIdenticalVertices | Identifica y une conjuntos de datos de vértices idénticos en todas las mallas importadas. |
--generateNormals | Genera normales para todas las caras de todas las mallas. |
--generateSmoothNormals | Genera normales suaves para todos los vértices de la malla. |
--splitLargeMeshes | Divide las mallas grandes en submallas más pequeñas. |
--preTransformVertices | Elimina el gráfico de nodos y pretransforma todos los vértices con las matrices de transformación locales de sus nodos. |
--improveCacheLocality | Reordena los triángulos para mejorar la localización de los vértices en la caché. |
--removeRedundantMaterials | Busca materiales redundantes/no referenciados y los elimina. |
--fixInfacingNormals | Intenta determinar qué mallas tienen vectores normales orientados hacia dentro y los invierte. |
--findDegenerates | Este paso busca primitivas degeneradas en todas las mallas y las convierte en líneas o puntos adecuados. |
--findInvalidData | Este paso busca en todas las mallas datos no válidos, como vectores normales a cero o coordenadas UV no válidas, y los elimina o corrige. El objetivo es eliminar algunos errores comunes del exportador. |
--transformUVCoordinates | Este paso aplica transformaciones UV por textura y las convierte en canales de coordenadas de textura independientes. |
--findInstances | Este paso busca mallas duplicadas y las sustituye por referencias a la primera malla. |
--optimizeMeshes | Un paso de postprocesado para reducir el número de mallas. |
--optimizeGraph | Un paso de postprocesado para optimizar la jerarquía de la escena. |
--useFloatJointIndices | Almacena los índices de juntas como números de coma flotante para GLES 2.0. |
--globalScale | Este paso realizará una escala global del modelo. |
--globalScaleValue <value> | Factor de escala global utilizado por --globalScale. |
--dropNormals | Elimina las normales de todas las caras de todas las mallas. |
--removeComponentNormals | Elimina la componente Normal de las mallas. |
--removeComponentTangentsAndBitangents | Elimina los componentes Tangentes y Bitangentes de las mallas. |
--removeComponentColors | Elimina los componentes de Color de las mallas. |
--removeComponentUVs | Elimina los componentes UV de las mallas. |
--removeComponentBoneWeights | Elimina los pesos óseos de las mallas. |
--removeComponentAnimations | Elimina los componentes de animación de las mallas. |
--removeComponentTextures | Elimina los componentes de textura incrustados de las mallas. |
--fbxPreservePivots | Conserva los nodos pivotantes adicionales creados por los activos FBX (puede crear jerarquías de nodos profundas). |
--generateMipMaps | Fuerza a todos los componentes de textura importados a generar mapas mip para el filtrado de texturas de mapas mip. |
--useBinaryKeyframes | Graba datos de fotogramas clave como archivos binarios |
--generateLightmapUV | Realiza el desenvolvimiento UV del lightmap y genera un canal UV adicional para las mallas. Estos datos UV son utilizados por el lightmap baker y durante la ejecución del lightmapping. |
--generateMeshLevelsOfDetail | Cuando sea posible, crear niveles de detalle de malla simplificando automáticamente la malla de origen. |
--recalculateLodNormals | Calcular nuevas normales cuando sea necesario para los niveles de detalle de la malla generada. |
--recalculateLodNormalsMergeAngle <value> | Ángulo máximo en grados a considerar para el suavizado/fusión de normales al recalcular las normales para los niveles de detalle de la malla generada. |
--recalculateLodNormalsSplitAngle <value> | Ángulo máximo en grados a considerar para la división de normales al recalcular las normales para los niveles de detalle de la malla generada. |
© 2026 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.
