model-viewer: 3D interativo na web

Quando usar o model-viewer

<model-viewer> é um componente HTML para mostrar modelos glTF/GLB. Dá-te carregamento, câmara orbital, iluminação, animações, anotações e um caminho para AR sem montares um motor 3D completo.

O GLB é uma forma de empacotar um modelo glTF. O mesmo componente também aceita um ficheiro .gltf com recursos associados. Em ambos os casos, as animações têm de vir no asset: o componente apresenta-as, mas não as cria.

A primeira página 3D

Descarrega o RobotExpressive.glb (CC0 1.0), guarda-o ao lado de index.html e cria exemplo.css. Este primeiro exemplo funciona sem precisares de criar um modelo. Serve o projeto por HTTP local ou publica-o; abrir diretamente com file:// pode bloquear o carregamento dos ficheiros.

Para abrir esta apostila localmente, inicia o servidor na pasta vercelUniana, que contém playbooks e models:

python3 -m http.server 8000
# Abre http://localhost:8000/playbooks/apostila-model-viewer.html

<!doctype html>
<html lang="pt-PT">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>O meu personagem 3D</title>
  <script type="module"
    src="https://cdn.jsdelivr.net/npm/@google/model-viewer@4.4.0/dist/model-viewer.min.js"></script>
  <link rel="stylesheet" href="exemplo.css">
</head>
<body>
  <h1>Conhece o personagem</h1>
  <model-viewer src="RobotExpressive.glb"
    alt="Robô 3D branco e laranja que pode ser rodado"
    camera-controls touch-action="pan-y" loading="eager">
  </model-viewer>
</body>
</html>

model-viewer {
  display: block;
  width: 100%;
  height: 480px;
  background: #edf4ee;
}

Para testar este exemplo separado, guarda index.html, exemplo.css e RobotExpressive.glb na mesma pasta. Inicia o servidor nessa pasta e abre http://localhost:8000/. Se a porta 8000 já estiver ocupada pela apostila, encerra aquele servidor antes de iniciar outro.

src aponta para o modelo; alt descreve-o; camera-controls permite rodar e ampliar; touch-action="pan-y" ajuda a manter o scroll vertical no telemóvel. A altura em CSS é essencial: sem espaço visível, o modelo não aparece como esperado.

Quatro modelos para comparar

Os botões no percurso visual trocam o modelo sem recarregar a página. O GLB escolhido só é transferido quando o selecionas; o abacate, mais pesado, permite observar a diferença numa ligação móvel. As setas percorrem as animações disponíveis. Um modelo sem animações continua a poder ser rodado, mas os controlos de reprodução ficam inativos.

Na versão fornecida, hero.glb usa 29 materiais. Isso não impede a visualização na página, mas ultrapassa a referência de 10 materiais recomendada pelo Scene Viewer para AR no Android. Testa o resultado no telemóvel antes de decidir se precisas de simplificar o asset.

Formatos: GLB, glTF e recursos de AR

O atributo src aceita modelos glTF 2.0 em dois formatos: .glb e .gltf. Escolhe GLB para começar, porque costuma ser mais simples de transportar. Um .gltf é um ficheiro JSON que pode apontar para ficheiros .bin e texturas; publica esses recursos mantendo os caminhos relativos. Um GLB também pode, em certos casos, referenciar recursos externos, por isso verifica sempre o resultado exportado.

<model-viewer src="assets/personagem.gltf"
  alt="Personagem 3D que pode ser rodado"
  camera-controls touch-action="pan-y">
</model-viewer>

Se personagem.gltf apontar para personagem.bin e texturas/cor.png, publica os três caminhos. Mudar apenas o nome da extensão de um FBX ou OBJ para .gltf não converte o ficheiro.

“Extensões” também pode significar recursos opcionais dentro de um glTF: Draco comprime geometria, KTX2 comprime texturas e Meshopt é outra opção de compressão. O model-viewer suporta esses casos, mas o Meshopt exige configurar o descodificador. Testa a compatibilidade do asset depois de o otimizares.

Do Blender ao GLB: receita de exportação

Sim, o Blender exporta diretamente para GLB. Escolhe Ficheiro → Exportar → glTF 2.0 (.glb, .gltf) e, no painel de exportação, seleciona glTF Binary (.glb). O GLB reúne modelo, materiais, texturas e animações num único ficheiro. Os nomes exatos das opções podem variar com a versão do Blender.

1. Isola o asset. Deixa na seleção ou numa coleção apenas a malha, o esqueleto e os objetos indispensáveis; usa Selected Objects ou Active Collection. Exclui cenários, objetos de teste e malhas ocultas que não fazem parte do modelo.
2. Confere tamanho e orientação. glTF usa metros e eixo Y para cima; verifica as dimensões em escala real, sobretudo para AR. Confirma origem e pose inicial. Ajusta transformações antes de exportar, mas testa uma cópia se o objeto tiver rig ou animações, pois aplicar transformações indiscriminadamente pode alterar o movimento.
3. Prepara materiais PBR. Usa Principled BSDF com texturas de imagem e UVs. Base Color, metallic/roughness, normal, emissive e oclusão são caminhos comuns de glTF. Nós procedurais, efeitos de composição e o aspeto da viewport não se traduzem automaticamente; converte ou faz bake do que for essencial e confirma o resultado exportado.
4. Exporta apenas animações úteis. Mantém nomes claros como Idle e Wave; verifica Actions/NLA, esqueleto e shape keys no GLB final. Simulações e movimentos gerados só durante o render precisam de ser convertidos em keyframes quando não são exportáveis.
5. Revê as opções de malha. Mantém UVs e normais quando há texturas e sombreado; usa tangentes se o resultado do normal map as exigir. Verifica o efeito de Apply Modifiers: subdivisão e outros modificadores podem multiplicar a geometria exportada.
6. Abre o GLB num visualizador. Compara silhueta, materiais, escala, orientação, animações e tamanho do ficheiro. Faz ainda um teste na página e num telemóvel real.

O poster dá uma primeira imagem enquanto o 3D carrega. Com loading="lazy", um visualizador mais abaixo na página só começa a carregar quando se aproxima da área visível.

<model-viewer
  src="/assets/personagem.glb"
  poster="/assets/personagem.webp"
  alt="Personagem 3D estilizado, em pé, que pode ser rodado"
  camera-controls touch-action="pan-y"
  loading="lazy">
</model-viewer>

Câmara, gestos e scroll

camera-controls permite que a pessoa explore o modelo. camera-orbit define o ângulo inicial da câmara. auto-rotate pode chamar a atenção, mas movimento constante deve ser usado com moderação e respeitar a preferência de movimento reduzido.

Devo manter a câmara e as luzes do Blender?

Para um modelo que será apresentado no <model-viewer>, começa por não exportar as câmaras nem as luzes da cena de trabalho. Configura o enquadramento na página com camera-orbit, camera-target e field-of-view; configura o aspeto com environment-image, exposure, tone-mapping e shadow-intensity. A câmara usada no render do Blender não define automaticamente a vista inicial deste componente.

O Blender pode exportar câmaras e luzes pontuais, direcionais ou focos para glTF. Mantém esses dados apenas se outro visualizador ou motor da tua produção precisar deles e testa esse destino. Luzes Area e iluminação World não passam como luzes glTF equivalentes. Se quiseres um aspeto específico no model-viewer, testa o GLB com a iluminação de ambiente que a página realmente usará. Evita gravar sombras fortes no Base Color se também haverá iluminação e sombras dinâmicas, sobretudo em AR.

<model-viewer src="personagem.glb"
  alt="Personagem 3D com roupa azul"
  camera-controls
  camera-orbit="25deg 75deg auto"
  touch-action="pan-y">
</model-viewer>

Se quiseres ligar o scroll à apresentação, podes atualizar a órbita da câmara em JavaScript. Isso faz o ponto de vista mudar; não faz a cabeça do boneco mover-se de forma independente. Para uma página normal, evita bloquear o scroll ou capturar todos os gestos dentro do 3D.

Animações e eventos

As animações têm de existir no GLB ou glTF. Depois de o modelo carregar, availableAnimations devolve os seus nomes. Podes escolher uma com animationName e reproduzi-la com play().

Experimenta a demonstração interativa no início da apostila: escolhe uma animação, reproduz e pausa o robô.

No percurso visual, as setas escolhem uma animação e o botão Reproduzir inicia-a; o scroll muda apenas a câmara. Se o GLB não tiver animações, podes continuar a rodar o modelo. O exemplo abaixo usa um botão com o teu próprio ficheiro:

<model-viewer id="personagem" src="personagem.glb"
  alt="Personagem 3D que acena" camera-controls>
</model-viewer>
<button id="acenar" type="button" disabled>Acenar</button>
<script>
  const viewer = document.querySelector('#personagem');
  const botao = document.querySelector('#acenar');
  viewer.addEventListener('load', () => {
    botao.disabled = !viewer.availableAnimations.includes('Wave');
  });
  botao.addEventListener('click', () => {
    viewer.animationName = 'Wave';
    viewer.currentTime = 0;
    viewer.play({ repetitions: 1 });
  });
</script>

O nome Wave é apenas um exemplo: usa o nome real exportado no teu modelo. Para alternar entre Idle e Wave, podes ouvir o evento finished e voltar à animação de repouso. O componente pode fazer transição suave quando mudas animationName.

Trocar de modelo é uma ação independente

Guarda RobotExpressive.glb e Avocado.glb ao lado do HTML. Este exemplo mostra o estado de carregamento e informa se o GLB escolhido contém animações. O abacate continua interativo mesmo sem clips.

<model-viewer id="visor" src="RobotExpressive.glb"
  alt="Robô 3D que pode ser rodado" camera-controls
  touch-action="pan-y"></model-viewer>
<button type="button" data-modelo="RobotExpressive.glb"
  data-descricao="Robô 3D que pode ser rodado">Robô</button>
<button type="button" data-modelo="Avocado.glb"
  data-descricao="Meio abacate 3D que pode ser rodado">Abacate</button>
<p id="estado" role="status">A carregar…</p>
<script>
  const visor = document.querySelector('#visor');
  const estado = document.querySelector('#estado');
  document.querySelectorAll('[data-modelo]').forEach(botao => {
    botao.addEventListener('click', () => {
      estado.textContent = 'A carregar…';
      visor.setAttribute('alt', botao.dataset.descricao);
      visor.setAttribute('src', botao.dataset.modelo);
    });
  });
  visor.addEventListener('load', () => {
    const total = visor.availableAnimations.length;
    estado.textContent = total
      ? `Modelo pronto: ${total} animação(ões).`
      : 'Modelo pronto, sem animações.';
  });
  visor.addEventListener('error', () => {
    estado.textContent = 'Falha ao carregar. Verifica o caminho do GLB.';
  });
</script>

Este exemplo usa os modelos descarregáveis do capítulo 2. Mantém o tamanho e o fundo do visualizador definidos em CSS, como no primeiro exemplo. O nome exportado da animação pode ser pouco legível, como acontece com o hero.glb; dá nomes curtos às ações no Blender quando puderes.

Hotspots e realidade aumentada

Um hotspot é um elemento HTML colocado numa posição do modelo. Serve para identificar uma peça ou abrir uma explicação. As coordenadas têm de corresponder ao teu GLB; a forma mais fácil de as obter é usar o editor do projeto model-viewer.

<model-viewer src="produto.glb"
  alt="Cadeira 3D com detalhes identificados"
  camera-controls touch-action="pan-y">
  <button slot="hotspot-encosto"
    data-position="0m 0.7m 0m"
    data-normal="0m 0m 1m"
    type="button">Ver encosto</button>
</model-viewer>

Para oferecer AR em dispositivos compatíveis, adiciona ar. Os modos disponíveis incluem WebXR, Scene Viewer e Quick Look; a disponibilidade real depende do dispositivo e do navegador. O atributo ios-src pode apontar para um .usdz ou .reality para Quick Look; sem ele, o componente pode gerar um USDZ. Essa geração automática ainda tem limitações, incluindo animações, por isso testa a experiência em iOS.

<model-viewer src="produto.glb"
  alt="Cadeira 3D que pode ser vista no espaço real"
  camera-controls touch-action="pan-y"
  ar ar-modes="webxr scene-viewer quick-look"
  ar-scale="fixed">
</model-viewer>

Desempenho e acessibilidade

Uma cena 3D leve começa no asset. Mede o peso do GLB, reduz polígonos invisíveis ou desnecessários e adequa as texturas ao tamanho real do visualizador. Usa poster e loading="lazy" em conteúdo abaixo da dobra.

Orçamento inicial para um modelo móvel

Conta triângulos exportados, não apenas “polígonos” no Blender. Não existe um limite universal para model-viewer: desempenho depende também de materiais, texturas, transparências, animações, tamanho do canvas e aparelho. Como referência para assets usados no Scene Viewer do Android, a Google indica 30–50 mil triângulos como faixa ideal e recomenda não ultrapassar 100 mil, até 10 materiais, texturas até 2048 × 2048 e cerca de 10 MB de modelo. Trata estes valores como ponto de partida e restrições desse modo de AR, não como garantia de fluidez para toda a web.

• Escreve alt útil: descreve o que a pessoa precisa de saber sobre o objeto.
• Mantém botões e explicações em HTML normal, acessíveis por teclado.
• Não dependas apenas do 3D para transmitir informação essencial; oferece texto ou imagem alternativa.
• Evita movimento automático quando a pessoa pede menos animação.
• Testa com rato, toque, teclado e num telemóvel menos potente.
• Confirma que o GLB ou glTF, os recursos associados e a biblioteca carregam sem erros.

const viewer = document.querySelector('model-viewer');
const menosMovimento = matchMedia('(prefers-reduced-motion: reduce)');
viewer.autoRotate = !menosMovimento.matches;
menosMovimento.addEventListener('change', event => {
  viewer.autoRotate = !event.matches;
});

Se houver uma ação importante, oferece também um botão fora do modelo. A pessoa não deve ter de descobrir um gesto 3D oculto para completar a tarefa.

Levar o 3D para telemóveis

O objetivo é que a página continue fácil de ler e percorrer, mesmo quando o 3D demora a abrir, não cabe no ecrã ou AR não está disponível. Testa sempre o aparelho mais modesto que pretendes suportar e uma ligação móvel real.

Publicar um personagem interativo

Cria uma página de apresentação de um personagem. A experiência deve ser compreensível mesmo antes do GLB carregar.

1. Prepara um GLB com uma pose inicial e pelo menos uma animação curta; documenta triângulos, materiais, texturas e tamanho final.
2. Cria uma imagem de poster e um texto alt descritivo.
3. Integra o model-viewer com camera-controls e touch-action="pan-y"; ajusta o enquadramento em retrato e paisagem.
4. Acrescenta um botão HTML que inicia a animação após o evento load.
5. Inclui uma descrição textual do personagem e um estado visível se o carregamento falhar.
6. Testa em desktop e telemóvel real, com rede limitada e movimento reduzido; mede o peso transferido e confirma se os gestos não atrapalham o scroll.

Próximo passo: se o projeto exigir que olhos, cabeça ou braços acompanhem continuamente o cursor, leva o mesmo GLB para uma cena Three.js ou React Three Fiber. A preparação do asset e as decisões de acessibilidade continuam a ser úteis.