3D 지도 권장사항

이 가이드에서는 3D 지도 웹 구성요소와 애플리케이션과 통합할 때 고려사항을 자세히 살펴봅니다.

장소 검색 및 경로 찾기의 사용 사례 예시 — 장소 검색 및 경로 찾기 예시입니다.

성능 고려사항

원활하고 반응성이 뛰어난 상호작용 및 시각적 요소를 위해 다음 접근 방식을 고려하세요.

지도 로드

3D 지도의 초기 로드 및 렌더링 설정은 최적의 사용자 환경을 위해 브라우저 구성 기술과 UI 권장사항을 결합합니다.

API 로드: 초기 페이지 로드 시 Maps JavaScript API를 로드하려면 3D 지도 비동기 동적 로드를 사용합니다.
라이브러리: google.maps.importLibrary("maps3d")와 같이 필요한 경우 프로그래매틱 방식으로 라이브러리를 로드합니다. 또는 직접 스크립트 로드를 사용하여 HTML 페이지에서 <gmp-map-3d>와 같은 웹 구성요소를 직접 사용하는 경우 적절한 시점에 라이브러리가 자동으로 로드됩니다.
기본 지도 기능 관리: 맞춤 mapId를 사용하여 기본 지도 POI(HYBRID 모드)를 필터링하고 밀도를 관리합니다. 특히 애플리케이션에 마커나 폴리라인과 같은 자체 맞춤 요소가 있는 경우에 유용합니다. 이렇게 하면 시각적 혼란과 잠재적 중복을 방지할 수 있습니다. 또는 POI, 도로 폴리라인, 도로 이름, 거리 이름 (위성 모드)과 같은 기본 지도 벡터 타일 기능을 사용 중지할 수 있습니다.
이벤트: gmp-steadystate 또는 gmp-error 이벤트를 수신하여 마커 로드, 카메라 애니메이션과 같은 후속 로직을 빌드합니다.

지도 로드 시퀀스 — 배경 캔버스 > 축소된 타일 > 지형 메시 > 표면 메시 (예: 건물) > 관심 장소 및 도로 라벨, 병렬로 로드되는 맞춤 요소 (마커, 3D 모델 등)

사용자 상호작용: 지도의 콘텐츠를 변경하기 전에 gmp-steadystate 이벤트를 기다립니다. 사용자가 초기 gmp-steadystate 이벤트 전에 지도와 상호작용 (이동, 확대/축소)하기 시작하면 사용자가 상호작용을 중지한 후에만 이벤트가 트리거됩니다. 사용자가 지도를 이동하거나 확대/축소하는 동안 오버레이 콘텐츠 (예: 마커 또는 다각형)를 표시하거나 업데이트하지 마세요. gmp-centerchange, gmp-headingchange, gmp-rangechange, gmp-rollchange, gmp-tiltchange를 수신 대기하여 오버레이 콘텐츠 (예: 마커 또는 다각형)를 표시하거나 업데이트하지 마세요.
requestAnimationFrame() (rAF) 사용: 지속적인 업데이트를 위해 사용하고 집약적인 계산을 그리기 호출과 엄격하게 분리합니다.
- rAF 사용: 부드러운 60FPS 애니메이션과 전력 소비 감소를 위해 업데이트를 브라우저의 디스플레이 속도와 동기화합니다.
- 집중적인 그리기 작업 방지: 최종 업데이트 중에 무거운 비그리기 작업을 실행하지 마세요.
- 로직 분리: rAF 루프 내에서 최소 웹 구성요소 업데이트 호출 전에 모든 집약적 로직을 실행합니다.
초기 장면 설정: <gmp-map-3d> 기울기와 같은 카메라 설정은 로드 속도에 영향을 미칩니다. 장면을 확대하거나 기울일수록 더 상세한 다각형이 표시되고 로드해야 합니다. 세부정보 수준은 위치 (예: 건물이 많은 도시와 자연 지형만 있는 시골)에 따라 달라집니다.
- 확대되지 않은 (고도 높음), 기울지 않은 뷰를 선호합니다.
- 사용자가 특정 영역에 집중하고 타일이 완전히 로드될 수 있도록 지도에 bounds(sample)를 추가합니다.
프리로더 시각적 요소: <gmp-map-3d>는 매우 빠르게 로드되지만, 저가형 기기 (GPU 낮음) 또는 대역폭 (4G 느림)을 사용하는 사용자에게는 전체 해상도로 표시하는 데 시간이 걸릴 수 있습니다. 이 경우 배경에서 3D 장면이 로드되는 이미지, 애니메이션 또는 텍스트로 프리로더를 만들 수 있습니다. 아래에서 사용할 주요 이벤트를 확인하세요.

// create the map in the background and wait for gmp-steadystate event
async function initMap() {
    await google.maps.importLibrary("maps3d");
    const map = document.querySelector('gmp-map-3d');
    const div = document.querySelector('div'); // preloader "
    map.addEventListener('gmp-steadystate', ({isSteady}) => {
        if (isSteady) {
            div.style.display = 'none';
        }
    });
}
initMap();

2D 지도:
- 마커와 같은 지리 데이터를 포함하면서 이러한 사용자에게 대체 2D 지도(위성)를 제공할 수 있습니다.

또는 로드하는 동안 사용자가 특정 장소를 시각화할 수 있도록 위성 모드의 보완적인 2D 정적 지도를 표시할 수 있습니다.

시각적 요소 성능 및 관리

3D 지도는 마커, 폴리라인, 폴리라인, 3D 모델과 같은 시각적 요소를 최적의 성능과 최소한의 렌더링 시간으로 표시하는 여러 방법을 제공합니다. 시각적 요소의 양이 많더라도 마찬가지입니다.

마커

최적의 맞춤설정 선택:
- PinElement: 기본 마커 변경사항 (색상, 크기, 테두리, 텍스트 글리프)의 경우 <gmp-pin> 요소 또는 PinElement 클래스를 사용합니다. 이 방법이 가장 성능이 좋은 맞춤설정 방법입니다.
- HTMLImageElement 또는 SVGElement 마커를 적절히 사용: 투명도를 추가하거나 아이콘과 같은 이미지를 SVGElement에 삽입하는 등 더 많은 맞춤설정에 사용합니다 (base64 인코딩 필요). 이러한 이미지는 로드 시 래스터화되며 성능 오버헤드가 발생합니다. HTMLImageElement와 SVGElement는 Marker3DElement의 기본 슬롯에 할당하기 전에 <template> 요소로 래핑해야 합니다.
- 현재는 일반 HTML 또는 CSS를 추가할 수 없습니다.
충돌 동작 관리: 마커의 collisionBehavior 속성을 활용합니다. 항상 표시되어야 하는 중요한 마커의 경우 동작을 적절하게 설정하세요. 중요도가 낮은 마커의 경우 특히 높은 확대/축소 수준에서 더 깔끔하고 덜 복잡한 지도 환경을 유지할 수 있도록 숨길 수 있습니다.
중요한 관심 장소만: 건물이나 지형을 통해 반드시 봐야 하는 마커(예: 구조 대상, 매설된 유틸리티 라인 또는 사용자의 아바타)에만 drawsWhenOccluded를 사용하거나 속성을 프로그래매틱 방식으로 설정합니다.
폐색 테스트: 지도는 3D이므로 건물이나 지형에 의해 마커가 시각적으로 가려질 수 있습니다(폐색). 다양한 카메라 각도와 마커 고도를 테스트하여 중요한 관심 지점이 계속 표시되도록 하거나, 가려진 경우 가시성과 고도를 조정하는 로직을 구현합니다.
고도 활용: 3D 지도에서 마커는 고도 값이 있는 위치를 사용해야 합니다. 지형 또는 건물과 연결된 마커의 경우 지도가 기울어지거나 회전할 때 마커가 올바르게 고정되도록 altitudeMode: 'RELATIVE_TO_GROUND', 'RELATIVE_TO_MESH' 또는 유사한 설정을 사용합니다.

다각형 및 다중선

다각형 로드 예 — 예시 시나리오: 다각형 1,000개를 로드하는 데 100~150ms가 걸림 (최신 노트북: macOS M3 Pro, Chrome)

기하구조 단순화: 렌더링 전에 경로 데이터에 단순화 알고리즘을 적용합니다. 이렇게 하면 일반적인 모양을 유지하면서 꼭짓점 수가 줄어들어 특히 복잡한 경계나 경로의 렌더링 속도가 크게 향상됩니다.
확대/축소 수준별 데시메이션: 매우 큰 데이터 세트의 경우 사용자가 해당 영역으로 확대할 때만 세부정보가 많은 지오메트리를 로드하는 것이 좋습니다. 낮은 확대/축소 수준에서는 매우 단순화된 폴리라인 또는 다각형 버전만 필요합니다.
돌출된 다각형 사전 계산: 다각형이 돌출(extruded: true)된 경우 경로 데이터는 3D 볼륨 (메시)을 정의합니다. 복잡한 고정점 폴리곤을 처리하는 데는 계산 비용이 많이 듭니다. 다각형의 소스 데이터는 최대한 단순해야 합니다.
폴리라인 및 다각형 성능 테스트: 특히 3D로 돌출된 경우 수많은 또는 복잡한 폴리라인/다각형을 추가할 때 프레임 속도가 떨어지지 않는지 확인합니다. 필요한 경우 꼭짓점 수를 제한하거나 단순화 알고리즘을 사용합니다.
모양을 업데이트할 때는 루프를 실행하고 개별 요소를 수정하는 대신 단일 작업에서 전체 경로 배열을 수정합니다. 단일 할당 작업 (예: polyline.path = newPathArray;)은 여러 반복 업데이트보다 훨씬 효율적입니다.
돌출된 폴리라인 피하기 (가능한 경우): 폴리라인은 고도 값을 사용하여 3D 공간에 배치할 수 있지만 폴리라인을 돌출시키면 (예: 획 너비와 큰 고도 범위를 지정) 그래픽 집약적일 수 있습니다. 가능하면 지상 (RELATIVE_TO_GROUND)에 2D 폴리라인을 사용하거나 성능 향상을 위해 최소 획 두께를 사용하세요.
중요한 라우팅 요소에만 drawsOccludedSegments를 사용하세요. 배경 또는 맥락적 도형의 경우 지도의 3D 형상에 의해 자연스럽게 가려지도록 허용합니다. 중요하지 않은 숨겨진 형상을 표시하면 불필요한 렌더링 복잡성이 추가됩니다.

3D 모델

<gmp-map-3d>에서 3D 모델 .glb 렌더링과 gmp-click 이벤트와 같은 상호작용이 매우 빠릅니다.

압축으로 파일 크기 최소화: 특히 모바일 네트워크에서 빠르게 로드되도록 복잡한 .glb 모델 파일을 5MB 미만으로 유지합니다 (이상적으로는 더 작게). 이를 달성하는 기본 방법은 .glb 파일 내의 메시 데이터에 Draco 압축을 적용하는 것입니다. 이렇게 하면 시각적 품질 손실을 최소화하면서 파일 크기를 크게 줄일 수 있습니다 (종종 50% 이상).
모델 원점 중앙에 배치: 3D 모델링 소프트웨어가 모델의 원점 (0, 0, 0 지점)이 모델의 베이스 중앙에 배치된 상태로 모델을 내보내야 합니다. 이렇게 하면 지도에서 위치 지정과 회전이 간소화되어 모델이 위도, 경도 좌표에 올바르게 고정됩니다.
CORS 관리: 모델 파일이 웹 애플리케이션과 다른 도메인이나 CDN에 호스팅되는 경우 필요한 교차 출처 리소스 공유 (CORS) 헤더 (예: Access-Control-Allow-Origin: *). 그렇지 않으면 지도가 모델을 로드할 수 없습니다.