드래그로 이동, 오른쪽 또는 Shift 드래그로 회전, 휠로 확대좌우로 끌어 이동, 두 손가락으로 확대와 회전, 위아래로 밀면 페이지 스크롤
마우스: 드래그로 지도를 옮기고, 오른쪽 버튼이나 가운데 버튼, 또는 Shift를 누른 채 드래그하면 회전과 기울기가 바뀝니다. 가까이 확대하면 도로명과 일반 건물이 나타납니다. 휠로 확대하면 시선이 낮아지고, 축소하면 위에서 내려다봅니다. 터치: 한 손가락으로 좌우로 끌면 지도가 움직이고, 위아래로 밀면 페이지가 스크롤됩니다. 두 손가락으로 확대와 회전을 합니다. 키보드: 지도를 선택한 뒤 방향키로 이동, +/−로 확대·축소, Shift와 방향키로 회전·기울기, Home으로 전체 보기. 건물이나 장소 이름을 누르면 정보를 볼 수 있습니다.
이 기술로 무엇을 할 수 있을지 먼저 적고, 이어서 우리동네 지도를 데이터 준비부터 화면까지 만들어 간 순서대로, 실제 코드와 함께 적었습니다.
1. 지도를 직접 그리면 무엇을 할 수 있을까요
웹에서 지도를 띄울 때는 보통 지도 SDK를 씁니다. 넓은 범위를 정확하게 보여 주는 데는 이만한 도구가 없습니다. 하지만 지도를 서비스의 얼굴로 쓰고 싶을 때는 아쉬움이 남습니다. 어느 서비스의 지도든 비슷한 모습이 되고, 건물 하나를 주인공처럼 다루기도 어렵습니다.
범위가 정해진 공간이라면 이야기가 달라집니다. 3D 장면을 직접 그리면 지도를 일러스트처럼 꾸밀 수 있고, 건물 하나하나를 누르고 띄우고 강조할 수 있는 물건으로 다룰 수 있습니다. 저는 대학 캠퍼스나 테마파크 안내도, 축제 행사장 지도, 동네 상권이나 관광지를 소개하는 페이지 같은 곳에 이런 지도가 어울릴 것 같다고 생각했습니다.
그래서 제가 사는 광명시 하나를 골라 직접 만들어 봤습니다. 확인하고 싶었던 건 두 가지입니다. 공개된 OpenStreetMap 데이터만으로 어느 정도의 지도가 나오는지, 그리고 도시 하나 분량의 건물을 브라우저가 감당할 수 있는지입니다.
2. 지도 SDK 대신 Three.js로 시작한 이유
우리동네 지도는 광명시 한 곳만 보여 주는 입체 일러스트 지도입니다. 건물 윤곽을 누르면 그 모양 그대로 떠오르고, 가까이 확대하면 일반 건물이 솟아오르는 표현이 필요했습니다. 이 글에서는 그 지도를 어떤 순서로 만들었는지, 각 단계에서 어떤 코드를 썼고 어디서 막혔는지를 적습니다. 웹 지도 라이브러리를 써 본 적이 있고, Three.js는 처음이거나 가볍게 써 본 정도인 독자를 염두에 두었습니다.
완성된 첫 화면. 광명시 경계 모양의 지형 판 위에 건물, 도로, 숲이 올라가 있습니다.
타일 기반 지도 SDK는 어디든 보여 주는 대신, 표현은 스타일 사양이 허락하는 범위 안에서만 바뀝니다. 이 프로젝트는 지도의 범위가 광명시 하나로 정해져 있고, 건물 하나하나를 선택하고 강조하는 일이 핵심이었습니다. 그래서 장면(scene), 카메라(camera), 렌더러(renderer)를 직접 구성하는 Three.js를 골랐습니다.
대신 지도 SDK가 대신해 주던 일을 전부 직접 해야 합니다. 위경도를 장면 좌표로 바꾸고, 지형을 만들고, 카메라를 지도처럼 움직이게 하고, 글자를 얹는 일입니다. 이어지는 단계가 곧 그 목록입니다. 먼저 뼈대가 되는 세 가지부터 만듭니다.
src/components/lab/map-engine.ts
const scene = new T.Scene(); scene.background = new T.Color("#f0eadb");const camera = new T.PerspectiveCamera(40, 1, 0.1, 700);const renderer = new T.WebGLRenderer({ antialias: true, alpha: false, powerPreference: "low-power" });renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));// ...host.appendChild(canvas);
화면 비율은 처음에 1로 두고, 컨테이너 크기가 정해지면 ResizeObserver가 알려 주는 값으로 다시 맞춥니다. 픽셀 비율은 2로 제한했습니다. 고해상도 화면에서 3배 비율까지 그리면 그림자까지 포함해 부담이 커지기 때문입니다.
3. 데이터는 미리 만들어 정적 파일로 둔다
지도의 재료는 OpenStreetMap(OSM) 데이터입니다. 행정경계, 도로, 하천, 녹지, 건물 윤곽과 장소 좌표를 모두 여기서 가져옵니다. 런타임에 OSM API를 부르지 않고, 빌드 전에 Python 스크립트로 받아서 가공한 JSON 파일만 사이트에 올립니다. 페이지를 열 때마다 외부 서버에 의존하지 않고, 사용 정책이 엄격한 API에 부담을 주지 않기 위해서입니다.
OSM의 지도 API는 한 번에 받을 수 있는 영역 크기가 제한되어 있어서, 광명시 일대를 가로 3칸, 세로 4칸으로 나눠 받습니다. 요청 사이에는 1초를 쉬고, 받은 응답은 .cache 폴더에 저장해 두어 같은 구역을 두 번 받지 않습니다.
scripts/build-gwangmyeong-map.py
def fetch(): CACHE.mkdir(parents=True, exist_ok=True) for ix in range(3): for iy in range(4): path = CACHE / f'{ix}-{iy}.osm' if path.exists(): continue left, bottom = 126.825 + ix * .025, 37.400 + iy * .024 url = f'https://api.openstreetmap.org/api/0.6/map?bbox={left:.6f},{bottom:.6f},{left+.025:.6f},{bottom+.024:.6f}' req = urllib.request.Request(url, headers={'User-Agent': 'GwangmyeongLab/1.0 (city map build)'}) with urllib.request.urlopen(req, timeout=60) as response: data = response.read() ET.fromstring(data) path.write_bytes(data) time.sleep(1)
받은 구역들을 합쳐 시 경계 안에 들어오는 것만 남깁니다. 점이 다각형 안에 있는지는 광선 투사(ray casting) 방식으로 판단합니다. 점에서 오른쪽으로 반직선을 그었을 때 경계 변과 몇 번 만나는지 세어서, 홀수면 안쪽입니다.
scripts/build-gwangmyeong-map.py
def inside(point, ring): x, y = point hit = False for a, b in zip(ring, ring[1:]): if (a[1] > y) != (b[1] > y) and x < (b[0]-a[0]) * (y-a[1]) / (b[1]-a[1]) + a[0]: hit = not hit return hit
건물은 2,422채가 남았습니다. 문제는 높이였습니다. OSM에는 높이(height) 태그가 있는 건물이 832채, 층수(building:levels)만 있는 건물이 84채이고, 나머지 1,506채는 아무 정보가 없습니다. 지도를 입체로 보이게 하려면 높이가 필요하므로 정보가 없는 건물은 9m로 두되, 데이터에 heightSource를 따로 기록해 실제 값, 층수로 추정한 값, 기본값을 구분했습니다. 건물을 선택하면 상세 정보에 "높이 정보가 없어 9m로 표현한 건물"이라고 밝히는 것도 이 기록 덕분입니다.
도로는 이름이 필요합니다. 처음에는 도로의 종류(kind)와 좌표만 저장했다가, 확대했을 때 도로명을 보여 주려고 스크립트를 고쳤습니다. 모든 도로에 이름을 붙이면 파일이 커지므로 고속도로부터 3차선 도로까지만 name을 담았습니다.
scripts/build-gwangmyeong-landscape.py
roads.append({'kind':t['highway'],'points':points,**({'name':t['name']} if t.get('name') and t['highway'] in ['motorway','trunk','primary','secondary','tertiary'] else {})})
결과는 경계(255KB), 도로와 녹지와 하천(520KB), 건물(약 5MB) 세 개의 JSON입니다. 장소 301곳의 좌표와 분류는 src/content의 JSON으로 코드와 함께 관리합니다.
4. 위경도를 장면 좌표로 바꾸기
Three.js의 장면은 미터나 도 단위가 아니라 임의의 단위를 씁니다. 위경도를 그대로 쓰면 가로와 세로의 실제 길이가 달라 모양이 찌그러집니다. 위도 37도 부근에서 경도 1도의 실제 길이는 위도 1도보다 짧기 때문입니다. 그래서 광명시 한가운데를 원점으로 하는 간단한 투영 함수를 만들었습니다.
위도 1도는 약 111.3km이므로 장면 한 칸을 100m로 보면 1113.2가 됩니다. 경도에는 cos(위도)를 곱해 위도에 따라 줄어드는 길이를 맞춥니다. 반환하는 두 번째 값은 위도에 음수를 곱한 값인데, 장면에서 z축이 화면 앞쪽(남쪽)으로 자라기 때문입니다. 북쪽이 위로 보이는 지도를 만들려면 이 부호가 필요합니다. 광명시는 장면 안에서 가로 68, 세로 108칸(6.8km x 10.8km)의 상자 안에 들어갑니다.
정밀한 지도 투영(예: UTM)이 아니라 이 정도로 단순하게 간 이유는 범위가 작기 때문입니다. 도시 하나의 크기에서는 평면 근사의 오차가 눈에 띄지 않고, 좌표 변환 라이브러리를 들이지 않아도 됩니다. 범위가 훨씬 넓은 지도에서는 쓸 수 없는 방법입니다.
5. 지형 판과 바닥 무늬 만들기
지도의 바닥은 광명시 경계 모양의 판입니다. 경계 좌표를 투영해 Shape로 만들고, 위로 돌출시켜(ExtrudeGeometry) 두께가 있는 판을 만듭니다. 판 윗면에는 도로와 녹지를 그린 그림을 씌워야 하므로 윗면만 따로 평면(ShapeGeometry)으로 하나 더 만듭니다.
src/components/lab/map-engine.ts
const shape = new T.Shape(projected.map(([x, z]) => new T.Vector2(x, -z)));const slabGeometry = new T.ExtrudeGeometry(shape, { depth: 2.35, bevelEnabled: false });slabGeometry.rotateX(-Math.PI / 2);slabGeometry.translate(0, -2.35, 0);// ...const surfaceGeometry = new T.ShapeGeometry(shape);surfaceGeometry.rotateX(-Math.PI / 2);
Shape는 2D 평면(x, y)에서 정의되고 ExtrudeGeometry는 z 방향으로 늘어납니다. 우리가 원하는 것은 바닥이 땅(xz 평면)에 놓이고 높이가 y로 자라는 모양이므로 rotateX(-Math.PI / 2)로 눕힙니다. 이때 z가 반전되기 때문에 Shape에 넣는 좌표는 -z로 미리 뒤집어 둡니다. 판은 아래로 2.35만큼 내려서 지면 높이를 0으로 유지합니다.
바닥 무늬는 2D 캔버스에 그립니다. 2,048 x 3,072 픽셀 캔버스에 숲, 공원, 시가지, 물 순서로 면을 칠하고, 하천은 선으로 긋고, 일반 건물은 연한 평면으로 찍고, 마지막에 도로를 그립니다. 도로는 같은 선을 두 번 긋습니다. 먼저 굵게 어두운 색으로 긋고, 그 위에 한 칸 가는 밝은 색으로 한 번 더 그어 테두리가 있는 길처럼 보이게 합니다.
카메라 조작은 Three.js 예제에 들어 있는 OrbitControls를 바탕으로 했습니다. 기본 동작은 왼쪽 드래그가 회전이고 오른쪽 드래그가 이동인데, 지도에서는 반대가 자연스럽습니다. 그래서 버튼을 바꾸고, 이동이 화면 방향이 아니라 지면을 따라가도록 screenSpacePanning을 껐습니다. 이 옵션을 끄지 않으면 기울어진 상태에서 드래그할 때 지도가 위아래로 떠오릅니다.
모바일에서는 문제가 하나 더 있었습니다. OrbitControls는 캔버스에 touch-action: none을 직접 넣어서 모든 터치를 가져갑니다. 지도가 화면 대부분을 차지하는 모바일에서는 지도 위에서 손가락을 미는 순간 페이지 스크롤이 막힙니다. 그래서 터치 화면(pointer: coarse)에서만 pan-y로 바꿔, 위아래 밀기는 페이지 스크롤에 돌려주고 좌우 이동과 두 손가락 확대, 회전만 지도가 받게 했습니다. CSS로 바꾸면 인라인 스타일에 밀려 적용되지 않기 때문에 컨트롤을 만든 직후 코드에서 바꿉니다.
휠은 별도로 가로챘습니다. OrbitControls의 휠은 거리만 바꾸지만, 지도에서는 확대할수록 시선이 낮아지고 축소할수록 위에서 내려다보는 쪽이 더 자연스럽습니다. 거리가 바뀌는 만큼 기울기도 함께 바꾸는 함수를 따로 만들고, 컨트롤보다 먼저 휠 이벤트를 받아(capture: true) 컨트롤의 처리를 막았습니다.
거리에 지수 함수를 쓴 것은 확대 비율을 일정하게 느끼게 하려는 선택입니다. 가까울 때 한 칸 확대하는 것과 멀 때 한 칸 확대하는 것이 같은 비율이면 휠 한 번의 체감이 비슷합니다. 거리는 12에서 235 사이로, 기울기는 0.2에서 1.24 라디안 사이로 제한합니다.
클릭과 드래그를 구분하는 일도 직접 해야 했습니다. 드래그가 끝나는 순간에도 pointerup이 오기 때문에, 누른 자리와 뗀 자리가 5픽셀 이하일 때만 클릭으로 봅니다. 클릭이면 화면 좌표를 광선으로 바꿔(Raycaster) 어떤 건물 모형이 맞았는지 찾습니다.
이름표는 3D 객체가 아니라 HTML 버튼입니다. 글자를 3D 텍스처로 만들면 확대할 때 흐려지고 접근성도 잃기 때문입니다. 대신 장소의 3D 좌표를 매 프레임 카메라로 투영해 화면 좌표를 얻고, 그 위치로 버튼을 옮깁니다. 투영 결과가 -1과 1 사이를 벗어나면 화면 밖이라는 뜻입니다.
301곳의 이름표를 한꺼번에 보여 주면 서로 겹쳐 읽을 수 없습니다. 그래서 규칙을 두었습니다. 멀리서는 주요 장소만, 가까이 가면 일반 장소까지 후보에 넣고, 이미 놓인 이름표와 가로세로로 겹치면 숨깁니다. 한 화면에 보일 수 있는 개수에도 상한(멀면 13개, 가까우면 22개)을 두었고, 선택된 장소는 규칙과 상관없이 항상 보입니다.
src/components/lab/map-engine.ts
const eligible = active || (visibleIds.has(label.place.id) && (label.place.featured || distance < 42));const projected = label.position.clone().project(camera), x = (projected.x + 1) / 2 * width, y = (1 - projected.y) / 2 * height;const w = label.place.name.length * 10 + 20;const within = projected.z > -1 && projected.z < 1 && x > w / 2 + 6 && x < width - w / 2 - 56 && y > 82 && y < height - 62;const collides = occupied.some((box) => Math.abs(box.x - x) < (box.w + w) / 2 + 8 && Math.abs(box.y - y) < 43);const show = eligible && within && (active || (!collides && shown < (distance > 90 ? 13 : 22)));
이름표의 폭은 실제로 재지 않고 글자 수에 10을 곱한 값으로 어림합니다. 매 프레임 DOM 크기를 읽으면 레이아웃 계산이 계속 일어나기 때문입니다. 오차가 있어도 겹침 판정에 여유 간격(8픽셀)을 두어 문제가 없었습니다.
8. 선택한 건물을 하이라이트하기
처음에는 선택한 장소에 원형 고리를 띄웠습니다. 구현은 쉬웠지만 건물과 어울리지 않았고, 어느 건물인지도 알기 어려웠습니다. 그래서 건물 윤곽을 찾아 그 모양대로 돌출시킨 블록을 띄우는 방식으로 바꿨습니다.
문제는 윤곽을 찾는 일입니다. 장소 하나가 건물 하나와 1:1로 대응하지 않습니다. 그래서 세 단계로 찾습니다. 장소에 연결된 건물이 있으면 그것을 쓰고, 없으면 장소 좌표를 포함하는 건물을 찾고, 그것도 없으면 가장 가까운 건물을 쓰되 35m 안일 때만 인정합니다.
src/components/lab/map-engine.ts
function outlineFor(placeId: string, point: Coordinate, own?: Footprint) { if (own) return { ring: own.ring.map(project), height: own.height }; const hit = outlines.find((o) => inside(point, o.ring)); if (hit) return hit; let best: (typeof outlines)[number] | undefined, bestDistance = 0.35; for (const o of outlines) { const d = Math.hypot(o.center[0] - point[0], o.center[1] - point[1]); if (d < bestDistance) { best = o; bestDistance = d; } } return best;}
윤곽을 찾았으면 돌출 지오메트리를 만들고 주황색 반투명 재질을 입힙니다. 윤곽선도 함께 그려야 건물 모서리가 또렷하게 보입니다. 윤곽이 하나도 없는 장소는 작은 핀으로 위치를 알립니다.
src/components/lab/map-engine.ts
const shape = new T.Shape(found.ring.map(([x, z]) => new T.Vector2(x, -z)));const geometry = new T.ExtrudeGeometry(shape, { depth: model ? 0.1 : buildingHeight(found.height) + 0.05, bevelEnabled: false }); geometry.rotateX(-Math.PI / 2);// ...const body = new T.Mesh(geometry, new T.MeshStandardMaterial({ color: ACCENT, emissive: ACCENT, emissiveIntensity: 0.3, transparent: true, opacity: 0.8, roughness: 0.8 }));const edge = new T.LineSegments(new T.EdgesGeometry(geometry), new T.LineBasicMaterial({ color: "#fff4df" }));
건물을 선택한 모습. 윤곽이 그대로 돌출되고 모서리선이 함께 그려집니다.
주요 장소는 직접 모형을 만들어 두었는데, 처음에는 이 건물들에서 하이라이트가 보이지 않았습니다. 윤곽 블록이 모형 안에 묻혀 버렸기 때문입니다. 모형 건물에는 블록의 높이를 낮추고 사방으로 1.35배 넓혀 건물 둘레의 받침 판처럼 보이게 했고, 모형의 재질에는 주황색 발광(emissive)을 더했습니다. 일반 건물은 윤곽을 1.04배만 키워 본래 건물을 감싸게 했는데, 같은 크기로 겹치면 면이 깜빡이는 현상(z-fighting)이 생기기 때문입니다.
9. 거리에 따라 건물을 다르게 보여 주기(LOD)
건물 2,422채 중 직접 모형을 만든 주요 건물은 35곳이고, 나머지는 평면으로 바닥 무늬에 찍혀 있었습니다. 가까이 확대해도 평평하니 지도가 밋밋했습니다. 그렇다고 건물마다 메시(mesh)를 하나씩 만들면 그리는 호출이 2천 번을 넘어 무거워집니다.
해법은 두 가지를 겹치는 것입니다. 첫째, 건물을 지도의 격자 구역(가로 6, 세로 9, 모두 54칸)별로 묶어 하나의 지오메트리로 합칩니다(mergeGeometries). 구역 하나가 그리기 호출 하나가 됩니다. 둘째, 멀리서는 모든 구역을 숨기고, 가까이 확대했을 때 카메라 주변 구역만 켭니다. 이렇게 거리에 따라 표현의 정밀도를 바꾸는 방식을 단계별 표현(Level of Detail, LOD)이라고 부릅니다.
높이는 실제 미터를 그대로 쓰지 않았습니다. 장면 한 칸이 100m라서 20m 건물은 0.2칸에 불과하고, 지도 전체에서는 거의 보이지 않습니다. 그래서 0.03을 곱한 뒤 0.28에서 2.4 사이로 제한했습니다. 기본값 9m 건물은 0.28이 되어 너무 납작하지 않고, 아주 높은 건물도 지도를 뚫고 나가지 않습니다. 건물마다 색을 조금씩 달리하려고 정점 색(vertex color)을 넣었는데, 재질이 하나라도 건물마다 다른 색을 낼 수 있습니다.
src/components/lab/map-engine.ts
const g = new T.ExtrudeGeometry(new T.Shape(o.ring.map(([x, z]) => new T.Vector2(x, -z))), { depth: buildingHeight(f.properties.height), bevelEnabled: false });g.rotateX(-Math.PI / 2); g.translate(0, 0.03, 0);const tone = new T.Color("#c4d1b2").offsetHSL(0, 0, ((i * 37) % 11 - 5) * 0.006), n = g.getAttribute("position").count;g.setAttribute("color", new T.Float32BufferAttribute(Array.from({ length: n }, () => [tone.r, tone.g, tone.b]).flat(), 3));const key = `${Math.floor((o.center[0] - SURFACE.minX) / cellW)},${Math.floor((o.center[1] - SURFACE.minZ) / cellH)}`;(groups.get(key) ?? groups.set(key, []).get(key)!).push(g);
구역을 켜고 끄는 코드는 짧습니다. 카메라와 목표 지점 사이 거리가 62보다 가까워지면 건물을 보이게 하고, 그중에서도 카메라가 보는 지점에서 일정 반경 안의 구역만 켭니다. 반경은 거리에 비례해(거리 x 1.1 + 8) 넓어지므로 멀수록 더 많은 구역이 켜집니다.
src/components/lab/map-engine.ts
function updateChunks(distance: number) { const near = distance < BUILDING_LOD, radius = distance * 1.1 + 8, t = controls.target; for (const chunk of chunks) chunk.mesh.visible = near && Math.hypot(chunk.x - t.x, chunk.z - t.z) < radius;}
가까이 확대한 모습. 평면이던 일반 건물이 높이를 가진 입체로 바뀌고, 도로명 라벨이 나타납니다.
구역을 만드는 일은 로드할 때 한 번만 하고, 만든 구역은 처음에는 모두 숨깁니다(visible = false). 확대하기 전까지는 그리기 비용이 없습니다.
10. 확대하면 도로명을 보여 주기
도로명도 이름표처럼 HTML 요소이고, 같은 규칙(겹치면 숨김, 최대 개수)을 씁니다. 다른 점은 두 가지입니다. 도로는 선이라서 이름을 어디에 둘지 정해야 하고, 도로의 방향에 맞춰 글자를 기울여야 합니다.
같은 이름의 도로는 구간이 여러 개로 쪼개져 있습니다. 이름별로 구간을 묶어 가장 긴 구간을 고르고, 그 구간의 한가운데 점을 라벨 위치로 삼습니다. 이름 하나가 라벨 하나만 갖게 하면 긴 도로가 지도에서 보이지 않을 수 있어서, 첫째 구간의 절반보다 긴 구간이 하나 더 있으면 라벨을 최대 두 개까지 둡니다.
글자의 기울기는 도로의 한 점과 다음 점을 화면 좌표로 바꿔 두 점을 잇는 직선의 각도로 구합니다. 각도가 90도를 넘으면 글자가 뒤집혀 읽기 어려우므로 180도를 더하거나 빼서 항상 위쪽을 향하게 합니다.
src/components/lab/map-engine.ts
let angle = Math.atan2(y2 - y, x2 - x) * 180 / Math.PI; if (angle > 90) angle -= 180; else if (angle < -90) angle += 180;label.el.style.transform = `translate(${x}px, ${y}px) translate(-50%, -50%) rotate(${angle}deg)`;
도로명 라벨은 거리가 75보다 가까울 때만 보이고, 한 번에 최대 16개입니다. 장소 이름표가 먼저 자리를 차지하고, 도로명은 남은 자리에만 놓입니다. 도로 등급이 높은 도로가 우선입니다.
11. 숲에 나무 심기
지형이 밋밋해서 숲에 나무를 심었습니다. 나무는 OSM의 숲 구역 안, 그리고 시 경계 안에서만 심고, 주요 건물 주변과 서로 너무 가까운 곳은 피합니다. 후보 위치는 무작위로 뽑는데, 방문할 때마다 나무 위치가 달라지면 같은 지도가 매번 다르게 보입니다. 그래서 시드를 고정한 간단한 선형 합동 생성기(LCG)를 직접 만들었습니다.
나무 290그루를 하나씩 메시로 만들면 그리기 호출이 580번(잎과 줄기)이 됩니다. 같은 모양이 반복되므로 인스턴싱(InstancedMesh)을 썼습니다. 지오메트리와 재질은 하나만 두고, 나무마다 위치와 크기만 행렬로 넘기면 한 번의 호출로 모두 그려집니다.
src/components/lab/map-engine.ts
const crowns = new T.InstancedMesh(new T.IcosahedronGeometry(0.65, 1), new T.MeshStandardMaterial({ color: "#88ad70", roughness: 1, flatShading: false }), candidates.length);const trunks = new T.InstancedMesh(new T.CylinderGeometry(0.07, 0.1, 0.75, 5), new T.MeshStandardMaterial({ color: "#b3a37a" }), candidates.length);
12. React와 Three.js의 경계 나누기
목록, 검색, 분류 필터, 상세 정보는 React 컴포넌트가 맡고, 장면과 카메라와 이름표는 React와 무관한 TypeScript 모듈(map-engine.ts)이 맡습니다. 둘은 콜백과 몇 개의 메서드로만 대화합니다. 장면의 객체를 React 상태로 두면 렌더링할 때마다 비교와 재생성이 일어나 3D가 끊기기 때문입니다.
엔진은 페이지가 열린 뒤 동적으로(import()) 불러옵니다. Three.js는 용량이 크고 브라우저에서만 쓰이므로 서버 렌더링 단계에서 불러올 이유가 없습니다. 컴포넌트가 사라질 때는 엔진의 dispose()를 호출해 WebGL 자원을 돌려줍니다.
확대 비율과 나침반 각도는 카메라가 움직일 때마다 바뀝니다. 이 값을 useState로 올리면 매 프레임 리렌더링이 일어납니다. 그래서 엔진이 값을 알려 주면 상태 대신 ref로 잡아 둔 DOM 요소를 직접 고칩니다. 화면에 보이는 글자만 바뀌고 컴포넌트는 다시 그려지지 않습니다.
src/components/lab/NeighborhoodMap.tsx
onView: (zoom, bearing, pitch) => { if (zoomLabel.current) zoomLabel.current.textContent = `${Math.round(zoom)}%`; if (pitchLabel.current) pitchLabel.current.textContent = `${Math.round(pitch)}°`; if (compass.current) compass.current.style.transform = `rotate(${-bearing}deg)`;},
렌더링도 필요할 때만 합니다. 계속 도는 애니메이션 루프 대신, 카메라가 움직였다는 change 이벤트나 전환 애니메이션이 있을 때만 requestAnimationFrame을 예약합니다. 가만히 있는 지도는 GPU를 쓰지 않습니다.
13. 만들면서 막혔던 것들
가장 오래 걸린 것은 회전이 간헐적으로 먹히지 않는 문제였습니다. 마우스 오른쪽 버튼으로 드래그해도 어떤 곳에서는 지도가 돌지 않았습니다. 원인은 이름표였습니다. 이름표가 HTML 버튼이라 마우스 이벤트를 먼저 받고, 이름표 위에서 시작한 드래그는 캔버스까지 닿지 않았던 것입니다. 지도 위에 이름표가 많아서 자주 걸렸습니다.
이름표가 이벤트를 받지 않게(pointer-events: none) 하면 클릭으로 장소를 고를 수 없습니다. 그래서 이름표에서 시작한 pointerdown을 캔버스로 그대로 넘겨서(dispatchEvent) 컨트롤이 드래그를 시작하게 했습니다. 이때 이름표 클릭은 그대로 선택이 되어야 하므로, 이름표에서 시작했다는 사실을 기억해 두었다가 5픽셀 이내로 끝나면 선택으로 처리합니다.
넘겨진 이벤트는 isTrusted가 거짓이라는 점도 중요했습니다. 캔버스의 pointerdown 처리에서 "이름표에서 시작했다"는 기억을 지우는데, 사용자가 캔버스를 직접 눌렀을 때만 지워야 하기 때문입니다. 사용자의 진짜 이벤트와 코드가 만든 이벤트를 구분하는 값이 isTrusted입니다.
src/components/lab/map-engine.ts
function pointerDown(event: PointerEvent) { if (event.isTrusted) downPlace = null; down = { x: event.clientX, y: event.clientY }; }
7단계에서 적은 모형 건물의 하이라이트 문제도 비슷했습니다. 코드가 틀린 것이 아니라 어떤 요소가 어떤 요소 위에 놓이는지, 어떤 요소가 이벤트를 먼저 받는지가 원인이었습니다. 3D와 DOM을 함께 쓰는 화면에서는 이런 겹침 관계를 먼저 확인하는 것이 시간을 아꼈습니다.