Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

3D 지도 권장사항

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

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

성능 고려사항

상호작용 및 시각적 요소에 원활하고 반응이 빠른 환경을 제공하려면 다음 접근 방식을 고려하세요.

지도 로드

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

API 로드: 초기 페이지 로드 시 Maps JavaScript API를 로드하려면 3D 지도 비동기 동적 로드를 사용합니다.
라이브러리: google.maps.importLibrary("maps3d")와 같이 필요한 경우 프로그래매틱 방식으로 라이브러리를 로드합니다. 또는 직접 스크립트 로드를 사용하여 HTML 페이지에서 <gmp-map-3d>와 같은 웹 구성요소를 직접 사용하는 경우 라이브러리가 적절한 시점에 자동으로 로드됩니다.
기본 지도 지형지물 관리: 커스텀 mapId를 사용하여 기본 지도 관심 장소(HYBRID 모드)를 필터링하고 밀도를 제어합니다. 특히 애플리케이션에 마커나 다중선과 같은 자체 커스텀 요소 집합이 있는 경우에 유용합니다. 이렇게 하면 시각적 혼란과 잠재적인 중복을 방지할 수 있습니다. 또는 관심 장소, 도로 다중선, 도로 이름, 거리 이름 (SATELLITE 모드)과 같은 기본 지도 벡터 타일 기능을 사용 중지할 수 있습니다.
이벤트: 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> 카메라 설정은 로드 속도에 영향을 미칩니다. 장면을 확대하거나 기울일수록 더 상세한 다각형이 표시되며 로드가 필요합니다. 세부정보 수준은 위치에 따라서도 달라집니다 (예: 건물이 많은 도시와 자연 지형지물만 있는 시골).
- 확대 수준이 낮고 (고고도) 기울기가 낮거나 기울어지지 않은 뷰를 선호합니다.
- 사용자가 특정 영역에 집중하고 타일이 완전히 로드될 수 있도록 지도에 경계(샘플)를 추가합니다.
프리로더 시각 요소: <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 지도(SATELLITE)를 이러한 사용자에게 제공할 수 있습니다.

또는 로드하는 동안 사용자가 특정 장소를 시각화할 수 있도록 위성 모드의 보완적인 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 공간에 배치할 수 있지만 다중선을 돌출 (예: 획 너비 및 큰 고도 범위 지정)하면 그래픽 집약적일 수 있습니다. 가능하면 지면의 2D 다중선 (RELATIVE_TO_GROUND) 또는 최소 선 두께를 사용하여 성능을 개선하세요.
중요한 경로 요소에만 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: *)를 포함하도록 호스팅 서버를 구성해야 합니다. 그렇지 않으면 지도에서 모델을 로드할 수 없습니다.