[Three.js] Three.js

Three.js

들어가며

• 웹 브라우저에서 3D 그래픽을 쉽게 구현할 수 있게 해주는 라이브러리인 Three.js에 대해 간단하게 정리해본다.

 

Three.js

개념

• 웹 브라우저에서 3D 그래픽을 쉽게 구현할 수 있도록 도와주는 JavaScript 라이브러리
• 웹에서 3D 콘텐츠를 보여주기 위해 거의 필수로 사용되는 도구

Three.js – JavaScript 3D Library

 

핵심 개념

① Scene (장면)

• 모든 3D 객체가 배치되는 무대 공간
• 나무, 빛, 카메라 등 모든 객체는 이 @scene@에 추가되어야 화면에 렌더링된다.
• 여러 객체를 그룹화하거나 배경색, 안개 효과 등을 설정할 수 있다.

const scene = new THREE.Scene();

// 배경색을 검정색으로 설정
scene.background = new THREE.Color(0x000000);

 

② Camera (카메라)

• 실제로 장면을 바라보는 눈 역할을 한다.
• 주로 사용하는 카메라로는 2가지가 있다.
  • @PerspectiveCamera@ : 원근감 있는 일반적인 카메라 (현실과 유사)
  • @OrthographicCamera@ : 평행 투영 카메라 (게임 UI나 CAD 등에서 사용)

const camera = new THREE.PerspectiveCamera(
  75,                                            // ✅ 시야각(FOV)
  window.innerWidth / window.innerHeight,        // ✅ 종횡비
  0.1,                                           // ✅ 가까운 클리핑 거리
  1000                                           // ✅ 먼 클리핑 거리
);

// 카메라를 z축 방향으로 이동
camera.position.z = 5;

 

③ Renderer (렌더러)

• @scene@과 @camera@를 기반으로 실제 화면에 3D 그래픽을 그려주는 엔진
• 일반적으로 WebGLRenderer를 사용한다. (GPU 가속)
• DOM 요소(@<canvas>@)에 결과를 그린다.

const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);

// 캔버스를 페이지에 추가
document.body.appendChild(renderer.domElement);

 

④ Mesh (메쉬 = 형태 + 재질)

• 보이는 3D 객체 그 자체
• 2가지로 구성된다.
  • Geometry : 모양 (정육면체, 구, 평면 등)
  • Material : 표면 특성 (색, 반사, 투명도 등)

const geometry = new THREE.BoxGeometry(1, 1, 1); // 가로(W), 세로(H), 깊이(D)
const material = new THREE.MeshStandardMaterial({ color: 0xff0000 });

const cube = new THREE.Mesh(geometry, material);

// 장면에 추가
scene.add(cube);

 

⑤ Light  (조명)

• 3D 공간에 빛을 추가하여 재질과 그림자가 자연스럽게 보이게 해준다.
• 주로 사용되는 조명의 종류는 다음과 같다.
  • @AmbientLight@ : 전체 공간에 퍼지는 부드러운 빛
  • @PointLight@ : 특정 위치에서 퍼지는 빛 (예: 전구의 빛)
  • @DirectionalLight@ : 태양빛처럼 한 방향에서 비추는 빛
  • @SpotLight@ : 특정 각도로 비추는 스포트라이트

const light = new THREE.DirectionalLight(0xffffff, 1); // 흰색, 밝기 1
light.position.set(5, 10, 7);

// 장면에 추가
scene.add(light);

 

⑥ Controls (조작 컨트롤)

• 마우스나 터치로 카메라를 움직일 수 있게 해주는 유틸리티
• 대표적인 도구
  • @OrbitControls@ : 마우스로 회전/줌/이동
  • @FlyControls@ : 비행 시점
  • @FirstPersonControls@ : 1인칭 시점
• 해당 기능을 사용하려면 별도로 @import@를 해주어야 한다.

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

const controls = new OrbitControls(camera, renderer.domElement);

// 부드러운 회전 기능 설정
controls.enableDamping = true;

 

주요 기능

• 박스, 구, 원기둥, 평면, 텍스처 등 다양한 3D 객체 표현
• Ambient, Point, Directional, Spot 등의 조명 효과 표현
• 그림자와 반사 표현
• 마우스/키보드로 조작 가능
• @.obj@, @.gltf@, @.fbx@ 등 다양한 3D 파일 불러오기
• 블러, 그림자, 반사 등 고급 효과 표현 (포스트 프로세싱)

 

사용되는 분야

• 게임, 메타버스
• 3D 제품 뷰어 (전자상거래)
• 건축/인테리어 시뮬레이션
• 데이터 시각화
• 인터랙티브 아트

 

공식 문서

three.js docs

 

사용 예제

import * as THREE from 'three';

// 1. Scene 생성
const scene = new THREE.Scene();

// 2. Camera 생성
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
camera.position.z = 5;

// 3. Renderer 생성
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// 4. Mesh (도형 + 재질) 만들기
const geometry = new THREE.BoxGeometry(); // 정육면체
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 }); // 초록색 재질
const cube = new THREE.Mesh(geometry, material);
scene.add(cube); // 씬에 추가

// 5. 애니메이션 루프
function animate() {
  requestAnimationFrame(animate);
  cube.rotation.x += 0.01; // 회전
  cube.rotation.y += 0.01;
  renderer.render(scene, camera);
}
animate();

 

리액트(React)에서 Three.js 사용하기

• 리액트(React)에서 Three.js를 사용하는 방법은 다음과 같이 2가지 방법이 있다.

 

방법 ① : Three.js 직접 사용하기

• 리액트 프로젝트 안에서 DOM이 준비된 후, Three.js를 수동으로 초기화하는 방법이다.
• @useRef@로 @<div>@ 요소를 가져온 후, 해당 요소에 WebGL 캔버스를 삽입한다.

 

사용 예제 코드

import { useRef, useEffect } from 'react';
import * as THREE from 'three';

const MyThreeScene = () => {
  const mountRef = useRef(null);

  useEffect(() => {
    // (1) 기본 설정
    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(
      75,
      mountRef.current.clientWidth / mountRef.current.clientHeight,
      0.1,
      1000
    );
    camera.position.z = 5;

    const renderer = new THREE.WebGLRenderer({ antialias: true });
    renderer.setSize(mountRef.current.clientWidth, mountRef.current.clientHeight);
    mountRef.current.appendChild(renderer.domElement);

    // (2) 오브젝트 생성
    const geometry = new THREE.BoxGeometry();
    const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
    const cube = new THREE.Mesh(geometry, material);
    scene.add(cube);

    const light = new THREE.DirectionalLight(0xffffff, 1);
    light.position.set(3, 3, 3);
    scene.add(light);

    // (3) 애니메이션
    const animate = () => {
      cube.rotation.x += 0.01;
      cube.rotation.y += 0.01;
      renderer.render(scene, camera);
      requestAnimationFrame(animate);
    };
    animate();

    // (4) 클린업
    return () => {
      mountRef.current.removeChild(renderer.domElement);
    };
  }, []);

  return (
    <div
      ref={mountRef}
      style={{ width: '100%', height: '400px' }}
    />
  );
};

export default MyThreeScene;

 

방법 ② : ＠react-three/fiber 라이브러리(R3F) 사용하기

• @＠react-three/fiber@(R3F)는 Three.js를 리액트 방식으로 완전히 래핑한 라이브러리이다.
• 리액트에서 사용 친화적이고, 간단하게 Three.js 기능을 구현할 수 있다.

 

라이브러리 설치하기

$ npm install three @react-three/fiber    # yarn add three @react-three/fiber

 

함께 사용하는 라이브러리

• 아래의 라이브러리들을 함께 사용할 수 있다.

라이브러리	설명
@＠react-three/drei@	@OrbitControls@, @Text@, @Environment@ 등 자주 쓰는 유틸리티 제공
@three-stdlib@	@GLTFLoader@ 등 로더 기능을 @fiber@에서 쓰기 위한 라이브러리
@＠react-three/postprocessing@	후처리 효과 (블룸, 노이즈 등)
@＠react-three/flex@	- Three.js 안에서 CSS Flexbox 스타일 레이아웃 구현 가능 - 구현 가능 기능 예 : Flexbox처럼 3D 텍스트와 버튼을 정렬
@＠react-three/cannon@	물리 엔진 (Cannon.js 기반). 중력, 충돌, 힘 적용 가능
@＠react-three/rapier@	- 고성능 물리 엔진 Rapier.js 바인딩 (cannon보다 빠르고 정밀함) - 구현 가능 기능 예 : 3D 캐릭터가 중력 따라 떨어지고 장애물과 부딪히는 효과
@＠react-three/keyboard-controls@	키보드 조작을 쉽게 설정할 수 있는 훅
@＠react-three/interactive@	오브젝트에 onClick, onHover 같은 인터랙션 처리 지원
@leva@	- 실시간 UI 컨트롤 패널 - 조명 밝기, 위치 등 즉석에서 값 조정 - 구현 가능 기능 예 : UI 슬라이더로 빛의 세기를 조절하면서 실시간 테스트
@three/examples/jsm@	OrbitControls, GLTFLoader, EffectComposer 등 기본 Three.js 예제 기능들
@three-mesh-bvh@	고속 레이캐스팅 및 충돌 감지용 Bounding Volume Hierarchy(BVH)
@three-pathfinding@	- 3D 공간 내 경로 탐색(NavMesh) 기능 제공 - 구현 가능 기능 예 : AI 캐릭터가 NavMesh를 따라 움직임
@troika-three-text@	- 고품질 3D 텍스트 렌더링 (TrueType 폰트 지원) - 구현 가능 기능 예 : 한글, 영어 모두 매끄럽게 표현되는 3D 텍스트
@three-nebula@	입자 효과(파티클) 시스템
@threejs-toys@	실험적/예술적 효과를 쉽게 적용할 수 있는 유틸 모음

 

공식 문서

Introduction - React Three Fiber

 

사용하기

사용 예제 코드

import { Canvas } from '@react-three/fiber';

const Box = () => {
  return (
    <mesh rotation={[0.4, 0.2, 0]}>
      <boxGeometry />
      <meshStandardMaterial color="orange" />
    </mesh>
  );
};

const MyCanvas = () => {
  return (
    <Canvas style={{ width: '100%', height: '400px' }}>
      <ambientLight intensity={0.5} />
      <directionalLight position={[3, 3, 3]} />
      <Box />   // ✅
    </Canvas>
  );
};

export default MyCanvas;

 

Three.js를 처음 배우는 경우, 방법①(기본 Three.js + useEffect 방식)으로 먼저 개념을 익히고, 익숙해졌거나 프로젝트에 사용할 경우 방법②(＠react-three/fiber + drei 조합)를 이용하여 개발을 진행한다.

 

참고 사이트

Three.js – JavaScript 3D Library

Introduction - React Three Fiber