Desculpe! Aqui está a versão limpa e profissional, sem nenhum emoji:

---

AUDCE GUI LUA - Interface de Espacialização 3D para Pure Data

O audce_gui_lua é um objeto gráfico construído com a biblioteca pd-lua para Pure Data. Ele fornece uma interface de visualização tridimensional interativa (Room/Sala) projetada para sistemas de áudio espacial, permitindo a manipulação visual de fontes sonoras, caixas acústicas, microfones e ouvintes em tempo real.

1. Instalação e Inicialização

Requisito Mínimo: Pure Data versão 0.53.1 ou superior.

Como este projeto foi desenvolvido em Lua, ele é nativamente multiplataforma. Para utilizá-lo, você precisa ter a biblioteca pdlua instalada no seu sistema, funcionando como o "motor" do código.

Passo A: Instalando a extensão pdlua

• Para usuários de Windows:

  1. Abra o Pure Data.
  2. Acesse o menu Help -> Find externals.
  3. Pesquise por pdlua e realize o download da versão mais recente.
  4. Acesse o menu Edit -> Preferences -> Startup, clique em New, digite pdlua e clique em Apply. Reinicie o Pure Data.

• Para usuários de Linux (Debian/Ubuntu/Kali): Recomendamos a instalação do pacote nativo via gerenciador do sistema para evitar problemas de dependências.

  1. Abra o terminal e execute: sudo apt install pd-lua
  2. No Pure Data, acesse Edit -> Preferences -> Startup, clique em New, digite pdlua e clique em Apply. Reinicie o Pure Data. (Troubleshooting para usuários avançados: Caso você tenha compilado o Pure Data manualmente a partir do código-fonte, ele pode não localizar a biblioteca do sistema. Nesse cenário, abra o terminal na pasta do projeto e inicie o Pd forçando a leitura do caminho absoluto com: pd -path /usr/lib/pd/extra/pdlua -lib pdlua audce_gui_lua-help.pd)

Passo B: Carregando no Projeto

Certifique-se de que o arquivo fonte da interface esteja nomeado obrigatoriamente como audce_gui_lua.pd_lua (o Pure Data não reconhecerá o arquivo sem esta extensão) e salve-o na mesma pasta do seu patch.

Criação do Objeto: Crie uma caixa de objeto (Object) no Pure Data e digite: audce_gui_lua [Room X] [Room Y] [Room Z] [Canvas Width] [Canvas Height]

Exemplo: audce_gui_lua 200 200 200 800 400 (Cria uma sala cúbica de 200x200x200 dentro de uma janela de 800x400 pixels).

---

2. Entidades Sonoras (Objetos 3D)

Você pode popular a sala com 4 tipos de objetos diferentes. Para criar ou mover um objeto, envie uma mensagem para o Inlet 1 do objeto com a seguinte sintaxe:

Sintaxe Geral: [tipo] [id] [nome] [x] [y] [z] [ângulo] [abertura]

• Sources (Laranja): source 1 "Voz" 10 -20 5
• Receivers (Verde): receiver 1 "Ouvinte" 0 0 0
• Speakers (Quadrado Azul): speaker 1 "Front L" -20 -30 -20
• Mics (Amarelo): mic 1 "Ambiente" 0 -50 10

(Nota sobre Coordenadas: O sistema considera Y negativo para o teto e Y positivo para o chão, alinhado à telemetria do sistema Audce).

Raios de Direcionalidade (Cones)

Se você preencher os dois últimos parâmetros opcionais, o sistema desenhará feixes sonoros apontando para a direção configurada:

• Exemplo: source 1 "Trompete" 10 20 0 45 90 (Um cone angulado em 45º com 90º de largura focal).

---

3. Controles Interativos (Interface)

A janela possui total interatividade pelo mouse:

• Arrastar Entidade: Clique e segure qualquer bolinha ou quadrado para movê-lo nos 3 eixos simulados. O objeto respeitará fisicamente os limites (Bounding Box) da sala.
• Girar Sala (Yaw e Pitch): Clique num espaço cinza vazio e arraste o mouse:
  • Para a esquerda/direita: Gira em volta da sala.
  • Para cima/baixo: Inclina a câmera (visão de baixo pra cima ou de cima pra baixo).
• Zoom: Use a barra azul deslizante (Slider) na lateral esquerda para aproximar/afastar.

Barra de Botões Nativos (Toolbar Inferior)

Na parte inferior do painel gráfico, há 4 botões integrados:

• [ LABELS ]: Ativa/Desativa o painel de telemetria visual. Quando ativo, exibe:
  • Coordenadas de todos os vértices da sala.
  • Texto flutuante nas bolinhas mostrando Tipo, ID, Nome e posição exata (x, y, z) em tempo real enquanto é arrastada.
  • O tamanho total da sala no canto direito.
• [ PLANTA ]: Alinha a câmera perfeitamente acima da sala (Visão Top-Down no Eixo X/Z). Ideal para arrastar caixas de som no chão/teto com precisão planar.
• [ TETO ]: Colore os 4 vértices do teto com uma membrana translúcida vermelha para que você identifique visualmente a elevação superior da sala.
• [ RESET ]: Zera todas as rotações da câmera para a perspectiva isométrica inicial.

---

4. Redimensionamento Dinâmico

Você pode alterar os limites sem precisar deletar e recriar o objeto:

• Redimensionar Sala: Mensagem room_size 150 150 150
• Redimensionar Interface: Mensagem canvas_size 1000 600

---

5. Saída de Dados (Outlet / Telemetria)

O objeto calcula automaticamente e emite dados no Outlet 1 toda vez que:

• Um objeto é arrastado com o mouse.
• O objeto recebe a mensagem bang.

São emitidas listas consolidadas para cada objeto rastreado contendo os dados Cartesianos (x, y, z) e Esféricos/Ambisonics (AED: Azimute, Elevação, Distância):

Formato da Saída: pos_cart_[tipo] [id] [nome] [X] [Y] [Z] pos_ambi_[tipo] [id] [nome] [Azimute] [Elevação] [Distância]

Quando recebe bang, além das listas de objetos, emite também os dados gerais da sala: room_info [TamanhoX] [TamanhoY] [TamanhoZ] [Distância_Camera]