En esta página

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] sourceFilename

Para convertir un recurso 3D contenido en el archivo testModel.fbx con balsam, se utilizaría el siguiente comando:

balsam testModel.fbx

Esto generaría los siguientes archivos:

  • meshes/testModel.mesh
  • TestModel.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:

Una captura de pantalla de la aplicación Balsam UI.

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ónDescripción
--outputPath, -o <outputPath>Establece la ubicación donde se guardarán los archivos generados. El valor por defecto es el directorio actual.
--calculateTangentSpaceCalcula las tangentes y las bitangentes de las mallas importadas.
--joinIdenticalVerticesIdentifica y une conjuntos de datos de vértices idénticos dentro de todas las mallas importadas.
--generateNormalsGenera normales para todas las caras de todas las mallas.
--generateSmoothNormalsGenera normales suaves para todos los vértices de la malla.
--splitLargeMeshesDivide las mallas grandes en submallas más pequeñas.
--preTransformVerticesElimina el grafo de nodos y transforma previamente todos los vértices con las matrices de transformación locales de sus nodos.
--improveCacheLocalityReordena los triángulos para mejorar la localidad de la caché de vértices.
--removeRedundantMaterialsBusca materiales redundantes o sin referencia y los elimina.
--fixInfacingNormalsIntenta determinar qué mallas tienen vectores normales orientados hacia el interior y los invierte.
--findDegeneratesEn este paso se buscan primitivas degeneradas en todas las mallas y se convierten en líneas o puntos correctos.
--findInvalidDataEn 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.
--transformUVCoordinatesEste paso aplica transformaciones UV por textura y las integra en canales de coordenadas de textura independientes.
--findInstancesEste paso busca mallas duplicadas y las sustituye por referencias a la primera malla.
--optimizeMeshesUn paso de posprocesamiento para reducir el número de mallas.
--optimizeGraphUn paso de posprocesamiento para optimizar la jerarquía de la escena.
--useFloatJointIndicesAlmacena los índices de las articulaciones como números de punto flotante para GLES 2.0.
--globalScaleEste paso aplicará una escala global al modelo.
--globalScaleValue <value>Factor de escala global utilizado por --globalScale.
--dropNormalsElimina las normales de todas las caras de todas las mallas.
--removeComponentNormalsElimina el componente normal de las mallas.
--removeComponentTangentsAndBitangentsElimina los componentes tangentes y bitangentes de las mallas.
--removeComponentColorsElimina cualquier componente de color de las mallas.
--removeComponentUVsElimina cualquier componente UV de las mallas.
--removeComponentBoneWeightsElimina cualquier peso de hueso de las mallas.
--removeComponentAnimationsElimina cualquier componente de animación de las mallas.
--removeComponentTexturesElimina cualquier componente de textura incrustada de las mallas.
--fbxPreservePivotsConserva los nodos de pivote adicionales creados por los recursos FBX (puede generar jerarquías de nodos profundas)
--generateMipMapsObliga a todos los componentes de textura importados a generar mapas mip para el filtrado de texturas mediante mapas mip
--useBinaryKeyframesRegistra los datos de fotogramas clave como archivos binarios.
--generateLightmapUVRealiza 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.
--generateMeshLevelsOfDetailSiempre que sea posible, crea niveles de detalle de las mallas simplificando automáticamente la malla de origen.
--recalculateLodNormalsCalcula 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.