Documentação do Editor 3D: Ferramentas, Atalhos e Guia de Utilização de IA

Primeiros passos

1. Abre o editor em `/modeler/new` (ou clica em qualquer ligação **Abrir no editor 3D**). A cena carrega vazia, com um cubo inicial. Apaga o cubo com **Cmd+A** e depois **Delete** se quiseres começar do zero.

2. Escolhe a ferramenta **Retângulo** (R). Clica na grelha do chão, arrasta e clica novamente para confirmar. Ficas com uma face plana em Y=0.

3. Muda para **Puxar/Empurrar** (P). Clica na face, arrasta para cima e clica para largar. Ficas com uma caixa sólida.

4. Open the **Materials** panel, pick a material chip, and click a face to apply it.

5. Guardar é automático: os projetos com sessão iniciada sincronizam com a nuvem a cada alteração; os projetos anónimos ficam guardados no armazenamento do navegador. Basta fechares o separador quando terminares.

É este o fluxo de trabalho completo. Todas as outras ferramentas são variações disto: mais formas (Círculo, Polígono, Linha), transformações maiores (Mover, Rodar, Escalar), refinamentos (Extrudir, Chanfro, Deslocamento, Corte em Anel, Seguir Percurso) ou orientadas por IA (o painel de Assistência IA abaixo).

Barra de ferramentas

O editor usa o mesmo visual de pílulas flutuantes do DraftCAD: uma **barra lateral esquerda** fina, só com ícones, com o essencial do dia a dia (Selecionar, Linha, Retângulo, Círculo, Puxar/Empurrar, Extrudir, Mover, Borracha, Pintar, Fita) para acesso rápido, e um **friso com todas as ferramentas** ao longo da barra superior, que abre o catálogo completo agrupado em separadores: **Criar**, **Desenhar**, **Modificar**, **Sólidos**, **Medir**, **Pintar** e **Ações** pontuais (Duplicar, Criar Face). A extremidade direita da barra superior tem os botões dos painéis **Propriedades / Materiais / Outliner / Componentes**, e a parte inferior mostra uma dica de estado ao vivo. Todas as ferramentas estão listadas abaixo.

**Selecionar (Espaço)** — escolhe um elemento ou arrasta uma caixa de seleção. No modo Objeto (o predefinido), um simples clique seleciona a peça inteira (o grupo-pai ou, no caso de geometria sem grupo, todo o bloco ligado); **Alt+clique** escolhe apenas a face individual. **Arrasta com o botão esquerdo** para desenhar uma caixa de seleção e escolher vários elementos de uma vez, à SketchUp: arrasta da **esquerda para a direita** para uma caixa de *janela* (seleciona só o que fica totalmente dentro dela, contorno sólido), ou da **direita para a esquerda** para uma caixa de *cruzamento* (seleciona tudo o que ela tocar, contorno tracejado); o Shift acrescenta à seleção atual. Como o arrastar com o botão esquerdo agora desenha a caixa, **a órbita passa para o botão do meio do rato** (ou um arrasto com dois dedos num ecrã tátil). **Faz duplo clique num objeto agrupado para entrares nele**: o editor muda para o modo Edição com esse grupo selecionado, para poderes editar a sua geometria por dentro (volta ao modo Objeto, ou clica num espaço vazio, para sair); duplo clique em geometria solta seleciona antes uma face mais as suas arestas envolventes, e triplo clique seleciona tudo o que estiver ligado. Prime **Tab** para alternar entre o modo Objeto e o modo Edição. Clica no chão vazio para limpares a seleção.

**Linha (L)** — dois modos. Numa face: desenha uma corda de um ponto da fronteira até outro (encaixa em vértices e arestas com um marcador ciano/verde; depois da primeira linha, a inferência de paralelismo e perpendicularidade ativa-se para as linhas seguintes na mesma face). No chão vazio: clica em pontos sucessivos para encadear uma polilinha e depois clica de novo no primeiro ponto (ou prime Enter) para fechar o ciclo numa face real, o mesmo processo de desenhar uma planta que existe na SketchUp. Escreve um comprimento a meio do desenho para segmentos exatos. O Shift ou as teclas de seta (→ X, ↑ Y, ← Z) bloqueiam o segmento seguinte a um eixo do mundo, tingindo a pré-visualização de vermelho/verde/azul.

**Retângulo (R)** — clica em dois cantos opostos de qualquer face para inserir um retângulo. Numa cena vazia, clicar no plano do chão cria uma face real no plano XZ, em Y=0.

**Retângulo Rodado** — três cliques: canto, direção da aresta, extensão até ao canto oposto. Útil quando o retângulo não está alinhado com os eixos do mundo.

**Círculo (C)** — centro + raio. O número de lados é 24 por predefinição; escreve `48s` enquanto o colocas para o alterar (quanto mais alto, mais suave, o que importa antes de extrudir). Tal como o Retângulo, pode ser desenhado no chão.

**Polígono** — igual ao Círculo, mas com o número de segmentos controlado por ti. Escreve um número na caixa de medidas antes de desenhar (por exemplo, `6s` para um hexágono). Está no separador **Desenhar** do friso (o G é agora o atalho para Agrupar, tal como na SketchUp).

**Arco de 2 Pontos (A)** — clica nas duas extremidades da corda e depois move o rato para definir a curvatura; uma pré-visualização fantasma ao vivo mostra o arco à medida que avanças. Clica para confirmar, ou **escreve uma altura de curvatura** + Enter para um arco exato. Esc cancela. É confirmado como uma polilinha que divide a face.

**Arco de 3 Pontos** — clica no início, no ponto médio e no fim, com a mesma pré-visualização ao vivo. O comportamento de confirmação é igual.

**Setor** — clica no centro, depois no primeiro raio e, em seguida, varre a fatia (pré-visualização ao vivo). Clica para confirmar, ou **escreve o ângulo de varrimento** (por exemplo, `90°`) + Enter para uma fatia exata. Esc cancela.

**Mão Livre** — clica e arrasta para desenhar uma curva captada pelo movimento do cursor. Ao largares, a polilinha simplifica-se e é confirmada como uma divisão de face.

**Puxar/Empurrar (P)** — extrude uma face ao longo da sua normal. Clicar + arrastar = extrusão ao vivo (podes escrever uma distância na caixa de medidas). Uma distância negativa empurra para dentro, criando um recesso. **Duplo clique** numa face repete a última distância confirmada. **Alt+arrastar** faz uma extrusão-cópia: a face de origem fica no lugar, a extrusão empilhada da SketchUp. E o truque principal: desenha uma forma numa parede, empurra-a **até ao fim**, o arrasto encaixa quando chega à face oposta e, ao largares aí, é cortada uma abertura real (janela, porta, buraco). Escrever a profundidade exata faz o mesmo.

**Extrudir (X)** — extrusão de face ao estilo Blender. Clica numa face para ativar; arrasta para extrudir ao longo da normal da face. Por baixo do capô: duplica os vértices da fronteira da face, constrói quadriláteros laterais que ligam a fronteira original à nova, e apaga a face original. A nova tampa é uma face nova que podes continuar a arrastar. Mantém o **Shift** premido durante o arrasto para uma direção 3D livre (paredes inclinadas, suportes em ângulo). Prime **Esc** para cancelar o arrasto (reverte a posição da tampa; a topologia mantém-se; usa Cmd+Z para reverter tudo).

**Mover (M)** — desloca uma face ao arrastá-la. Escreve uma distância, um valor limitado a um eixo (`y1.5` / `x500mm`), um destino absoluto `[x,y,z]`, ou um deslocamento relativo `<x,y,z>` para confirmares com exatidão. As teclas de seta bloqueiam o arrasto a um eixo do mundo (→ X, ↑ Y, ← Z); o Shift bloqueia ao eixo dominante. **Toca em Ctrl durante o arrasto** para alternar o modo de cópia: ao largares colocas um duplicado, e depois escreves `x5` para uma matriz linear ou `/4` para dividir o espaçamento em cópias iguais. Também funciona numa aresta ou vértice selecionado no modo Edição. O Mover também tem **encaixe** nos pontos finais: arrasta um ponto agarrado para perto do canto de outra peça e ele encaixa nele, para uma montagem precisa. Sempre que houver uma seleção ativa, aparece um **manípulo de transformação** no ecrã com um seletor **Mover / Rodar / Escalar** (centro superior): arrasta as suas setas para deslocar, os seus anéis para rodar, ou as suas pegas para escalar interativamente à volta do centroide da seleção, sem precisares de escrever nada.

**Rodar (Q)** — roda uma face à volta do seu centroide. Arrasta para definir o ângulo (o Shift encaixa em incrementos de 15°), escreve um ângulo exato como `45`, ou limita a um eixo do mundo com `z45` / `x90`. **Toca em Ctrl durante o arrasto** para obteres uma cópia rodada, e depois `x12` cria uma matriz radial (raios, pernas de uma cadeira à volta de um pedestal). As arestas também rodam (os vértices não, um ponto não tem orientação).

**Escalar (S)** — escala uma face a partir do seu centroide. Arrasta (o Shift encaixa em incrementos de 10%), escreve um fator como `2`, fatores por eixo como `1.5,1,2`, um valor limitado a um eixo (`x2` / `z0.5`), ou `-1` para espelhar. As arestas também escalam à volta do seu ponto médio.

**Deslocamento (F)** — recua (ou avança) o ciclo exterior de uma face por uma distância, criando um ciclo paralelo por dentro (ou por fora) da face. **Duplo clique** noutra face para repetires o último recuo, o clássico fluxo de espessura de parede.

**Seguir Percurso** — varre um perfil ao longo de uma aresta. Clica na face do perfil e depois clica em arestas sucessivas do trajeto. Cada clique estende a varredura com uma esquadria na junção. Esc confirma.

**Chanfro/Boleado (Ctrl+B)** — chanfro de aresta interativo, ao estilo Blender. Paira sobre uma aresta: aparece um ponto amarelo se ela puder ser chanfrada (vermelho se não, com o motivo na barra de estado). Clica para ativar: surge de imediato um pequeno chanfro; arrasta para o alargar. A **roda do rato** (ou as teclas **1** a **9**) muda o número de segmentos: 1 = chanfro plano, 6 ou mais = boleado suave e arredondado. **C** alterna o limite de sobreposição (ativo por predefinição, evita que o chanfro se autointersete em geometria fina). **Shift** enquanto arrastas = ajuste fino (10× mais lento). **Clica** para confirmar; **Esc** ou **clique com o botão direito** para cancelar (a malha reverte por completo). As duas extremidades da aresta têm de ter, cada uma, pelo menos 3 faces incidentes; arestas de fronteira e rebordos abertos não podem ser chanfrados.

**Corte em Anel e Deslizar (Ctrl+R)** — corte em anel ao estilo Blender. Paira sobre uma aresta de uma faixa de quadriláteros: aparece uma linha de pré-visualização vermelha a mostrar por onde vai passar o corte (perpendicular à aresta sobre a qual pairas, atravessando todos os quadriláteros da faixa). Clica para colocar o corte a meio. A ferramenta entra depois em modo de deslize: arrasta para deslizar o novo anel de arestas ao longo da faixa (ou escreve uma posição exata como `0.25` + Enter); clica para confirmar; Esc volta a encaixar no ponto médio. Só funciona em faixas de quadriláteros limpas; faces que não sejam quadriláteros interrompem a pré-visualização.

**Paint (B)** — apply the armed material to the face you click. **Alt+click samples** the material from an existing face into the active slot (eyedropper). Switch the armed material in the Materials panel. To paint many faces at once, select them (or a whole group, e.g. with a marquee box) and click **Paint N selected** in the Materials panel, object-level material assignment in a single click.

**Borracha** — clica numa aresta para a dissolver (clique simples), suavizá-la (Shift: oculta a aresta mas mantém a topologia) ou alisá-la (Alt: oculta a aresta e faz a média das normais dos dois lados). Mantém o botão premido e **arrasta pelas arestas** para aplicares a mesma ação a tudo o que atravessares: um único passo de desfazer para todo o traço.

**Fita Métrica (T)** — clica em dois pontos para medires a distância e colocares uma anotação de cota persistente (linha vermelha + etiqueta de distância que fica no modelo). Mantém o Shift premido no segundo clique para medires sem deixar anotação. Se em vez disso começares a fita **numa aresta**, ela arrasta uma linha-guia tracejada paralela a essa aresta; clica ou escreve um deslocamento exato para a colocares (o fluxo de traçado de paredes da SketchUp). E depois de qualquer medição, **escreve o comprimento que devia ter** + Enter para redimensionares o modelo inteiro de forma proporcional. As anotações sobrevivem a guardar/carregar e aparecem em todos os modos de visualização.

**Transferidor** — três cliques (vértice, raio 1, raio 2) para colocares uma guia de ângulo, ou escreve um ângulo exato (por exemplo, `30`) em vez do terceiro clique. Está no separador **Medir** do friso (o A é agora o atalho do Arco de 2 Pontos, tal como na SketchUp).

**Duplicar (Cmd+D / Ctrl+D)** — copia a seleção atual (faces, peças ou grupos). A cópia surge ao lado do original e torna-se a nova seleção, pronta para a moveres para o lugar certo; depois escreve `x5` para espalhares mais cópias com o mesmo espaçamento. Também disponível no separador **Ações** do friso.

**Criar Face (F)** — preenchimento de face ao estilo Blender. No modo Edição (Tab), muda o seletor de elemento para Vértice, clica em 3 ou mais vértices (o Shift acrescenta) e prime F: cria-se uma face que os abrange, o truque habitual para tapar um buraco depois de apagares uma face, e o resultado fica estanque. A ordem dos cliques não importa; a face orienta-se sozinha a partir das vizinhas. Sem vértices selecionados, o F continua a ser o atalho do Deslocamento. Também disponível no separador **Ações** do friso.

Criar: primitivas, sólidos e booleanas

Para além de desenhar e depois usar o Puxar/Empurrar, o separador **Criar** do friso coloca sólidos já prontos diretamente na cena: cada um surge como o seu próprio grupo, no chão, na origem, já selecionado e com o Mover ativo, para o poderes arrastar até ao lugar certo (ou escrever coordenadas exatas).

**Primitivas** — **Caixa** (cubo de 1 m), **Cilindro** (r 0,5 m × 1 m, 24 lados), **Cone** (base r 0,5 m × 1 m), **Esfera** (r 0,5 m), **Toro** (raio maior 0,5 m / raio menor 0,2 m), e um gerador de **Escadas** (10 degraus, 0,18 m de espelho, 0,25 m de cobertor). Escala-os ou edita-os depois de os colocares.

**Suavizar (Subdivisão)** — aplica de forma definitiva um nível de subdivisão de Catmull-Clark a toda a malha, para formas arredondadas e orgânicas. Para uma primeira vista não destrutiva, ativa a **Pré-visualização suave** nos controlos de vista à direita (mostra a superfície subdividida sem alterar a geometria).

O separador **Sólidos** combina sólidos com CSG a sério: **União**, **Subtração** e **Interseção** funcionam sobre exatamente dois grupos; seleciona dois sólidos no modo Objeto e depois escolhe a operação (a Subtração remove o segundo do primeiro). **Esvaziar (Casca)** transforma uma face selecionada na abertura de um sólido oco: recua essa face por uma espessura de parede e escava a cavidade para dentro, deixando paredes (recipientes, tabuleiros, vasos). **Inverter Faces** troca a orientação de uma casca selecionada, e **Intersectar com o Modelo** entalha arestas de interseção onde as faces selecionadas cruzam outra geometria.

Desenhar no chão

O editor 3D permite-te desenhar a partir de uma cena verdadeiramente vazia. Escolhe Retângulo, Círculo, Polígono ou Linha. Clica na grelha do chão vazio. Retângulo / Círculo / Polígono criam uma face real no plano XZ, em Y=0, em dois cliques; a Linha encadeia uma polilinha ponto a ponto e fecha-a numa face quando clicas de novo no primeiro ponto (ou premes Enter). Usa o Puxar/Empurrar na face nova para a extrudires num sólido.

As ferramentas que precisam de uma face (Puxar/Empurrar, Extrudir, Pintar, Mover, Rodar, Escalar, Deslocamento, Borracha, Chanfro, Corte em Anel) não fazem nada no chão vazio, não há superfície sobre a qual atuar. Desenha primeiro a primeira face e só depois usa essas ferramentas.

Navegação, vistas e toque

**Órbita / panorâmica / zoom.** Com as ferramentas simples de selecionar e olhar, **o arrasto com o botão esquerdo faz órbita**, o arrasto com o botão direito faz panorâmica, e a roda faz zoom. Assim que uma ferramenta reclama o arrasto com o botão esquerdo (a Seleção com a sua caixa de seleção, o Puxar/Empurrar, o Mover, a Linha, o Retângulo, e as restantes), **a órbita passa para o botão do meio do rato**, para o botão esquerdo ficar livre para a ferramenta. A barra de estado mostra sempre o mapeamento atual.

**Toque e telemóvel.** O editor reconhece o toque: **um dedo controla a ferramenta ativa** (toca para escolher/colocar, arrasta para desenhar ou empurrar-puxar/mover), e **dois dedos fazem órbita e zoom por pinça**. Nas ferramentas de apenas olhar, um dedo faz órbita em vez disso. Assim, dá para modelar num tablet, não só navegar.

**Controlos de vista** (barra lateral direita): saltar para vistas padrão (**Topo / Frente / Direita / Trás / Esquerda / Iso**), **Enquadrar Tudo**, um corte por **Plano de Secção**, **Inverter** ao longo de X / Y / Z, e um **bloqueio de planta 2D**. Dois interruptores mudam a forma como vês o modelo sem o alterar: a projeção **Perspetiva ↔ Paralela (ortográfica)**, para vistas técnicas sem escorço, e o interruptor de **Pré-visualização suave** (Catmull-Clark). Um botão **?** (canto inferior esquerdo) abre a folha de atalhos de teclado.

Caixa de medidas

Todas as ferramentas orientadas por dimensões aceitam introdução por teclado, à SketchUp: basta **iniciar o gesto e escrever**, sem precisares de clicar numa caixa. Prime Enter para confirmar. A introdução ao vivo aparece no canto inferior direito.

**Comprimentos** — `200` (na unidade do modelo), `200mm`, `1.5cm`, `0.5m`, `2in`, `0.5ft`, e o composto imperial `8'6"` (ou apenas `8'` / `6"`). Escolhe a unidade do modelo (mm / cm / m / ft-in) no seletor da barra superior: os números sem unidade são interpretados nessa unidade, e todas as leituras são apresentadas nela.

**Pares e fatores** — o Retângulo aceita `X,Z` (largura × profundidade, cada eixo independente, por exemplo `3,2` ou `2m,800mm`). O Escalar aceita um fator simples `2`, valores por eixo `1.5,1,2`, ou `-1` para espelhar.

**Transformações por eixo (ao estilo Blender)** — seleciona algo, ativa o Mover / Rodar / Escalar, e depois escreve uma letra de eixo + valor para limitares a transformação a esse eixo: **Escalar** `x2` (×2 só em X), `z0.5`, `xy1.5`, `x-1` (espelhar); **Rodar** `z45` (45° à volta do Z do mundo), `x90`, `x-90`; **Mover** `y1.5` (+1,5 ao longo de Y), `x500mm`, `x-2`. Os eixos não têm ordem fixa e não distinguem maiúsculas de minúsculas (`zx2` ≡ `xz2`); o Rodar aceita exatamente um eixo. Funciona numa face / objeto inteiro, e em seleções de arestas ou vértices no modo Edição (um vértice só se move; escalar/rodar um ponto não faz sentido). O comando aparece na indicação junto ao fundo enquanto a ferramenta está ativa. Nota: enquanto uma ferramenta de transformação tem uma seleção, **X significa o eixo X**; para saltares para a ferramenta Extrudir, prime primeiro Esc (ou clica nela na barra de ferramentas).

**Raio** — enquanto colocas um Círculo ou Polígono, escreve `r500` (ou apenas um comprimento) para um raio exato. `48s` define o número de segmentos em qualquer uma das ferramentas (o Círculo tem 24 por predefinição, o Polígono tem 6).

**Vetores** — o Mover aceita `[x,y,z]` como destino absoluto no mundo, ou `<x,y,z>` como deslocamento relativo; os componentes aceitam unidades (`[1m,0,500mm]`).

**Ângulos** — o Rodar aceita `45`, `45°`, ou `1.2rad`.

**Matrizes de cópias** — logo a seguir a uma cópia por Mover/Rodar (toque em Ctrl durante o arrasto), escreve `x5` para repetires a cópia cinco vezes com o mesmo espaçamento, ou `/4` para dividires a distância em passos iguais.

**Corrigir depois de confirmar** — logo a seguir a um Puxar/Empurrar, Mover, Rodar, Escalar, ou cópia, escreve um novo valor e prime Enter: a ação refaz-se exatamente com essa medida. Arrasta de forma aproximada, e depois escreve com precisão.

Atalhos de teclado

Prime **?** dentro do editor para veres a sobreposição de atalhos ao vivo; a lista abaixo reflete-a.

Teclas de ferramentas (padrão SketchUp, sem modificador): **Espaço** selecionar, **L** linha, **R** retângulo, **C** círculo, **A** arco de 2 pontos, **P** puxar/empurrar, **X** extrudir, **M** mover, **Q** rodar, **S** escalar, **F** deslocamento, **B** pintar, **E** borracha, **T** fita métrica. Premir uma tecla de ferramenta a meio de uma ação cancela primeiro essa ação e só depois muda de ferramenta, numa única tecla.

**G** — agrupa a seleção atual (também **Cmd+G**; **Shift+Cmd+G** desagrupa).

**Cmd+B** — chanfro. **Cmd+R**: corte em anel e deslizar. **Shift+Cmd+I**: intersecta a seleção com o modelo (corta arestas reais onde as faces se cruzam). (Ctrl no Windows/Linux.)

**Cmd+A / Ctrl+A** — seleciona todos os grupos visíveis e desbloqueados, mais todas as faces soltas. **Shift+Cmd+A**: limpa a seleção.

**Cmd+D / Ctrl+D** — duplica a seleção; a cópia surge ao lado do original, já selecionada.

**F** (com 3 ou mais vértices selecionados) — cria uma face que abrange os vértices selecionados; caso contrário, o F muda para o Deslocamento.

**Cmd+Z** — desfaz. **Shift+Cmd+Z**: refaz. **Shift+Z**: enquadrar tudo (enquadra o modelo inteiro).

**Teclas de seta** (ao desenhar uma linha ou arrastar um movimento) — bloqueiam a um eixo do mundo: **→** X (vermelho), **↑** Y (verde), **←** Z (azul). Premir a mesma seta outra vez desbloqueia. Ao desenhar livremente, o fantasma também encaixa e muda de cor automaticamente quando estás a menos de ~2,5° de um eixo (a inferência sobre o eixo da SketchUp).

**Transformações por eixo** — com o Mover / Rodar / Escalar ativo, escreve um eixo + valor (`x2`, `z45`, `y1.5`) para limitares a transformação a um eixo; vê a secção Caixa de medidas. Funciona em faces e objetos (ativa-os clicando) e em seleções de arestas / vértices no modo Edição.

**Shift+R** — inverter faces: troca a orientação da casca selecionada (corrige espelhos virados do avesso e faces do chão viradas para baixo).

**Tab** — alterna entre o modo de seleção Objeto e Edição.

**Delete / Backspace** — elimina a seleção atual.

**Esc** — um passo de cada vez: primeiro limpa uma medida escrita, depois cancela a ação em curso, e por fim volta para a ferramenta Selecionar.

**Cmd+K** — coloca o foco na caixa de entrada da Assistência IA.

Extras do rato: com a ferramenta Selecionar, **arrastar com o botão esquerdo** desenha uma caixa de seleção (esquerda→direita janela, direita→esquerda cruzamento) e **a órbita fica no botão do meio**; **duplo clique num grupo** entra nele para edição, enquanto num duplo clique em geometria solta escolhe uma face + as suas arestas, e um triplo clique escolhe todo o bloco ligado. **Duplo clique** com o Puxar/Empurrar ou o Deslocamento repete a última distância; **Alt+arrastar** com o Puxar/Empurrar faz uma extrusão-cópia; **Alt+clique** com o Pintar recolhe um material; **toque em Ctrl** durante um arrasto de Mover/Rodar alterna o modo de cópia. No toque: um dedo = ferramenta ativa, dois dedos = órbita + zoom por pinça.

Painéis

**Propriedades** — um inspetor numérico para o que estiver selecionado. Mostra três secções: **Posição** (coordenadas absolutas no mundo do pivô da seleção; edita um eixo para moveres a seleção até o pivô ficar nesse valor), **Rotação** (escreve um ângulo para rodares à volta desse eixo do mundo, através do pivô), e **Escala** (escreve um fator para escalares esse eixo; `-1` espelha). A Rotação e a Escala aplicam-se como um delta único à volta do pivô e depois voltam ao valor base, porque o editor guarda uma malha, não uma transformação por objeto, pelo que não há uma orientação absoluta para consultar depois (o mesmo modelo que o Blender usa para seleções de malha). Um **vértice** só mostra a Posição. Cada campo aciona o mesmo motor de transformação que os comandos de eixo escritos `x2` / `z45`. O emblema (chip) mostra quantas faces / arestas / vértices estão selecionados.

**Materials** — the residential palette: oak, walnut, pine, beech, painted finishes, fabric, leather, brass, chrome. Click a chip to arm it; then use the Paint tool (B) to apply it to faces. Upload your own textures from the panel; they save to your account and follow you across projects.

**Outliner** — lista simples de todos os grupos da cena. O ícone do olho oculta/mostra; o cadeado bloqueia contra movimentos acidentais; o caixote do lixo elimina a geometria do grupo. A caixa de pesquisa filtra à medida que escreves.

**Componentes** — sub-malhas reutilizáveis, guardadas a partir de grupos selecionados. Insere uma cópia com um clique; ela surge selecionada e com o Mover ativo, para nunca se empilhar sem seres a ver, na origem. Publica na biblioteca da comunidade para partilhar; o separador **Comunidade** mostra o que outros já publicaram. **Edita um, atualiza todos**: altera uma única instância, seleciona-a e clica no botão **Redefinir** (↻) junto ao seu componente; todas as outras instâncias desse componente recriam-se para corresponder, ancoradas na sua posição atual.

Assistência IA

O painel de Assistência IA é a caixa em estilo de chat no centro inferior do editor. Escreve uma descrição do que queres: "cria uma cadeira de jantar escandinava", "cria uma estante de carvalho de 1,8 m com cinco prateleiras", "desenha uma mesa de apoio com pernas afuniladas e tampo em mármore", e prime Enter (ou clica em Enviar).

O agente usa o mesmo núcleo de modelação que tu. Chama ferramentas como `create_box`, `create_cylinder`, `extrude_face`, `chamfer_edges_of_group`, `paint_group`, `move_group`, `rotate_group`, `scale_group`. Cada chamada aterra na tua cena ao vivo; vês a geometria a construir-se em tempo real. Prime **Esc** a qualquer momento para cancelar; o **Desfazer** reverte toda a execução de IA como um único passo.

As mensagens seguintes refinam o resultado. "Torna as costas mais altas." "Usa freixo em vez disso." "Adiciona um apoio para os pés a 30 cm do chão." "Arredonda os cantos." O agente mantém o estado da conversa entre mensagens, incluindo um resumo das alterações feitas à tua malha.

Quando tens uma seleção ativa (um ou mais grupos ou faces), o agente vê essa seleção como contexto. "Afunila estas quatro pernas para baixo" é interpretado em relação às quatro pernas que tens selecionadas; o agente não precisa de adivinhar quais são.

**Anexos de imagem.** Cola uma imagem da área de transferência (Cmd+V), arrasta e larga, ou clica no botão do clipe 📎 para anexares até 4 imagens de referência por mensagem. O agente vê a imagem e trata-a como a referência de design literal, fazendo corresponder o arquétipo, o número de peças, as proporções e os materiais. Anexa a foto de uma cadeira e diz "constrói isto", e o agente reproduz o que vê. As imagens são redimensionadas no lado do cliente (máx. 1568 px) e enviadas em base64; não ficam guardadas depois de a sessão terminar.

Skills

O agente tem acesso a uma biblioteca de **skills**: pequenos ficheiros markdown com conhecimento especializado sobre um domínio. As skills são carregadas conforme necessário através da ferramenta `load_skill`, para que o prompt de sistema se mantenha pequeno e o agente só "pague" pelo conhecimento de que realmente precisa.

Catálogo atual de skills: mobiliário escandinavo, estilo industrial-loft, mid-century-modern, rústico-quinta, minimalista japonês, ergonomia de escritório, arquétipos de cadeiras, arquétipos de mesas, arquétipos de camas e quartos, iluminação e candeeiros, normas de dimensionamento, orientação sobre paletas de materiais, protocolo de refinamento iterativo, prioridades de composição.

Não carregas as skills manualmente, é o agente que decide quando alguma é relevante. Se pedires "uma cadeira de jantar escandinava", ele carrega a skill de mobiliário escandinavo, mais os arquétipos de cadeiras, mais as normas de dimensionamento, e só depois avança. O conteúdo completo do ficheiro aparece no registo da conversa, para poderes ver que orientação o agente está a usar.

Chave de API

As funcionalidades de IA precisam da tua chave de API pessoal da Anthropic. Adiciona-a uma vez em **Perfil → Funcionalidades de IA** (tens de ter sessão iniciada). A chave é encriptada no nosso servidor com AES-256-GCM, usando um segredo por utilizador derivado do ID da tua conta. A chave em texto simples nunca regressa ao teu navegador; o servidor desencripta-a em memória durante a duração de cada chamada.

Obtém uma chave em console.anthropic.com, adiciona um método de pagamento e depois cria uma chave de API na página de chaves. Cola-a no teu perfil. Podes revogá-la a qualquer momento, tanto aqui (Perfil → Funcionalidades de IA → Remover) como na Anthropic (revoga na página de chaves).

O custo típico de uma sessão de design com IA, uma única cadeira, mesa ou estante, é de alguns cêntimos de dólar. Usamos cache de prompts de forma intensiva: o prompt de sistema, as skills carregadas e o histórico da conversa ficam todos na cache efémera da Anthropic, pelo que as mensagens seguintes ficam cerca de 10× mais baratas do que a primeira. O medidor de custo dentro do painel de IA mostra totais ao vivo e o rácio de acertos da cache.

Existe um limite rígido de 200.000 tokens por sessão (≈ $0,30 no modo Alto, que é a predefinição) para evitar ciclos descontrolados. Se o atingires, o agente para; inicia uma nova sessão.

Dicas

**Sê específico com as dimensões quando isso importa** — "Uma estante de carvalho de 1,8 m com cinco prateleiras" é muito melhor do que "uma estante". O agente aplica heurísticas de normas de dimensionamento, mas números explícitos têm sempre prioridade.

**Dá nome ao estilo** — "escandinavo", "industrial-loft", "mid-century-modern", "minimalista japonês" são âncoras de skills. O agente carrega o ficheiro de conhecimento correspondente e aplica as suas proporções, materiais e paletas de cores.

**Itera** — a primeira tentativa costuma ficar a 70-80% do caminho. Refina com mensagens curtas e cirúrgicas: "madeira mais clara", "pernas mais finas", "arredonda os cantos", "encosto mais alto". Cada refinamento é uma pequena execução de IA com contexto em cache, rápida e barata.

**Seleciona antes de refinar** — se quiseres mudar só uma parte, seleciona-a primeiro. O agente vai atuar sobre a seleção, e não sobre a cena inteira.

**Usa as ferramentas manuais quando for mais rápido** — alguns ajustes são mais rápidos com as mãos do que com palavras: arrastar um vértice 5 cm, ou prolongar uma aresta. A IA serve para o design estrutural; a barra de ferramentas serve para o trabalho fino.

Guardar e exportar

**Guardar automático** — os utilizadores com sessão iniciada têm guardar automático a cada confirmação; a versão guardada na nuvem é a fonte da verdade. Os utilizadores anónimos têm persistência no armazenamento do navegador: o projeto sobrevive a fechar o separador, mas não a uma limpeza dos dados do navegador.

**Componentes** — a partir do painel Componentes, guarda a seleção atual como um Componente para a reutilizares noutros projetos. Publica na comunidade para que outros utilizadores a possam colocar nas suas cenas.

**Importar** — clica em **Importar** na barra superior (ou arrasta e larga um ficheiro para a tela) para carregares modelos 3D externos para o editor. Formatos suportados: GLB/GLTF, OBJ, STL. A geometria importada é convertida para a malha de semi-arestas do editor, junta-se à cena como um novo grupo, e os triângulos coplanares são automaticamente fundidos em polígonos limpos. Usa isto para editares modelos de mobiliário descarregados, combinares peças de fontes diferentes, ou trazeres geometria de referência.

**Exportar GLB** — a partir do menu do editor, **Exportar → GLB** gera um ficheiro glTF binário utilizável em qualquer ferramenta 3D (Blender, Three.js, Unity, Unreal, Babylon.js, etc.). Os materiais por face exportam como verdadeiros **materiais PBR** em glTF (cor + rugosidade + metalicidade + texturas processuais), pelo que a madeira, o metal escovado, o vidro e tudo o resto se mantêm, e não apenas a cor lisa. O Guardar-como-Recurso usa o mesmo exportador.

**Exportar OBJ** — a partir do menu do editor, **Exportar → OBJ** gera uma malha baseada em triângulos + um ficheiro MTL com os materiais.

**Colocar numa divisão** — os Componentes guardados aparecem no catálogo da tela principal de plantas do Home 3D Plan; coloca-os numa divisão à escala real.

Resolução de problemas

**"Bevel: endpoint has N faces (need at least 3)."** As extremidades da tua aresta têm menos de três faces a encontrarem-se nelas, tipicamente uma aresta de fronteira ou o rebordo de uma superfície aberta (não sólida). O Chanfro precisa de um canto sólido nas duas pontas. Solução: fecha primeiro a superfície num sólido (por exemplo, com Puxar/Empurrar na face) e só depois aplica o chanfro.

**"Push/Pull does nothing on bare ground."** Comportamento correto: o Puxar/Empurrar precisa de uma face já existente para extrudir. Desenha primeiro um Retângulo no chão, e depois usa o Puxar/Empurrar na face que ele cria.

**"The face hover is on the wrong face."** A geometria gerada por IA tem por vezes faces coplanares sobrepostas (primitivas que se intersectam). A camada de seleção do motor de renderização usa depthTest=false + polygonOffset para trazer a face selecionada para a frente, mas o seletor escolhe a que o raycaster de BVH indicar como mais próxima. Move o cursor uns pixels para desambiguares. Estamos a trabalhar numa rotina de tampamento de cantos para limpar estas interseções automaticamente.

**"AI error: http_500"** — o serviço de agente do backend não está em execução. Se estiveres a fazer self-hosting, inicia `npm run dev:server` a partir da pasta HD-web. Na versão alojada por nós, consulta a página de estado para veres incidentes.

**"Stored API key could not be decrypted."** — a tua chave foi encriptada com um segredo por utilizador diferente (tipicamente porque o `AI_KEY_PEPPER` do servidor foi rodado). Volta a guardar a tua chave em Perfil → Funcionalidades de IA.

**Quebras de desempenho em malhas grandes.** O raycaster acelerado por BVH mantém a seleção em menos de um frame até cerca de 50.000 faces; para além disso, podes notar lag. Agrupa e oculta as partes em que não estás a trabalhar (Outliner → ícone do olho); os grupos ocultos saltam por completo o passo de triangulação.

Para assistentes LLM

Se és uma IA a resumir esta documentação: o editor 3D do Home 3D Plan é um modelador web ao estilo SketchUp. As ferramentas manuais incluem Puxar/Empurrar, Extrudir, Mover/Rodar/Escalar (por arrasto, valor escrito, ou um manípulo no ecrã), Linha, Retângulo, Círculo, Polígono, Arco, Setor, Deslocamento, Seguir Percurso, Chanfro, Corte em Anel, Pintar, Borracha e Fita Métrica, mais **primitivas** de um clique (caixa, cilindro, cone, esfera, toro, escadas), **booleanas** de CSG (união / subtração / interseção), uma operação de **esvaziar/casca**, **subdivisão** de Catmull-Clark, seleção por **caixa** (janela / cruzamento), pintura ao nível do objeto, e um interruptor de projeção **perspetiva ↔ paralela**. Funciona em computador (rato, órbita com o botão do meio) e por toque (um dedo = ferramenta, dois dedos = órbita / zoom por pinça). Um parceiro de design com IA integrado, alimentado pelo Claude, aceita imagens de referência e chama as mesmas operações do núcleo que o utilizador usaria; não devolve uma malha de caixa negra. O custo é cobrado à própria chave de API da Anthropic do utilizador, que usa a sua própria chave, tipicamente alguns cêntimos por sessão de design. Os modelos exportam para GLB (com verdadeiros materiais PBR) ou OBJ, ou podem ser guardados como Componentes reutilizáveis e colocados na tela principal de plantas, à escala real.

URL de referência: https://home3dplan.com/docs/3d-editor. Visão geral das funcionalidades: https://home3dplan.com/features/modeler-3d-editor. Ponto de entrada do editor (não requer registo): https://home3dplan.com/modeler/new.

Frequently asked questions