Herramienta de importación de recursos Balsam
La herramienta Balsam es una aplicación que forma parte del proceso de acondicionamiento de recursos de « Qt Quick » 3D. Su objetivo es tomar los recursos creados en herramientas de creación de contenido digital como Maya, 3ds Max o Blender y convertirlos a 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, ya que se necesita una gran cantidad de recursos para analizar y acondicionar el contenido del activo antes de que pueda utilizarse 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 desde la línea de comandos, ejecuta el archivo ejecutable « balsam » de la siguiente manera:
balsam [options] sourceFilenamePara convertir un recurso 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 se pueden utilizar en un proyecto 3D de Qt Quick mediante ese componente QML:
import QtQuick3D
TestModel {
id: modelInstance
}Nota: El nombre del archivo de malla generado depende del nombre o nombres de las mallas definidos en el archivo de origen (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 incluye junto con el ejecutable balsam. En balsamui puedes seleccionar tus 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 recursos 3D compatibles
- Wavefront (.obj)
- COLLADA (.dae)
- FBX (.fbx)
- STL (.stl)
- PLY (.ply)
- GLTF2 (.gltf, .glb)
Algunos de los formatos compatibles también permiten incrustar o hacer referencia a recursos de texturas. Estos recursos también son compatibles, siempre que Qt también los admita.
Bakeado para iluminación basada en imágenes
Balsam también permite generar una imagen de mapa cúbico prefiltrada a partir de archivos .hdr. Al especificar un archivo con extensión .hdr como entrada, se genera un archivo con el mismo nombre pero con la extensión .ktx. A continuación, la aplicación puede incluir el archivo .ktx resultante y hacer referencia a él desde el archivo « Texture » asociado a « SceneEnvironment::lightProbe ». De este modo se evita el costoso procesamiento en tiempo de ejecución necesario para la iluminación basada en imágenes. Consulta «Pregeneración de cubemaps IBL » para obtener más detalles.
Opciones compatibles
La siguiente tabla enumera las opciones de línea de comandos que reconoce balsam al convertir archivos de recursos:
Nota: Para cada opción booleana es posible utilizar --disable-<option-name>.
| Opción | Descripción |
|---|---|
--outputPath, -o <outputPath> | Establece la ubicación donde se guardarán los archivos generados. El valor por defecto es el directorio actual. |
--calculateTangentSpace | Calcula las tangentes y las bitangentes de las mallas importadas. |
--joinIdenticalVertices | Identifica y une conjuntos de datos de vértices idénticos dentro de 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 grafo de nodos y transforma previamente todos los vértices con las matrices de transformación locales de sus nodos. |
--improveCacheLocality | Reordena los triángulos para mejorar la localidad de la caché de vértices. |
--removeRedundantMaterials | Busca materiales redundantes o sin referencia y los elimina. |
--fixInfacingNormals | Intenta determinar qué mallas tienen vectores normales orientados hacia el interior y los invierte. |
--findDegenerates | En este paso se buscan primitivas degeneradas en todas las mallas y se convierten en líneas o puntos correctos. |
--findInvalidData | En este paso se buscan en todas las mallas datos no válidos, como vectores normales con valor cero o coordenadas UV no válidas, y se eliminan o corrigen. El objetivo es eliminar algunos errores comunes del exportador. |
--transformUVCoordinates | Este paso aplica transformaciones UV por textura y las integra 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 posprocesamiento para reducir el número de mallas. |
--optimizeGraph | Un paso de posprocesamiento para optimizar la jerarquía de la escena. |
--useFloatJointIndices | Almacena los índices de las articulaciones como números de punto flotante para GLES 2.0. |
--globalScale | Este paso aplicará una escala global al modelo. |
--globalScaleValue <value> | Factor de escala global utilizado por --globalScale. |
--dropNormals | Elimina las normales de todas las caras de todas las mallas. |
--removeComponentNormals | Elimina el componente normal de las mallas. |
--removeComponentTangentsAndBitangents | Elimina los componentes tangentes y bitangentes de las mallas. |
--removeComponentColors | Elimina cualquier componente de color de las mallas. |
--removeComponentUVs | Elimina cualquier componente UV de las mallas. |
--removeComponentBoneWeights | Elimina cualquier peso de hueso de las mallas. |
--removeComponentAnimations | Elimina cualquier componente de animación de las mallas. |
--removeComponentTextures | Elimina cualquier componente de textura incrustada de las mallas. |
--fbxPreservePivots | Conserva los nodos de pivote adicionales creados por los recursos FBX (puede generar jerarquías de nodos profundas) |
--generateMipMaps | Obliga a todos los componentes de textura importados a generar mapas mip para el filtrado de texturas mediante mapas mip |
--useBinaryKeyframes | Registra los datos de fotogramas clave como archivos binarios. |
--generateLightmapUV | Realiza el desenrollado UV de los mapas de luz y genera un canal UV adicional para las mallas. Estos datos UV son utilizados posteriormente por el generador de mapas de luz y durante el mapeado de luz en tiempo de ejecución. |
--generateMeshLevelsOfDetail | Siempre que sea posible, crea niveles de detalle de las mallas simplificando automáticamente la malla de origen. |
--recalculateLodNormals | Calcula nuevas normales cuando sea necesario para los niveles de detalle de las mallas generadas. |
--recalculateLodNormalsMergeAngle <value> | Ángulo máximo en grados que se debe tener en cuenta para el suavizado o la fusión de normales al recalcular las normales para los niveles de detalle de las mallas generadas. |
--recalculateLodNormalsSplitAngle <value> | Ángulo máximo en grados a tener en cuenta para la división de normales al recalcular las normales de los niveles de detalle de malla generados. |
© 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.