Tutorial de Three.js: Um Guia para Iniciantes

Three.js é uma das bibliotecas JavaScript mais populares para criar gráficos 3D em navegadores da web. Construída sobre o WebGL, simplifica o processo de criação e exibição de gráficos computadorizados 3D animados em um navegador da web, sem exigir que você aprenda WebGL de baixo nível. Se você está querendo criar visualizações interativas, jogos ou experiências imersivas na web, o Three.js fornece as ferramentas necessárias para dar vida às suas ideias.

Antes de começarmos o desenvolvimento com o Three.js, considere experimentar o Apidog como uma alternativa ao Postman para suas necessidades de teste de API. O Apidog oferece uma interface intuitiva com recursos poderosos para desenvolvimento, teste e documentação de API - tudo isso sem a quantidade excessiva de recursos que muitos usuários acham frustrante no Postman. É uma excelente ferramenta auxiliar ao desenvolver aplicações web que interagem com APIs.

botão

Agora, vamos iniciar nossa jornada no Three.js!

1. Configurando Seu Ambiente

Instalação

Existem várias maneiras de incluir o Three.js em seu projeto:

Opção 1: Usando npm (Recomendado)

npm install three

Então, importe-o em seu arquivo JavaScript:

import * as THREE from 'three';

Opção 2: Usando um CDN

Adicione isso ao seu arquivo HTML:

<script src="https://cdn.jsdelivr.net/npm/three@0.157.0/build/three.min.js"></script>

Opção 3: Baixar e incluir localmente

Baixe a biblioteca do site do Three.js e inclua-a em seu HTML:

<script src="path/to/three.min.js"></script>

Estrutura do Projeto

Para um projeto básico do Three.js, você precisará:

pasta-do-projeto/
├── index.html
├── style.css
└── script.js

Seu arquivo index.html deve incluir:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Meu App Three.js</title>
    <style>
        body { margin: 0; }
        canvas { display: block; }
    </style>
</head>
<body>
    <script src="https://cdn.jsdelivr.net/npm/three@0.157.0/build/three.min.js"></script>
    <script src="script.js"></script>
</body>
</html>

2. Compreendendo os Fundamentos

O Three.js opera com alguns conceitos-chave que são essenciais para entender:

Os Componentes Principais

Cena: Pense nisso como um contêiner que abriga todos os seus objetos, luzes e câmeras.
Câmera: Define qual parte da cena é visível (seu ponto de vista).
Renderizador: Desenha o que a câmera vê na sua tela.
Objetos (Malhas): Os objetos 3D em sua cena, tipicamente compostos de geometria e material.
Luzes: Fontes de iluminação para sua cena.

Criando Sua Primeira Cena

Aqui está um exemplo básico para criar um cubo giratório:

// Criar a cena
const scene = new THREE.Scene();

// Criar uma câmera
const camera = new THREE.PerspectiveCamera(
    75,                                     // Campo de visão
    window.innerWidth / window.innerHeight, // Proporção
    0.1,                                    // Plano de recorte próximo
    1000                                    // Plano de recorte distante
);
camera.position.z = 5;

// Criar o renderizador
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// Criar um cubo
const geometry = new THREE.BoxGeometry();
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

// Loop de animação
function animate() {
    requestAnimationFrame(animate);

    // Rotacionar o cubo
    cube.rotation.x += 0.01;
    cube.rotation.y += 0.01;

    renderer.render(scene, camera);
}
animate();

3. Tornando seu App Responsivo

Para garantir que sua aplicação Three.js fique boa em todos os dispositivos, você precisa lidar com o redimensionamento da janela:

// Lidar com o redimensionamento da janela
window.addEventListener('resize', () => {
    const width = window.innerWidth;
    const height = window.innerHeight;

    // Atualizar renderizador
    renderer.setSize(width, height);

    // Atualizar câmera
    camera.aspect = width / height;
    camera.updateProjectionMatrix();
});

4. Adicionando Materiais e Iluminação

As cenas básicas são apenas o começo. Vamos melhorar a qualidade visual com materiais e luzes:

Materiais

// Material padrão com reflexão
const material = new THREE.MeshStandardMaterial({
    color: 0x0088ff,       // Cor azul
    roughness: 0.5,        // Um pouco brilhante
    metalness: 0.5,        // Um pouco metálico
});

// Material Phong para superfícies brilhantes simples
const phongMaterial = new THREE.MeshPhongMaterial({
    color: 0xff0000,       // Cor vermelha
    shininess: 100,        // Muito brilhante
    specular: 0x111111     // Cor do brilho especular
});

Luzes

// Adicionar luz ambiente
const ambientLight = new THREE.AmbientLight(0x404040);
scene.add(ambientLight);

// Adicionar luz direcional (como o sol)
const directionalLight = new THREE.DirectionalLight(0xffffff, 1);
directionalLight.position.set(1, 1, 1);
scene.add(directionalLight);

// Adicionar luz pontual (como uma lâmpada)
const pointLight = new THREE.PointLight(0xffffff, 1, 100);
pointLight.position.set(10, 10, 10);
scene.add(pointLight);

5. Criando Diferentes Geometrias

O Three.js vem com muitas geometrias integradas:

// Esfera
const sphereGeometry = new THREE.SphereGeometry(1, 32, 32);
const sphere = new THREE.Mesh(sphereGeometry, material);
sphere.position.x = -3;
scene.add(sphere);

// Cilindro
const cylinderGeometry = new THREE.CylinderGeometry(1, 1, 2, 32);
const cylinder = new THREE.Mesh(cylinderGeometry, material);
cylinder.position.x = 0;
scene.add(cylinder);

// Toróide (donut)
const torusGeometry = new THREE.TorusGeometry(0.8, 0.3, 16, 100);
const torus = new THREE.Mesh(torusGeometry, material);
torus.position.x = 3;
scene.add(torus);

6. Criando Texto em Three.js

Texto pode ser adicionado à sua cena usando o TextGeometry:

// Primeiro, carregue a fonte
const loader = new THREE.FontLoader();
loader.load('https://threejs.org/examples/fonts/helvetiker_regular.typeface.json', function(font) {
    const textGeometry = new THREE.TextGeometry('Olá Three.js!', {
        font: font,
        size: 0.5,
        height: 0.1,
        curveSegments: 12,
        bevelEnabled: true,
        bevelThickness: 0.03,
        bevelSize: 0.02,
        bevelOffset: 0,
        bevelSegments: 5
    });

    const textMaterial = new THREE.MeshStandardMaterial({ color: 0xffff00 });
    const text = new THREE.Mesh(textGeometry, textMaterial);

    // Centralizar o texto
    textGeometry.computeBoundingBox();
    const textWidth = textGeometry.boundingBox.max.x - textGeometry.boundingBox.min.x;
    text.position.x = -textWidth / 2;

    scene.add(text);
});

7. Desenhando Linhas

Você pode criar linhas no Three.js para wireframes ou visualização de trajetórias:

// Criar pontos para a linha
const points = [];
points.push(new THREE.Vector3(-2, 0, 0));
points.push(new THREE.Vector3(0, 2, 0));
points.push(new THREE.Vector3(2, 0, 0));

// Criar a geometria da linha
const lineGeometry = new THREE.BufferGeometry().setFromPoints(points);

// Criar material
const lineMaterial = new THREE.LineBasicMaterial({ color: 0xffffff });

// Criar a linha
const line = new THREE.Line(lineGeometry, lineMaterial);
scene.add(line);

8. Interação e Controles

Para permitir que os usuários interajam com sua cena 3D, você pode adicionar controles:

// Importar OrbitControls
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';

// Criar controles
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true; // Adicionar efeito de amortecimento suave
controls.dampingFactor = 0.05;

// Atualizar o loop de animação
function animate() {
    requestAnimationFrame(animate);
    
    // Atualizar controles
    controls.update();
    
    renderer.render(scene, camera);
}

9. Carregando Modelos 3D

Você pode importar modelos criados em softwares como Blender:

import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';

const loader = new GLTFLoader();
loader.load(
    'path/to/model.gltf',
    // Chamado quando carregado
    function(gltf) {
        scene.add(gltf.scene);
    },
    // Chamado durante o carregamento
    function(xhr) {
        console.log((xhr.loaded / xhr.total * 100) + '% carregado');
    },
    // Chamado em caso de erro
    function(error) {
        console.error('Ocorreu um erro', error);
    }
);

10. Dicas de Depuração e Performance

Painel de Estatísticas

import Stats from 'three/examples/jsm/libs/stats.module.js';

const stats = new Stats();
document.body.appendChild(stats.dom);

function animate() {
    requestAnimationFrame(animate);
    stats.begin();
    
    // Seu código de animação aqui
    
    stats.end();
    renderer.render(scene, camera);
}

Dicas de Performance

Use BufferGeometry em vez de Geometry (que está obsoleto)
Reutilize materiais e geometrias sempre que possível
Defina renderer.powerPreference = 'high-performance' para melhor uso da GPU
Use Object3D.frustumCulled = true para ocultar objetos fora do campo de visão da câmera
Otimize a complexidade do modelo utilizando menos polígonos quando possível

Conclusão

Você agora aprendeu o básico do Three.js, desde a configuração do seu ambiente até a criação de cenas 3D interativas. Isso é apenas o começo—o Three.js oferece uma vasta gama de recursos para criar experiências web 3D impressionantes.

Para aprofundar seu conhecimento, explore a documentação oficial do Three.js e a galeria de exemplos. A comunidade também está ativa em fóruns e GitHub, fornecendo recursos e suporte para desenvolvedores de todos os níveis.

Lembre-se, a melhor maneira de aprender é experimentando. Comece com projetos simples e gradualmente avance para cenas mais complexas. Com prática e paciência, você estará criando experiências web 3D impressionantes em pouco tempo!

Divirta-se codificando com o Three.js!

botão