오류메시지 없을때 오류 찾기 (1) Leaflet 지도와 Three.js 렌더러 간의 충돌 문제

 
 

 

🔍 1차: 예상한 동작과 실제 동작을 비교하여, 문제 범위 좁히기

• 기대한 결과: 3D 오브젝트가 지도 위에 표시됨
• 실제 결과: 3D 오브젝트가 표시되지 않음

 

🔍 2차: 주요 함수들 디버깅

 1) threeContainer가 map.getContainer() 안에 추가되었는지 확인
 2) renderer가 정상적으로 생성되는지 확인
 3) animate() 함수가 실행되는지 확인
 4) camera와 scene이 제대로 설정되었는지 확인

 

🔍 3차: 함수는 정상 동작한다? => 렌더링 리스트 체크

(1) 요소가 DOM에 추가되었는가? : Elements 탭
      document.querySelector("canvas") 실행해 보고 null이 나오면 Three.js가 추가되지 않은 것.
(2) Three.js 렌더링이 실행되고 있는가?
       Three.js는 애니메이션을 계속 실행하기 때문에 requestAnimationFrame()이 실행되고 있어야한다.
(3) 3D 객체가 추가되었는가?
       Three.js에서 객체를 생성했지만 scene.add(mesh)를 호출하지 않으면 화면에 보이지 않아.
(4) 지도 위에 Three.js가 올바르게 배치되었는가?
       Three.js가 Leaflet의 MapContainer 아래에 있으면 지도에 가려질 수 있다.
        Elements 탭에서 z-index 값 확인. 🗝️문제발견!🗝️
 
 

---

 

📒 4. 학습 포인트

3D오브젝트에 z-index값을 명시하여, 문제 해결함

 

[ 문제 핵심 원인 ]

🔥 Leaflet 지도와 Three.js 렌더러 간의 충돌 문제

 

• 웹 브라우저는 HTML 요소들을 여러 레이어로 쌓아서 표시한다. 이때 z-index라는 CSS 속성이 각 요소가 어느 레이어 위에 에 위치할지를 결정한다. z-index 값이 높을 수록 위에 표시된다. 
• 이런 레이어 관련 문제는 웹 개발에서 자주 발생하는 문제 중 하나다. 특히 지도나 3D 그래픽과 같은 복잡한 시각적 요소들을 다룰 때는 각 레이어의 z-index 값을 명시적으로 관리하는것이 중요하다.

 
 

[ 문제 발생 과정 ]

 

1. 초기 렌더링 단계

const threeContainer = document.createElement("div");
threeContainer.style.position = "absolute";

 

• div 요소가 생성되고 position이 absolute로 설정됨
• 이 시점에서 z-index가 설정되지 않아 기본값을 사용함. => auto 또는 0

 

2. 레이어 배치 단계

map.getContainer().appendChild(threeContainer);

• Three.js 컨테이너를 지도 컨테이너의 자식으로 추가함
• 하지만 z-index가 낮아서 지도 레이어 아래에 배치됨.
• Leaflet 지도는 기본적으로 높은 z-index 값을 가지고 있음 (보통 기본값은 400정도) 

 

3. 렌더링 결과

const renderer = new THREE.WebGLRenderer({ alpha: true });
renderer.setSize(window.innerWidth, window.innerHeight);
threeContainer.appendChild(renderer.domElement);

• Three.js 렌더러가 생성되고 컨테이너에 추가된다.
• 렌더러는 정상적으로 동작하지만, 컨테이너가 지도 아래에 있어서 보이지 않는다.

TIP: Leaflet은 기본적으로 높은 z-index를 값을 가진다.

/* 출처: Leaflet 소스코드 leaflet.css */
/* Leaflet의 주요 레이어들의 기본 z-index 값 */

.leaflet-pane { z-index: 400; }
.leaflet-tile-pane { z-index: 200; }
.leaflet-overlay-pane { z-index: 400; }
.leaflet-shadow-pane { z-index: 500; }
.leaflet-marker-pane { z-index: 600; }
.leaflet-tooltip-pane { z-index: 650; }
.leaflet-popup-pane { z-index: 700; }

---

🚀 5. 사고 확장(비슷한 문제들)

 

• Three.js + React 환경에서 생기는 대표적인 문제들
  → z-index, position: absolute, display: none 문제로 인해 canvas가 가려지는 경우가 많음.
• Leaflet 내부에서 HTML 요소를 오버레이할 때 생기는 문제들
  → Leaflet의 Pane 개념과 z-index 문제 때문에 Three.js canvas가 보이지 않는 경우가 있음.
• 애니메이션 실행되는데 보이지 않는 문제
  → requestAnimationFrame()은 실행되지만 카메라 위치 문제로 인해 객체가 화면에 나오지 않는 경우.

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
출처

• Three.js 공식 문서 : Three.js Getting Started
• Three.js 공식 문서 : WebGLRenderer
• Three.js 공식 문서 : Scene Graph Dubugging
• React-Leaflet 공식 문서 : React-Leaflet Guide
• React-Leaflet 공식 문서 : Custom Layers
• Leaflet 공식 문서 : leaflet.css