🧊 STL Viewer — Sistema Web de Visualização de Modelos 3D

Sistema web completo para visualização de arquivos STL e 3MF no browser, com controle de acesso por usuário e senha, gerenciamento de projetos e upload de modelos 3D. Sem necessidade de instalar nenhum software adicional.

---

📋 Índice

• Funcionalidades
• Stack Tecnológica
• Requisitos
• Instalação
• Estrutura do Projeto
• Uso
• Visualizador 3D
• Segurança
• Solução de Problemas
• Licença

---

✨ Funcionalidades

Administrador

• Login seguro com senha criptografada (bcrypt)
• Dashboard com estatísticas gerais do sistema
• Criação, edição e remoção de usuários
• Criação, edição e remoção de projetos
• Upload de arquivos STL e 3MF por projeto (até 100MB)
• Upload via drag & drop ou seleção de arquivo
• Controle granular de permissões: define quais usuários acessam quais projetos
• Visualização prévia de qualquer arquivo cadastrado

Usuário Final

• Login seguro
• Visualização apenas dos projetos liberados pelo administrador
• Seleção do arquivo desejado dentro do projeto
• Visualização completa do modelo 3D no browser, sem instalação de software

Visualizador 3D

• Renderização com Three.js r155 (WebGL) via ES Modules
• Suporte a STL (binário e ASCII) e 3MF (incluindo arquivos exportados pelo Bambu Studio e PrusaSlicer)
• Detecção automática de multi-body em STL — cada body recebe uma cor distinta e é colorível individualmente
• Modos de renderização: Sólido, Wireframe e Sólido + Wireframe
• Iluminação profissional com 4 fontes de luz
• Rotação, pan e zoom com o mouse
• Reset de câmera automático
• Grid e eixos XYZ toggleáveis
• Personalização de cor do modelo e do fundo
• Painel de cores por body para modelos STL multi-body
• Correção automática de orientação (Z-up → Y-up)
• Painel de informações: triângulos, dimensões, tamanho e número de bodies/meshes
• Suporte a tela cheia
• Atalhos de teclado
• Suporte a arquivos grandes via HTTP Range Request

---

🛠 Stack Tecnológica

Camada	Tecnologia
Backend	PHP 8.0+ (puro, sem frameworks)
Banco	MySQL 5.7+ / MariaDB 10.3+
Frontend	HTML5, CSS3, JavaScript ES2022+
Renderização	Three.js r155 (WebGL, ES Modules)
Servidor	Apache 2.4+ com mod_rewrite
Segurança	PDO, bcrypt, sessões PHP, .htaccess

---

📦 Requisitos

• PHP 8.0 ou superior
• Extensões PHP: pdo, pdo_mysql, fileinfo, zip
• MySQL 5.7+ ou MariaDB 10.3+
• Apache com mod_rewrite habilitado
• HTTPS recomendado em produção
• Navegador moderno com suporte a WebGL e ES Modules (Chrome 89+, Firefox 108+, Edge 89+, Safari 15.4+)

---

🚀 Instalação

1. Clone ou faça upload dos arquivos

git clone https://github.com/lbkeppler/stl-viewer.git

Ou faça upload de todos os arquivos para o servidor via FTP/SFTP.

2. Crie o banco de dados

Acesse o phpMyAdmin ou execute via terminal:

mysql -u root -p < sql/install.sql

Isso criará o banco stl_viewer com todas as tabelas e o usuário administrador padrão.

3. Configure o sistema

Edite o arquivo config/database.php:

define('DB_HOST', 'localhost');               // host do banco
define('DB_NAME', 'stl_viewer');              // nome do banco
define('DB_USER', 'seu_usuario');             // usuário do banco
define('DB_PASS', 'sua_senha');               // senha do banco

define('BASE_URL', 'https://seudominio.com'); // sem barra no final!
define('UPLOAD_DIR', __DIR__ . '/../uploads/stl/');
define('MAX_FILE_SIZE', 100 * 1024 * 1024);  // 100MB

⚠️ Atenção: O BASE_URL não deve ter barra / no final.

4. Permissões de pasta

chmod 755 uploads/stl/

5. Primeiro acesso

Acesse o sistema pelo browser:

https://seudominio.com

Credenciais padrão:

E-mail: admin@sistema.com
Senha:  Admin@123

🔐 Troque a senha imediatamente após o primeiro login.

---

📁 Estrutura do Projeto

stl-viewer/
├── index.php                  # Página de login
├── dashboard.php              # Painel do usuário final
├── viewer.php                 # Visualizador STL/3MF
├── logout.php                 # Encerra sessão
├── .htaccess                  # Segurança e configurações Apache
│
├── config/
│   └── database.php           # Configuração do banco e constantes
│
├── includes/
│   ├── auth.php               # Autenticação e controle de sessão
│   ├── functions.php          # Funções CRUD gerais
│   ├── header.php             # Navbar global
│   └── footer.php             # Footer global
│
├── admin/
│   ├── index.php              # Dashboard administrativo
│   ├── users.php              # Gerenciar usuários
│   ├── projects.php           # Gerenciar projetos + upload + permissões
│   └── upload.php             # Endpoint upload AJAX alternativo
│
├── api/
│   ├── get_files.php          # Endpoint: lista arquivos de um projeto
│   └── serve_stl.php          # Endpoint: serve STL/3MF com autenticação
│
├── assets/
│   ├── css/style.css          # Estilos globais do sistema
│   └── js/viewer.js           # Utilitários do visualizador
│
├── uploads/
│   └── stl/
│       └── .htaccess          # Bloqueia execução de scripts nos uploads
│
└── sql/
    └── install.sql            # Script de instalação do banco de dados

---

📖 Uso

Fluxo do Administrador

1. Faça login com as credenciais de administrador
2. Acesse Usuários e crie os usuários do sistema
3. Acesse Projetos e crie um novo projeto
4. Dentro do projeto clique em Gerenciar:
   • Faça upload dos arquivos .stl ou .3mf do projeto
   • Na seção Permissões, conceda acesso aos usuários desejados
5. O usuário já pode logar e visualizar o projeto

Fluxo do Usuário Final

1. Faça login com suas credenciais
2. Na tela inicial aparecerão todos os projetos liberados para você
3. Clique em Abrir Projeto
4. Selecione o arquivo desejado
5. Clique em Visualizar — o modelo abre no browser

---

🎮 Visualizador 3D

Controles do Mouse

Ação	Controle
Rotacionar	Botão esquerdo + arrastar
Mover (pan)	Botão direito + arrastar
Zoom	Scroll do mouse

Atalhos de Teclado

Tecla	Ação
R	Reset da câmera
W	Modo wireframe
S	Modo sólido
B	Modo sólido + wireframe
G	Mostrar/ocultar grid
A	Mostrar/ocultar eixos
F	Tela cheia

Painel de Informações

O painel no canto inferior esquerdo exibe em tempo real:

• Nome do arquivo
• Tamanho em disco
• Número de triângulos da malha
• Dimensões nos eixos X, Y e Z em milímetros
• Número de bodies detectados (STL multi-body)
• Número de meshes (3MF)

Multi-body (STL)

Quando um arquivo STL contém múltiplos bodies desconectados, o visualizador os detecta automaticamente e:

• Atribui uma cor distinta a cada body pela paleta padrão
• Exibe o botão Bodies na toolbar
• Abre um painel lateral com um seletor de cor individual para cada body, permitindo personalização em tempo real

Formatos Suportados

Formato	Observações
.stl	Binário e ASCII, com detecção de multi-body
.3mf	Incluindo arquivos do Bambu Studio e PrusaSlicer

---

🔒 Segurança

• Senhas armazenadas com bcrypt (cost 12)
• Proteção contra session fixation (regenerate_id no login)
• Todas as queries usam PDO com prepared statements
• Arquivos servidos via endpoint PHP autenticado, nunca expostos diretamente
• Validação de assinatura ZIP em arquivos 3MF no upload
• Suporte a HTTP Range Request para arquivos grandes
• Pasta uploads/stl/ com execução de scripts bloqueada
• Pastas config/ e includes/ bloqueadas via .htaccess
• Headers de segurança: X-Content-Type-Options, X-Frame-Options, X-XSS-Protection
• Listagem de diretórios desabilitada (Options -Indexes)
• Validação de extensão e tamanho no upload
• Verificação de permissão em todas as rotas protegidas

---

🔧 Solução de Problemas

Login não funciona após instalação

Verifique se o BASE_URL em config/database.php não possui barra no final:

// ✕ Errado
define('BASE_URL', 'https://seudominio.com/');

// ✓ Correto
define('BASE_URL', 'https://seudominio.com');

Senha do admin não funciona

Crie o arquivo fix_admin.php temporariamente na raiz:

<?php
require_once __DIR__ . '/config/database.php';
$hash = password_hash('Admin@123', PASSWORD_BCRYPT, ['cost' => 12]);
$db   = getDB();
$db->prepare("UPDATE users SET password = ? WHERE email = 'admin@sistema.com'")
   ->execute([$hash]);
echo "Senha atualizada!";

Acesse pelo browser e apague o arquivo em seguida.

Arquivo STL não carrega no visualizador

• Verifique se o arquivo não está corrompido abrindo em outro software (ex: MeshLab, PrusaSlicer)
• Confirme que o tamanho não excede 100MB
• Verifique se a pasta uploads/stl/ tem permissão de escrita
• Cheque se o PHP tem as configurações de upload corretas

Arquivo 3MF não carrega

• Arquivos exportados pelo Bambu Studio e PrusaSlicer são suportados a partir do Three.js r155
• Se o erro persistir, re-exporte o modelo como STL pelo slicer de origem

Visualizador não abre (erro de módulo)

O visualizador usa ES Modules e requer HTTPS ou localhost. Não funciona em http:// em produção — configure o certificado SSL no servidor.

Erro de conexão com banco na Hostinger

O host do banco na Hostinger raramente é localhost. Acesse hpanel.hostinger.com → Hospedagem → Bancos de Dados → MySQL e copie o host exato exibido no painel.

Upload falha silenciosamente

Adicione ao php.ini ou .htaccess:

php_value upload_max_filesize 100M
php_value post_max_size 105M
php_value max_execution_time 120
php_value memory_limit 256M

---

📄 Licença

Este projeto está licenciado sob a MIT License.

MIT License

Copyright (c) 2024

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

Desenvolvido com ☕ e Three.js