Revideo Three.js 3D 애니메이션

Revideo는 Three.js와 통합되어 3D 오브젝트·WebGL 효과를 비디오에 넣을 수 있다. Revideo의 tween() 헬퍼로 3D 씬을 부드럽게 애니메이션.

🎮 Three.js가 뭔가요

항목	설명
Three.js	가장 인기 있는 WebGL 기반 3D 라이브러리
용도	브라우저에서 GPU 가속 3D 그래픽
Revideo 통합	`<Three/>` 컴포넌트 (씬 + 카메라 + 렌더 루프 자동 관리)
활용 사례	로고 3D 회전, 입자 효과, 데이터 시각화, 360° 회전

🛠️ 기본 예시 — 회전하는 큐브

import {Txt, Three, makeScene2D} from '@revideo/2d';
import * as THREE from 'three';
import {tween, waitFor} from '@revideo/core';

export default makeScene2D('scene', function* (view) {
  const threeRef = createRef<Three>();
  const txtRef = createRef<Txt>();

  // 3D 캔버스 추가
  yield view.add(
    <Three width={1920} height={1080} ref={threeRef}>
      <Txt fill="black" fontFamily="Lexend" ref={txtRef} fontSize={80} />
    </Three>,
  );

  // 텍스트 + 큐브 등장
  yield* chain(
    txtRef().text('Revideo x 3D with Three.js', 1),
    all(
      txtRef().position.y(-300, 1, 0.5),
      threeRef().opacity(1, 0.5),
    ),
  );

  // 4초간 회전
  yield* tween(4, value => {
    threeRef().scene().children[0].rotation.set(0, linear(value, 0, 2 * 3.14), 0);
  });

  yield* waitFor(2);
});

🎯 핵심 API: `<Three/>` + `tween()`

`<Three>` Props

Prop	타입	설명
`width`	`number`	3D 캔버스 가로 (px)
`height`	`number`	3D 캔버스 세로 (px)
`ref`	`Ref<Three>`	Three 인스턴스 참조

`threeRef().scene()`

Three.js의 THREE.Scene 인스턴스에 직접 접근 가능. scene.add(mesh), scene.remove(mesh) 등 Three.js의 모든 API 사용 가능.

`tween(duration, callback)`

Revideo의 제너레이터 헬퍼. duration초 동안 매 프레임 callback(value) 호출 (value는 0~1).

yield* tween(4, value => {
  // value: 0 → 1 (4초에 걸쳐)
  mesh.rotation.y = linear(value, 0, 2 * Math.PI);  // 0 → 360도
  mesh.position.x = easeInOut(value, 0, 500);  // 0 → 500px
});

tween은 단순 트윈. 복잡한 3D 시뮬레이션은 delay() + 코드 한 줄로 직접 처리.

📦 큐브 한 개 추가하는 헬퍼

function* addRotatingCube(
  threeScene: THREE.Scene,
  size: number,
  x: number, y: number, z: number,
) {
  const geometry = new THREE.BoxGeometry(size, size, size);
  const material = new THREE.MeshNormalMaterial();
  const mesh = new THREE.Mesh(geometry, material);
  mesh.position.set(x, y, z);
  mesh.scale.set(1, 1, 1);
  threeScene.add(mesh);

  // 4초간 회전
  yield* tween(4, value => {
    mesh.rotation.set(0, linear(value, 0, 2 * 3.14), 0);
  });
}

이렇게 헬퍼 제너레이터로 빼두면 씬이 깔끔해진다.

💡 실전 활용 사례

사례	패턴
로고 3D 회전	GLTF 모델 로드 + 회전 tween
입자 효과	100개 큐브 + 랜덤 위치 + `delay`
데이터 시각화	3D 막대 그래프 + 값에 따라 scale tween
360° 회전 영상	카메라 위치 변경 + `tween(5, v => ...)`
WebGL 셰이더	Three.js의 `ShaderMaterial` + 커스텀 GLSL

⚠️ 주의사항

Three.js 의존성 추가 필요: npm i three @types/three (Three.js 자체는 Revideo에 peer dep)
WebGL 미지원 환경: 헤드리스 렌더에서 GPU 가속 없으면 매우 느림
메모리 누수: tween 종료 후 Three.js 객체 (geometry, material, mesh)를 scene.remove() 후 dispose() 권장
PNG export 시 투명도: Three.js 렌더는 보통 검정 배경. renderer.setClearColor(0x000000, 0)로 투명 처리

🆚 `<Three>` vs `<Img>` (사전 렌더)

	`<Three>`	`<Img>` (사전 렌더)
렌더 시점	비디오 렌더 시마다 실시간	미리 렌더해서 비디오에 삽입
인터랙션	✅ 다른 노드와 애니메이션 연동	❌ 정적 이미지
성능	느림 (GPU/CPU 많이 사용)	빠름 (이미지 디코딩만)
용도	동적 3D 효과	정적 3D 일러스트

추천: 정적인 3D 일러스트는 미리 렌더해서 <Img>로, 진짜 3D 애니메이션이 필요할 때만 <Three> 사용.

🎯 다음 단계

이전 손자 페이지: Revideo Rive 애니메이션
씬 작성: Revideo Scene Flow 이해하기 → Revideo 시작하기 → 이전 hub
렌더링: Revideo 렌더링 → 다음 hub

🔗 공식 리소스

Revideo Three.js: https://midrender.com/revideo/docs/guide/designing-animations/3d-animations-with-threejs
Three.js 공식: https://threejs.org
Three.js 예제: https://threejs.org/examples

상위 문서: ← Revideo 애니메이션 & 디자인 출처: Revideo 공식 문서 — 3D Animations with Three.js + Three.js 한글화 (2026-07-29) 공급사: Revideo (현 Midrender) / Three.js (mrdoob & contributors)

변경 이력

날짜	변경
2026-07-29	초안 작성 — `<Three/>` + `tween()` + 회전 큐브 예제 + Three.js vs 사전렌더 비교 한글화
2026-07-29	메타데이터 블록을 본문 하단으로 이동