# readme-2601231158

> A brief description, shown to the model to help it understand when to use this skill

- Author: sonminchan
- Repository: pabian84/lg-electronics-repair-3d
- Version: 20260203090826
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/pabian84/lg-electronics-repair-3d
- Web: https://mule.run/skillshub/@@pabian84/lg-electronics-repair-3d~readme-2601231158:20260203090826

---

---
name: readme-2601231158
description: A brief description, shown to the model to help it understand when to use this skill
---

##  ■■ Description ■■
- 
**1. 이징 불일치 해결 (line 243)**
- `smoothProgress = eased` 로 통일하여 카메라 위치와 타겟 시선에 동일한 이징 적용
**2. 급격한 경로 전환 해결 (lines 178-216)**
- `QuadraticBezierCurve3`로 안정적인 곡선 생성
- 제어점을 완만하게 배치: `(start + end) / 2`, 높이는 `maxDim * 0.3` 오프셋
- 모든 점의 유효성을 `.isVector3`로 검증
- 거리 차이가 작으면 직선 이동으로 fallback
**3. Up-Vector 급격한 전환 해결 (lines 271-275)**
- 90% 임계값 제거, 0%~100% 전체 구간에 Cubic ease-out 적용
- 마지막 순간 급격한 회전 없이 자연스러운 전환
**4. 안전장치 추가**
- `isVector3` 검증을 통해 undefined 점 방지
- `distanceToSquared < 0.0001` 시 직선 이동 fallback
**GSAP를 사용하여 복잡한 이징효과인 카메라 이동 구현 할 수도 있음**
- 현재 코드는 camera.position에 따라 실시간으로 lookDir를 계산하므로, 카메라가 노드에 가까워질 때 UP 벡터가 급격하게 변하고 있다.


##  ■■ 카메라 이동시 의도한 궤적을 따라 이동하지 않는 문제 ■■
- 카메라 컨트롤러를 사용할 때, 사용자가 의도한 **Bezier 곡선 궤적**과 
  실제 **카메라 이동**이 일치하지 않는(직선으로 움직이거나 궤적에서 벗어나는) 문제가 발생할 수도 있다.
## 1. 문제 원인
- 이 현상의 핵심 원인은 **컨트롤러의 자체 보간(Damping/Inertia) 로직**이 프레임마다 
  강제로 주입된 좌표(`position.copy`)를 '급격한 변화'로 인식하여 
  부드럽게(직선에 가깝게) 보정하려고 시도하기 때문이다.
- 이를 해결하기 위해 시네마틱 애니메이션이 실행되는 동안 **임시로 Damping을 비활성화**하여, 
  카메라가 곡선 좌표를 그대로 따라가도록 강제하는 **Enterprise-grade 솔루션** 방식을 추천한다.

## ■■ (Ref) GSAP를 사용한 복잡한 이징 효과 및 카메라이동 구현 ■■
- GSAP(GreenSock Animation Platform) 를 활용한 **복잡한 이징(Easing) 기반의 카메라 이동 구현**은 
  엔터프라이즈급 3D 웹 애플리케이션에서 매우 권장되는 방식이다. 
- 특히 **정밀한 타임라인 제어**와 **물리 법칙을 모사한 부드러운 연출**이 필요한 경우 GSAP는 강력한 솔루션이 된다.
## 1. GSAP 방식 vs 수동 구현 방식 차이점
| 구분                  | GSAP 방식 (라이브러리 활용)                                                                    | 수동 구현 방식 (lerp / requestAnimationFrame)                                              |
| --------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| 이징(Easing)의 다양성 | Elastic, Bounce, CustomEase 등 수십 가지의 정교한 수학적 곡선을 즉시 적용 가능.                | lerp는 주로 선형이며, 곡선 적용을 위해서는 직접 수학 공식(Cubic, Sine 등)을 작성해야 함.   |
| 타임라인 제어         | 애니메이션의 일시정지, 역재생, 특정 시점 연결(Chaining)이 매우 직관적임.                       | 각 상태값과 경과 시간(elapsed time)을 직접 변수로 관리해야 하므로 로직이 복잡해짐.         |
| 성능 최적화           | 자체적인 최적화 엔진을 통해 GPU 부하를 최소화하고 프레임 드랍 발생 시 보정 로직 작동.          | 브라우저의 ref 성능에 의존하며, 프레임이 튀는 현상(Jitter)을 방지하기 위한 추가 로직 필요. |
| 중복 실행 처리        | 새로운 애니메이션 시작 시 기존 애니메이션을 자동으로 덮어쓰거나(Overwrite) 부드럽게 연결 가능. | 이전 루프를 명시적으로 cancelAnimationFrame 하지 않으면 애니메이션이 겹쳐 떨림 발생 가능.  |


## ■■ 실제 카메라가 이동할 때 그 곡선을 타지 않는 현상 은 주로 다음 두 가지 기술적 원인 때문이다. ■■
1. **애니메이션 루프 내 `cameraControls.update()`의 자동 보간 간섭**: 
	- 많은 카메라 컨트롤 라이브러리(CameraControls, OrbitControls 등)는 
	  자체적인 `damping`(감쇠)이나 `smoothing` 기능을 가지고 있어, 
	  `position.copy()`로 강제 설정한 값을 다시 자신들의 내부 로직으로 덮어씌워 직선처럼 보이게 만들 수 있다.
2. **`lerp`와 `Bezier`의 혼용**: 
	- 코드 내에서 위치는 Bezier로 잡더라도, `cameraControls`의 내부 상태를 업데이트하는 방식이 선형적일 경우, 
	  곡선 궤적이 상쇄된다.
3. **궤적이 완만하게 그려지는 이유:**
	- 시작점과 끝점 사이의 **중간 제어점(Control Point)** 이 두 지점과 너무 가깝거나 
	  직선상에 가깝게 배치되어 있기 때문이다. 
	- 곡률을 높이려면 제어점을 진행 방향의 수직 벡터나 카메라의 상단(Up) 방향으로 더 멀리 밀어내야 한다.
4. **선형 이동 느낌 해결 (Path Following):**
	- 카메라가 곡선을 따라가지 않는 것처럼 느껴지는 이유는 애니메이션 루프 내에서 
	  곡선의 좌표를 샘플링(`curve.getPoint(t)`)하지 않고, 
	  단순히 시작/끝 위치를 `lerp`(선형 보간)하고 있기 때문일 가능성이 크다.
### 4-1. 해결 방법
- 이를 해결하기 위해, **카메라 컨트롤의 내부 보간을 잠시 끄고(damping 무시)**, 
  **Bezier 곡선 위의 좌표를 프레임 단위로 강제 주입** 하도록 
  `moveCameraCinematic`의 로직을 수정해야 한다.


## ■■ (Ref) 카메라가 노드를 비출때 노드를 바라보는 방향이 일관되지 않는 문제 ■■
## 1. 발생 원인
1. **상대적 방향 벡터 사용**: 
	- `direction`이 `(0, -1, 0)` 또는 `(0.5, -1, 0.5)`와 같이 고정된 월드 좌표계 벡터를 사용하고 있을 수도 있다.
	- 만약 대상 노드(예: 댐퍼)가 모델 내에서 회전되어 있다면, 월드 기준 벡터는 노드의 '정면'을 보장하지 못한다.
2. **노드 로컬 좌표계 미반영**: 
	- 노드가 기울어져 있거나 회전된 상태라면, 해당 노드의 `worldQuaternion`을 활용하여 
	  노드 기준의 '앞(Forward)' 또는 '위(Up)' 방향을 계산해야 하지만 
	  현재는 일부 UP 벡터 계산에만 제한적으로 사용되고 있을 수도 있다.
3. **UP 벡터 계산의 불안정성**: 
	- `crossVectors(nodeY, lookDir)`를 통해 UP 벡터를 계산할 때, 
	  두 벡터가 평행에 가까워지면 결과가 부정확해져 카메라가 뒤집히거나 돌아가는 현상이 발생할 수도 있다.
## 2. 개선 계획
1. **노드 로컬 기준 방향 계산**: 
	- 노드의 `worldQuaternion`을 추출하여, 노드의 로컬 Z축(또는 특정 축)을 기준으로 
	  카메라의 목적지(`endPos`)를 계산하도록 수정
2. **일관된 뷰포트 보장**: 
	- `LEFT_DOOR_DAMPER_COVER_BODY_NODE`과 같은 특정 부품에 대해서는 해당 부품이 가장 잘 보이는 로컬 오프셋을 정의하여 적용
3. **안전한 UP 벡터 설정**: 
	- 카메라의 `up` 벡터를 설정할 때 노드의 월드 UP 방향을 우선적으로 고려하고, 
	  예외 상황(평행 벡터)에 대한 처리를 강화