OpenLayers와 deck.gl을 같이 쓸 때 어긋나는 이유

OpenLayers 지도 위에 deck.gl layer를 얹으면 강력한 시각화를 만들 수 있다.

문제는 두 라이브러리가 각자 view와 coordinate를 관리한다는 점이다.

처음에는 레이어가 아예 보이지 않거나, 처음엔 맞다가 pan/zoom 후 조금씩 어긋나는 일이 생길 수 있다.

1. module loading부터 확인한다

시각화가 안 보이면 좌표 문제라고 생각하기 쉽다.

하지만 ESM import나 asset path가 404라면 아무리 좌표를 바꿔도 소용없다.

먼저 확인한다.

• network 200
• 실제 module path
• build output
• ESM import 경로

2. 좌표계 책임을 한 곳에 둔다

다음 네 개를 따로 적어보면 문제가 잘 보인다.

원본 데이터 좌표
OpenLayers View 좌표
deck.gl ViewState
overlay canvas 위치

변환을 OpenLayers 쪽에서도 하고 deck.gl 쪽에서도 하면 위치가 맞는 것처럼 보이다가 이동하면서 drift가 생길 수 있다.

3. Viewport synchronization

initialViewState와 viewState를 같이 넘기면 안 됩니다. deck.gl 문서가 명시하는 사항이고, OpenLayers가 뷰를 소유하는 구성에서는 viewState만 넘겨 외부에서 관리해야 합니다. 둘을 같이 주면 deck.gl이 자체 상태를 들고 있게 되어, OpenLayers가 움직인 뒤 한 프레임 동안 서로 다른 곳을 그립니다.

초기 화면을 한 번 맞추는 것만으로는 부족하다.

OpenLayers의:

center
zoom
rotation

변화가 있을 때 deck.gl viewState도 같이 갱신돼야 한다.

OL View change
↓
현재 상태 읽기
↓
deck.gl에 반영

4. Drift는 작은 CSS 문제가 아닐 수 있다

pan할 때 조금씩 밀린다면 단순 pixel offset을 보정하는 식으로 접근하기 쉽다.

하지만 실제 원인은 좌표 변환이나 viewport origin 책임이 중복된 것일 수 있다.

이 경우 임시 offset을 넣으면 zoom level마다 다시 틀어진다.

Known Point 하나로 시작하는 것이 가장 빠르다

복잡한 HexagonLayer부터 맞추면 문제가 projection인지 aggregation인지 구분하기 어렵다. 먼저 정답 위치를 아는 좌표 하나를 두 라이브러리에 동시에 그린다.

Known lon/lat
→ OpenLayers point
→ deck.gl point

두 점이 정확히 겹치는지 확인한 뒤 여러 점, polygon, aggregation layer 순으로 확장한다.

ViewState 값을 직접 비교한다

화면만 보고 추측하지 말고 숫자를 본다.

OpenLayers center
OpenLayers zoom
OpenLayers rotation
deck.gl longitude
deck.gl latitude
deck.gl zoom

pan/zoom할 때 값이 예상대로 함께 움직이는지 확인하면 drift 원인을 훨씬 빨리 좁힐 수 있다.

Pixel Ratio와 Canvas Size도 확인한다

고해상도 디스플레이에서는 device pixel ratio와 canvas size 차이가 overlay 어긋남처럼 보일 수 있다. 좌표가 맞는데 pixel 단위로 일정하게 밀린다면 projection보다 canvas sizing을 확인한다.

직접 실행하는 디버깅 점검 순서

1. Module 200 확인
2. Data 200 확인
3. Known point 1개 표시
4. Projection 확인
5. Initial view sync
6. Pan sync
7. Zoom sync
8. Rotation sync
9. Pixel ratio 확인
10. 복잡한 layer 적용

이 순서로 가면 “레이어가 안 보인다”는 하나의 증상을 여러 독립 문제로 분해할 수 있다.

이 순서가 통하지 않는 것

module loading · 좌표계 · viewport 세 계층으로 나누면 대부분은 여기서 끝납니다. 다만 이 순서가 답을 주지 못하는 것들이 있습니다.

• 정지 상태에서는 겹치는데 움직일 때만 밀리는 경우. 두 라이브러리가 서로 다른 프레임에 그리면 known point가 정확히 겹쳐도 팬·줌 중에 한 프레임씩 어긋납니다. 이건 좌표 문제가 아니라 렌더 타이밍 문제라 위 절차로는 안 보입니다

• WebGL 컨텍스트를 두 개 쓰는 구성 자체의 한계. 모바일에서는 컨텍스트 수 제한과 메모리 압박이 먼저 옵니다. 정렬이 맞아도 한쪽이 컨텍스트를 잃으면 사라집니다

• 좌표계가 애초에 다른 데이터. 레이어마다 EPSG가 섞여 있으면 뷰를 아무리 맞춰도 안 맞습니다. 그건 좌표계 판별 쪽 문제입니다

• 여기 적은 것은 특정 버전 조합에서 관찰되는 증상입니다. 라이브러리 버전이 바뀌면 달라집니다

• deck.gl — Views and Projections

• deck.gl — Interactivity (externally managed viewState)