Carregando modelos 3D

Os modelos 3D estão disponíveis em centenas de formatos de arquivo, cada um com diferentes propósitos, recursos variados e complexidade variável. Embora o three.js forneça muitos loaders, escolher o formato e o fluxo de trabalho certos economizará tempo e frustração mais tarde. Alguns formatos são difíceis de trabalhar, ineficientes para experiências em tempo real ou simplesmente não são totalmente suportados por enquanto.

Este guia fornece um fluxo de trabalho recomendado para a maioria dos usuários e sugestões do que tentar se as coisas não correrem como o esperado.

Antes de começar

Se você é iniciante na execução de um servidor local, comece com [link:#manual/introduction/How-to-run-things-locally Como executar localmente] primeiro. Muitos erros comuns de visualização de modelos 3D podem ser evitados hospedando arquivos corretamente.

Fluxo de trabalho recomendado

Sempre que possível, recomendamos o uso do glTF (GL Transmission Format). Ambas versões do formato, .GLB e .GLTF, são bem suportadas. Como o glTF está focado na entrega de recursos em tempo de execução, ele é compacto para transmitir e rápido para carregar. Seus recursos incluem meshs, materiais, texturas, skins, skeletons, morph targets, animações, luzes e câmeras.

Os arquivos glTF de domínio público estão disponíveis em sites como Sketchfab, ou várias ferramentas que incluem exportação glTF:

Blender da Blender Foundation
Substance Painter da Allegorithmic
Modo da Foundry
Toolbag da Marmoset
Houdini da SideFX
Cinema 4D da MAXON
COLLADA2GLTF do Khronos Group
FBX2GLTF do Facebook
OBJ2GLTF da Analytical Graphics Inc
…e muito mais

Se suas ferramentas preferidas não suportam glTF, considere solicitar exportação de glTF para os autores, ou postar no glTF roadmap thread.

Quando o glTF não é uma opção, formatos populares como FBX, OBJ ou COLLADA também estão disponíveis e são mantidos regularmente.

Carregando

Apenas alguns poucos loaders (por exemplo [page:ObjectLoader]) são incluídos por padrão com o three.js — outros devem ser adicionados ao seu aplicativo individualmente.


		import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

Depois de importar um loader você está pronto para adicionar um modelo à sua cena. A sintaxe varia entre loaders diferentes — ao usar outro formato, verifique os exemplos e a documentação para esse loader. Para glTF, o uso com scripts globais ficaria:


		const loader = new GLTFLoader();

		loader.load( 'path/to/model.glb', function ( gltf ) {

			scene.add( gltf.scene );

		}, undefined, function ( error ) {

			console.error( error );

		} );

Veja a documentação [page:GLTFLoader GLTFLoader] para mais detalhes.

Solução de problemas

Você passou horas modelando uma obra-prima artesanal, você a carrega em uma página web e — ah, não! 😭 Está distorcido, descolorido ou totalmente ausente. Comece com estas etapas de solução de problemas:

Verifique se há erros no console JavaScript e certifique-se de ter usado um callback `onError` ao chamar `.load()` para logar o resultado.
Visualize o modelo em outro aplicativo. Para glTF, visualizadores drag-and-drop estão disponíveis para three.js e babylon.js. Se o modelo aparece corretamente em um ou mais aplicativos, registre um bug do three.js. Se o modelo não puder ser mostrado em nenhum aplicativo, recomendamos registrar um bug com o aplicativo usado para criar o modelo.
Tente dimensionar o modelo para cima ou para baixo por um fator de 1.000. Muitos modelos são dimensionados de forma diferente, e modelos grandes podem não aparecer se a câmera estiver dentro do modelo.
Tente adicionar e posicionar uma fonte de luz. O modelo pode estar escondido no escuro.
Procure requisições de textura com falha na aba network, como `"C:\\Path\To\Model\texture.jpg"`. Use caminhos relativos ao seu modelo em vez disso, tal como `images/texture.jpg` — isso pode exigir edição do arquivo de modelo em um editor de texto.

Pedindo ajuda

Se você passou pelo processo de solução de problemas acima e seu modelo ainda não está funcionando, uma abordagem correta para pedir ajuda fará com que você tenha uma solução mais rápida. Poste uma pergunta no fórum three.js e, sempre que possível, inclua seu modelo (ou um modelo mais simples com o mesmo problema) em qualquer formato que você tiver disponível. Inclua informações suficientes para outra pessoa reproduzir o problema rapidamente - idealmente, uma demonstração ao vivo.