Boas práticas
3DVue

Formatos aceitos

A plataforma 3DVue aceita vários formatos 3D. GLTF é o formato recomendado : oferece a melhor relação qualidade/tamanho de arquivo para renderização web em tempo real.

Converter do SolidWorks : STEP / STL → GLTF

Os arquivos de software CAD (SolidWorks, Fusion 360, CATIA) geralmente estão no formato .STEP, .STP ou .STL. Precisam ser convertidos antes da integração.

1. Abrir o FreeCAD
2. Importar o arquivo STEP/STL
   Ctrl + I → selecionar seu arquivo .stp ou .stl

3. Exportar para GLTF ou DAE
   Ctrl + E → escolher formato DAE ou GLTF

Conversor online (alternativa rápida):
   https://imagetostl.com/fr/convertir/un-fichier/stp/en/glb

Exportação do Blender

Se você trabalha diretamente no Blender, aqui estão as configurações de exportação GLTF recomendadas para a plataforma 3DVue. Usar a compressão Draco reduz significativamente o tamanho do arquivo.

Formato:          glTF Binary (.glb)  ← agrupa tudo em um arquivo
Compressão:       Draco ativado       ← reduz o tamanho em 60-80%
Texturas:         Incluir → marcar
Materiais:        Exportar materiais → marcar
Transformações:   Aplicar → marcar    ← obrigatório, ver seção Transformações

Nomenclatura de coleções no Blender

Os scripts automatizam a exportação de arquivos GLTF e mapas UV. Para funcionar corretamente, as coleções do Blender devem seguir uma estrutura precisa.

Collection
  └── nome-produto             ← sem acentos nem espaços
        ├── modelisation         ← todos os objetos 3D
        └── gltf                 ← arquivos de exportação gerados

Exemplos corretos:
  nome-produto: butterfly-chair       ✓
  nome-produto: tolix-chair-a         ✓

Exemplos incorretos:
  nome-produto: Butterfly Chair       ✗ maiúsculas + espaço
  nome-produto: cadeira-estante       ✗ caracteres acentuados

Transformações & escala

• Sempre aplicar transformações Ctrl + A → Todas as Transformações antes de exportar : caso contrário os mapas UV ficam incorretos
• Trabalhar na escala 1 (escala real em metros) : evita erros de escala no configurador
• Se um objeto não toca o chão (ex.: uma luminária suspensa), adicionar um plano invisível chamado RA de tamanho 0.0001m na posição 0,0,0 para realidade aumentada

Addons recomendados para o Blender

Esses addons são usados sistematicamente pela equipe da 3DVue para garantir UVs de qualidade em todos os projetos.

Consistência de Texel Density

A densidade de texels define quantos pixels de textura cobrem uma determinada superfície real. Se dois objetos do mesmo cliente tiverem densidades de texels diferentes, uma textura de madeira aparecerá em escalas diferentes em cada objeto : o que não é realista.

Preferir desdobramentos UV baseados em costuras com o método Conformal : exceto para objetos de cor uniforme que não precisam de um desdobramento preciso.

UV para BAT SVG

Quando o configurador usa um BAT SVG (personalização com upload de logo ou texto), regras adicionais se aplicam ao desdobramento UV.

• Todos os UVs devem caber em um único mapa UV
• Exportar o mapa UV em 4096×4096 px
• O GLTF deve corresponder exatamente ao mapa UV exportado
• Um script do Blender automatiza a exportação do GLTF e do mapa UV : as coleções devem estar corretamente nomeadas para funcionar
• Se necessário, pintar no mapa UV para ajudar a criar o arquivo do Illustrator (alinhamento de padrões)

Nomenclatura de arquivos de textura

Cada canal PBR corresponde a um arquivo de textura com um nome padronizado. A plataforma identifica o papel de cada textura pelo seu nome.

Formatos & resolução

• Formato quadrado obrigatório : 1024×1024 ou 2048×2048 (máximo 2K)
• Formato de arquivo: PNG (recomendado para transparência e qualidade) ou JPEG (tamanho de arquivo menor)
• Um mapa normal muito pesado pode ser comprimido sem perda via imagecompressor.com

Regras gerais

• Formato quadrado obrigatório, resolução 4K (4096×4096 px)
• Nomenclatura: BAT-nomemodelo-dimensao_albedo.svg
• Sem caracteres acentuados, sem espaços no nome do arquivo
• Todos os elementos editáveis devem estar vetorizados no SVG : sem elementos raster

Formato:  BAT-nomemodelo-dimensao_albedo.svg

Exemplos:
  BAT-camiseta-tamanhoG_albedo.svg     ✓
  BAT-caneca-300ml_albedo.svg          ✓
  BAT-camiseta tamanho G albedo.svg    ✗ espaços não permitidos
  BAT-camiseta-tamanhoé_albedo.svg     ✗ caracteres acentuados não permitidos

Estrutura de camadas no Illustrator

As camadas do Illustrator devem ser organizadas de acordo com uma estrutura precisa para que o configurador possa identificar as zonas editáveis e as zonas de referência.

Exportação SVG do Illustrator

• Vetorizar todos os elementos editáveis antes de exportar : Shift + Ctrl + O
• Nomear o arquivo exportado com a convenção nomedesign_albedo.svg
• Sem elementos raster no arquivo exportado : tudo deve ser vetorial
• Verificar que as camadas gabarit e présentation estejam ocultas ao exportar

Incluir o script

Adicione o script uma vez no seu <head> ou antes de </body>. Uma única inclusão é suficiente para todas as páginas do seu site.

<script src="https://cdn.jsdelivr.net/gh/3dvue/api@v4/viewer-3dvue-min.js"></script>

Declarar o componente

Coloque a tag <viewer-3dvue> onde deseja que o visualizador apareça. Dois atributos são obrigatórios: name (identificador único na página) e src (URL do seu configurador, fornecida pela 3DVue na entrega).

<!-- Atributos obrigatórios -->
<viewer-3dvue
  name="meuVisualizador"
  src="https://app.3dvue.fr/view?p=AB01-CD02"
></viewer-3dvue>

<!-- Com debug ativado (logs no console) -->
<viewer-3dvue
  name="meuVisualizador"
  src="https://app.3dvue.fr/view?p=AB01-CD02"
  debug
></viewer-3dvue>

Controle sem JavaScript

O componente escuta automaticamente os eventos click e change em qualquer elemento que tenha os seguintes atributos. Sem JavaScript necessário.

<!-- Botão que muda vários materiais ao clicar -->
<button
  viewer-3dvue="meuVisualizador"
  viewer-3dvue-clic="setMaterial"
  viewer-3dvue-meshs-materials='{"1":"0n","3":"2b"}'
>
  Azul Meia-Noite
</button>

<!-- Select que aplica o valor escolhido -->
<select
  viewer-3dvue="meuVisualizador"
  viewer-3dvue-change="setMaterial"
  viewer-3dvue-mesh="2,4"
>
  <option value="0n">Vermelho</option>
  <option value="1a">Azul</option>
</select>

API JavaScript

Para casos avançados : carregamento dinâmico, captura de imagem, exportação SVG. Recuperar a referência do componente via querySelector.

Eventos

Escute os eventos diretamente no elemento viewer-3dvue através de addEventListener.

// Obter a referência do componente
const viewer = document.querySelector('viewer-3dvue[name="meuVisualizador"]');

// Aguardar que o viewer esteja pronto (recomendado para loadFonts)
viewer.addEventListener("onLoadComplete", () => {
  viewer.loadFonts([{ family: "Bebas Neue" }, { family: "Pacifico" }]);
});

// Mudar materiais
viewer.setMaterial({ "1": "0n", "3": "2b" });

// Modificar o elemento SVG selecionado
viewer.setSVGElementParam("fill", "#ff0000");          // cor
viewer.setSVGElementParam("text", "O meu texto");      // conteúdo do texto
viewer.setSVGElementParam("colorStop.0", "#7C3AED", "zone-id"); // gradiente

// Reagir à seleção de um elemento SVG
viewer.addEventListener("onSVGObjectSelected", (e) => {
  const obj = e.detail.obj;
  if (obj.type === "text") inputText.value = obj.text ?? "";
});
viewer.addEventListener("onSVGObjectDeselected", () => { inputText.value = ""; });

// Capturar o render atual
viewer.captureToBase64();
viewer.addEventListener("onCaptureBase64Complete", (e) => {
  const { base64, error } = e.detail;
  if (!error) document.querySelector("#preview").src = base64;
});