소개
이 가이드의 목적은 KmlLayer의 가장 일반적인 사용 사례를 다루고 대체 구현으로의 해당 마이그레이션 경로를 제공하는 것입니다. 이 정보는 예정된 지원 중단으로 인해 KmlLayer 사용에서 전환해야 하는 개발자를 위한 것입니다. KmlLayer를 지원하는 마지막 버전은 3.65이며 2027년 5월에 지원이 중단됩니다.
마이그레이션 경로는 KmlLayer 사용 방식에 따라 달라집니다.
- 관심 지역의 경계/테두리/영역 정보를 스타일 지정하는 KML 파일: Google의 경계 데이터를 사용하는 행정 구역에는 경계에 대한 데이터 기반 스타일 지정 (DDS)을 사용합니다.
- 벡터 데이터 (점/폴리라인/경계/다각형)가 포함된 KML 파일: 데이터 세트용 DDS, GeoJSON 또는
deck.gl,geoxml3과 같은 서드 파티 라이브러리를 사용합니다. - 대화형 요소가 있는 KML 파일: 기능 상호작용을 위해 수동 이벤트 리스너와 맞춤 정보 창을 구현합니다.
- 이미지가 포함된 KML 파일: 이미지 오버레이에는 GroundOverlays 또는 서드 파티 파서를 사용합니다.
- 네트워크 링크가 있는 KML 파일: 각 KML을 별도의 데이터 세트로 업로드하거나 KML을 병합합니다. 동적 데이터를 표시하는 경우 Datasets API를 사용하여 데이터 세트를 새로고침합니다.
- KML을 사용하여 화면 오버레이 표시: 맞춤 컨트롤을 사용하여 로고, 범례, 탐색 지원과 같은 고정 UI 요소를 대체합니다.
관심 영역의 경계/테두리/영역 정보를 스타일 지정하는 KML 파일
KmlLayer를 사용하여 특정 국가, 주, 지역을 강조 표시하는 등 행정 경계를 표시하거나 스타일을 지정하는 개발자의 경우 Google Maps Platform에서는 경계용 데이터 기반 스타일 지정 (DDS)으로 이전하는 것이 좋습니다.
이전 권장사항: 경계를 위한 데이터 기반 스타일 지정
경계에 대한 데이터 기반 스타일 지정을 사용하면 Google의 행정 경계 다각형에 직접 액세스할 수 있으므로 외부 KML 파일을 호스팅하거나 관리하지 않고도 이러한 지역에 맞춤 스타일 (채우기 및 획)을 적용할 수 있습니다.
사용 가능한 FeatureType
행정 구역은 기능별로 분류되고 수준별로 정렬됩니다. 스타일 지정에 지원되는 지형지물 유형은 다음과 같습니다.
COUNTRY: 국가 정치 단체입니다.ADMINISTRATIVE_AREA_LEVEL_1: 국가 수준 아래의 첫 번째 행정 독립체입니다 (예: 미국의 주).ADMINISTRATIVE_AREA_LEVEL_2: 국가 수준 아래 두 번째 행정 독립체입니다 (예: 미국의 카운티).LOCALITY: 자치 도시 또는 자치 마을입니다.POSTAL_CODE: 우편에 사용되는 우편번호입니다.SCHOOL_DISTRICT: 통합, 초등학교 또는 중등학교 학군입니다.
이러한 지형지물 유형을 사용할 수 있는 지역은 경계 적용 범위를 참고하세요.
영역을 강조 표시하는 방법
특정 지역의 스타일을 지정하려면 장소 ID로 타겟팅해야 합니다.
- 설정: JavaScript 벡터 지도 유형에 대해 구성된 지도 ID를 사용하고 Google Cloud 콘솔에서 사용할 수 있는 지형지물 레이어를 사용 설정해야 합니다.
- 구현: 경계 다각형 스타일 지정 샘플 코드를 사용합니다.
영역으로 패닝 제한
사용자가 강조 표시된 영역의 경계 상자 외부로 이동하지 못하도록 하려면 MapOptions 내에서 restriction 옵션을 사용하면 됩니다.
restriction 객체는 지도의 볼 수 있는 영역을 제한하는 latLngBounds를 정의합니다. 제한이 작동하는 방식에 관한 자세한 내용은 문서를 참고하세요.
// Restrict panning to a specific bounding box
restriction: {
latLngBounds: {
north: 47.8,
south: 45.8,
east: 10.5,
west: 5.9,
},
strictBounds: true,
},
요약 마이그레이션 구현
다음은 경계에 데이터 기반 스타일 지정을 사용하고 지역 제한을 사용하여 특정 지역 주변에 지도를 집중하는 방법의 전체 예입니다.
const myTargetRegion = "ChIJYW1Zb-9kjEcRFXvLDxG1Vlw"; // Place ID for Switzerland
function initMap() {
const map = new google.maps.Map(document.getElementById("map"), {
center: { lat: 46.8, lng: 8.2 },
zoom: 9,
mapId: "YOUR_MAP_ID", // Required for DDS
// Restrict panning to a specific bounding box
restriction: {
// Bounding box for Switzerland
latLngBounds: {
north: 47.8,
south: 45.8,
east: 10.5,
west: 5.9,
},
strictBounds: true,
},
});
// Access the Country layer and style a specific region by Place ID
const countryLayer = map.getFeatureLayer("COUNTRY");
countryLayer.style = (options) => {
if (options.feature.placeId === myTargetRegion) {
return {
fillColor: "#FF0000",
fillOpacity: 0.5,
strokeColor: "#FF0000",
strokeWeight: 2,
};
} else {
// Style everything else whited out, to make the area of interest pop out more.
return {
fillColor: '#ffffff',
fillOpacity: 0.8,
};
}
};
}
벡터 데이터 (점/폴리라인/경계/다각형)가 포함된 KML 파일
이전 권장사항: 데이터 세트를 위한 데이터 기반 스타일 지정
Google에서는 스타일 지정 및 성능을 더 세밀하게 제어하면서 공개적으로 제공되는 지리 데이터를 표시하기 위해 아래 경로를 권장합니다.
데이터 세트에 대한 데이터 기반 스타일 지정 기능을 사용하면 자체 지리 공간 데이터 (KML, GeoJSON 또는 CSV)를 업로드하고, 데이터 속성을 기반으로 맞춤 스타일을 적용하고, 벡터 지도에 지형지물을 표시할 수 있습니다.
1. 설정 및 업로드
런타임에 URL을 가져오는 KmlLayer와 달리 DDS에서는 Google Cloud 콘솔에 데이터를 데이터 세트로 호스팅해야 합니다.
- 지도 ID 만들기: 벡터 지도 유형으로 구성된 지도 ID를 사용합니다.
- 데이터 세트 업로드: KML 파일을 Google Cloud 콘솔에 업로드하여 고유한 데이터 세트 ID를 생성합니다. 자세한 내용은 지도 데이터 세트 관리 방법에 관한 전체 문서를 참고하세요.
- 데이터 세트 표시: 데이터 세트 ID를 만든 후에는 데이터 세트를 지도 스타일 및 지도 ID와 연결해야 합니다. 그런 다음 데이터 세트 ID를 사용하여 지도에 데이터를 실제로 표시합니다. 자세한 내용은 지도에 데이터 세트를 추가하는 방법의 전체 문서를 참고하세요.
- KML 형식에서 데이터를 가져오려는 경우 데이터 세트의 KML 요구사항을 참고하세요.
2. 뷰포트를 데이터로 설정
KmlLayer는 기본적으로 데이터 위치로 자동 이동하고 확대/축소합니다. 데이터 세트용 DDS를 사용하면 이 동작이 자동으로 실행되지 않으므로 수동으로 구현해야 합니다.
- 하드코딩된 제한사항: 데이터 영역이 정적인 경우
MapOptions에서restriction옵션을 사용하여 뷰포트를 특정 경계로 잠급니다. - 동적 확대/축소: 뷰포트를 동적으로 설정하려면 데이터 세트의 경계 상자와 함께
map.fitBounds()를 사용하면 됩니다.
3. 특성 속성을 기반으로 스타일 지정
KML 파일에는 DDS에서 자동으로 적용하지 않는 스타일 정보 (예: 색상)가 포함되는 경우가 많습니다. 데이터 세트 지형지물에서 속성을 읽어 색상과 불투명도를 적용하는 클라이언트 측 스타일 함수를 만들어야 합니다. 자세한 내용은 데이터 스타일 지정 방법에 관한 개발자 문서를 참고하세요.
예: 속성을 사용한 스타일 지정 함수
다음 예에서는 업로드된 데이터 세트에서 background_color 및 opacity 속성을 직접 읽는 스타일 함수를 만드는 방법을 보여줍니다.
/**
* Migration example: Styling features from dataset attributes.
*/
function styleDDSLayer(map, datasetId) {
const datasetLayer = map.getDatasetFeatureLayer(datasetId);
// Set the style function
datasetLayer.style = (params) => {
// Access attributes defined in your KML/Dataset
const featureAttributes = params.feature.datasetAttributes;
// Read style values from attributes, with fallback defaults
const fillColor = featureAttributes['background_color'] || '#4285F4';
const fillOpacity = parseFloat(featureAttributes['opacity']) || 0.5;
const strokeColor = featureAttributes['border_color'] || '#34A853';
return {
fillColor: fillColor,
fillOpacity: fillOpacity,
strokeColor: strokeColor,
strokeWeight: 2,
};
};
}
상호작용 및 스타일 지정 구현에 관한 자세한 내용은 데이터 세트의 데이터 기반 스타일 지정 개요 및 동적 데이터의 데이터 세트 API를 참고하세요.
이전 권장사항: GeoJSON을 사용한 클라이언트 측 렌더링
KmlLayer에서 GeoJSON을 사용한 클라이언트 측 렌더링으로 이전하는 개발자의 경우 Google Maps Platform은 데이터 형식을 변환하고 데이터 레이어를 사용하여 브라우저에서 직접 피처를 렌더링하고 스타일을 지정하는 마이그레이션 경로를 권장합니다.
데이터 레이어를 사용한 클라이언트 측 렌더링은 지리 데이터를 표시하는 매우 유연한 방법을 제공합니다. Google 서버에서 렌더링되는 KmlLayer와 달리 데이터 영역을 사용하면 표준 JavaScript 객체로 기능과 상호작용할 수 있습니다. 하지만 대규모 데이터 세트의 경우 데이터 세트의 데이터 기반 스타일 지정과 같이 서버 측에서 데이터를 처리하고 렌더링하는 것이 더 나을 수 있습니다.
1. KML을 GeoJSON으로 변환
첫 번째 단계는 KML 파일을 GeoJSON으로 변환하는 것입니다. 이 작업은 다음과 같은 여러 인기 오픈소스 도구를 사용하여 실행할 수 있습니다.
- ogr2ogr: GDAL 제품군의 일부인 이 강력한 명령줄 유틸리티는 다양한 벡터 형식 간에 변환할 수 있습니다.
ogr2ogr -f GeoJSON output.json input.kml
- togeojson: KML 및 GPX를 GeoJSON으로 변환하도록 특별히 설계된 작고 잘 테스트된 도구입니다.
togeojson input.kml > output.json
2. 뷰포트를 데이터로 설정
KmlLayer는 데이터 위치로 자동 이동하고 확대/축소하지만 데이터 레이어는 그렇지 않습니다. GeoJSON 데이터에 맞게 뷰포트를 설정하려면 경계 상자를 수동으로 계산하고 map.fitBounds()을 호출해야 합니다.
3. 특성 속성을 기반으로 스타일 지정
데이터 레이어에서 각 GeoJSON 지형지물에서 속성을 직접 읽어 모양을 결정하는 style 함수를 정의할 수 있습니다.
예: 스타일 지정 함수 및 뷰포트 조정
다음 예에서는 GeoJSON 데이터를 로드하고, 뷰포트를 설정하기 위해 경계를 계산하고, 속성을 기반으로 지형지물의 스타일을 지정하는 방법을 보여줍니다.
/**
* Migration example: Loading GeoJSON, fitting viewport, and styling from attributes.
*/
function initMap() {
const map = new google.maps.Map(document.getElementById("map"), {
zoom: 4,
center: { lat: -28, lng: 137 },
});
// Load the GeoJSON data
map.data.loadGeoJson('path/to/your/data.json', null, (features) => {
// Adjust viewport to show all loaded features
const bounds = new google.maps.LatLngBounds();
features.forEach((feature) => {
feature.getGeometry().forEachLatLng((latlng) => {
bounds.extend(latlng);
});
});
map.fitBounds(bounds);
});
// Set the style function to read from GeoJSON properties
map.data.setStyle((feature) => {
// Access attributes defined in your GeoJSON properties
const fillColor = feature.getProperty('background_color') || '#4285F4';
const opacity = parseFloat(feature.getProperty('opacity')) || 0.5;
const strokeColor = feature.getProperty('border_color') || '#34A853';
return {
fillColor: fillColor,
fillOpacity: opacity,
strokeColor: strokeColor,
strokeWeight: 2,
visible: true
};
});
}
데이터 영역 사용에 관한 자세한 내용은 지도에 GeoJSON 가져오기 문서를 참고하세요.
이전 경로: 서드 파티 라이브러리를 사용한 클라이언트 측 렌더링
KmlLayer의 다른 대안을 찾는 개발자를 위해 Google Maps Platform JavaScript API에서 KML 데이터를 렌더링하는 커뮤니티 유지관리 라이브러리가 여러 개 있습니다.
1. deck.gl
deck.gl는 고성능 WebGL 기반 시각화 프레임워크입니다. GoogleMapsOverlay 및 GeoJsonLayer을 통해 KML 렌더링을 거의 바로 대체할 수 있습니다.
- 캔버스 요구사항:
deck.gl를 효과적으로 사용하려면 WebGL 렌더링 기능이 있는 벡터 지도 유형을 사용하도록 지도를 변환 (캔버스 요소에 렌더링)해야 합니다. - KML 지원: 도형 파싱은 KML을 GeoJSON으로 변환하는
@loaders.gl/kml에 의해 처리됩니다. 복잡한 스타일, 아이콘, NetworkLink와 같은 일부 KML 기능에는 추가 수동 구현이 필요할 수 있습니다. - 문서: deck.gl 문서 | loaders.gl KML 로더
- 예:
- Google 지도 GitHub 저장소의 deckgl-kml-updated 샘플에서는 deck.gl을 사용하여 실시간으로 업데이트되는 KML 데이터를 렌더링하는 방법을 보여줍니다.
- deckgl-kml 샘플은 deck.gl을 사용하여 KML 데이터를 렌더링하는 방법을 보여줍니다.
2. geoxml3
geoxml3는 Google Maps JavaScript API v3용으로 특별히 설계된 KML 프로세서입니다. 브라우저에서 KML을 로컬로 파싱하고 데이터를 마커, 다중선, 다각형과 같은 표준 Google 지도 API 객체로 렌더링합니다.
- 표준 지도 지원: WebGL 기반 솔루션과 달리
geoxml3는 특정 렌더링 모드가 필요하지 않고 표준 Google Maps JS API v3 지도에서 작동합니다. - 주의사항:
- 제한적인 KMZ 지원: 라이브러리는 기본적으로 KMZ 파일을 완전히 지원하지 않습니다. KMZ 보관 파일의 압축을 해제하려면 일반적으로
ZipFile.complete.js와 같은 추가 서드 파티 스크립트와 통합해야 합니다. - 지원되지 않는 요소: 3D 도형, 복잡한 라벨, 특정 최신 KML 요소와 같은 기능은 지원되지 않습니다.
- 제한적인 KMZ 지원: 라이브러리는 기본적으로 KMZ 파일을 완전히 지원하지 않습니다. KMZ 보관 파일의 압축을 해제하려면 일반적으로
- 문서: geoxml3 GitHub 저장소
양방향 요소가 포함된 KML 파일
이전 권장사항: 데이터 세트를 위한 데이터 기반 스타일 지정
KmlLayer에서 데이터 세트용 데이터 기반 스타일 지정 (DDS)으로 이전하는 개발자를 위해 이 가이드에서는 자동 KML 상호작용에서 마우스 클릭 및 마우스 오버와 같은 맞춤형 고성능 상호작용으로 전환하는 방법을 설명합니다.
초기 설정
상호작용을 구현하기 전에 KML 마이그레이션: 벡터 데이터 가이드의 설정 단계를 따랐는지 확인하세요.
- 지도 ID: 벡터 지도 유형의 지도 ID를 구성합니다.
- 업로드: KML 데이터를 Google Cloud 콘솔에 업로드하여 데이터 세트 ID를 가져옵니다.
- 레이어 액세스:
map.getDatasetFeatureLayer(datasetId)를 사용하여 대화형 레이어에 액세스합니다.
1. 상호작용 이벤트 처리
KmlLayer에서는 기능 클릭이 API에 의해 자동으로 처리되어 정보 창이 팝업됩니다. 데이터 세트용 DDS를 사용하면 데이터 세트 레이어에서 마우스 이벤트 리스너를 수동으로 등록해야 합니다.
click: 사용자가 기능을 클릭할 때 트리거됩니다.mousemove: 커서가 기능을 지나갈 때 트리거되며, 마우스 오버 효과에 유용합니다.
2. 동적 스타일 지정 (마우스 오버 효과)
DDS 스타일은 레이어에 전역으로 적용되므로 상호작용 중인 기능을 추적하고 스타일을 다시 적용하는 상태 변수를 유지해야 합니다.
let currentFeatureId = null;
function initInteraction(map, datasetId) {
const datasetLayer = map.getDatasetFeatureLayer(datasetId);
// Apply the style function
datasetLayer.style = (params) => {
const isHovered = params.feature.datasetAttributes['id'] === currentFeatureId;
return {
strokeColor: 'green',
strokeWeight: isHovered ? 4.0 : 2.0, // Bold border on hover
fillColor: 'green',
fillOpacity: isHovered ? 0.5 : 0.3,
};
};
// Add interaction listeners
datasetLayer.addListener('mousemove', (event) => {
if (event.features.length > 0) {
currentFeatureId = event.features[0].datasetAttributes['id'];
datasetLayer.style = datasetLayer.style; // Re-apply style to reflect changes
}
});
// Clear hover state when the mouse leaves the features
map.addListener('mousemove', () => {
if (currentFeatureId !== null) {
currentFeatureId = null;
datasetLayer.style = datasetLayer.style;
}
});
}
3. description 속성에서 HTML 표시
KML에서 <description> 태그에는 기본 정보 창의 HTML이 포함되는 경우가 많습니다.
이 데이터를 데이터 세트로 가져오면 description이 특징 속성이 됩니다. 이를 렌더링하려면 문자열을 표준 google.maps.InfoWindow에 직접 전달합니다.
const infoWindow = new google.maps.InfoWindow();
datasetLayer.addListener('click', (event) => {
if (event.features.length > 0) {
const feature = event.features[0];
// Access the HTML description attribute
const htmlContent = feature.datasetAttributes['description'];
infoWindow.setContent(htmlContent);
infoWindow.setPosition(event.latLng);
infoWindow.open(map);
}
});
4. ExtendedData를 사용한 맞춤 정보 창
KML에서 <ExtendedData>를 사용하여 맞춤 이름/값 쌍을 저장하는 경우 datasetAttributes에 매핑됩니다. 이러한 속성을 반복하여 맞춤 HTML 디스플레이를 빌드할 수 있습니다.
function createCustomContent(feature) {
const attributes = feature.datasetAttributes;
const container = document.createElement("div");
container.style.padding = "10px";
container.innerHTML = "<h3>Feature Details</h3><dl></dl>";
const dl = container.querySelector("dl");
// Iterate through all data attributes imported from KML ExtendedData
for (const key in attributes) {
const dt = document.createElement("dt");
dt.style.fontWeight = "bold";
dt.textContent = key;
const dd = document.createElement("dd");
dd.textContent = attributes[key];
dl.appendChild(dt);
dl.appendChild(dd);
}
return container;
}
datasetLayer.addListener('click', (event) => {
if (event.features.length > 0) {
const content = createCustomContent(event.features[0]);
infoWindow.setContent(content);
infoWindow.setPosition(event.latLng);
infoWindow.open(map);
}
});
고급 시각화 기법은 데이터 기능 스타일 지정 방법 관련 개발자 문서를 참고하세요.
이전 권장사항: GeoJSON을 사용한 클라이언트 측 렌더링
KmlLayer에서 GeoJSON 및 데이터 레이어를 사용한 클라이언트 측 렌더링으로 이전하는 개발자를 위해 이 가이드에서는 자동 KML 상호작용에서 맞춤 이벤트 기반 상호작용 및 동적 스타일로 전환하는 방법을 설명합니다.
초기 설정
상호작용을 구현하기 전에 KML 데이터를 GeoJSON으로 변환하고 데이터 레이어로 로드해야 합니다. ogr2ogr 또는 togeojson와 같은 도구를 사용하고 map.data.loadGeoJson()로 지도를 초기화하는 방법에 관한 자세한 내용은 이전 권장사항: GeoJSON을 사용한 클라이언트 측 렌더링 가이드를 참고하세요.
1. 자동 상호작용과 수동 상호작용 비교
이러한 레이어의 주요 차이점은 사용자 입력을 처리하는 방식입니다.
KmlLayer: 지형지물 클릭을 자동으로 처리하고 KMLInfoWindow를 표시합니다.- 데이터 영역:
InfoWindow객체를 자동으로 표시하지 않습니다. 사용자 상호작용을 캡처하려면 이벤트 리스너를 수동으로 추가하고 데이터를 표시하는 코드를 작성해야 합니다.
2. 상호작용 이벤트 처리
GeoJSON 지형지물을 대화형으로 만들려면 map.data 객체에서 addListener() 메서드를 사용합니다. 일반적인 이벤트는 다음과 같습니다.
click: 정보 창 또는 선택 로직을 트리거하는 데 사용됩니다.mouseover/mouseout: 마우스 오버 효과 및 강조 표시에 사용됩니다.
3. 정보 창에 HTML 설명 표시
KML이 GeoJSON으로 변환되면 <description> 태그 (HTML이 포함되는 경우가 많음)가 일반적으로 description이라는 속성에 매핑됩니다. feature.getProperty('description')를 사용하여 이 문자열을 검색하고 표준 google.maps.InfoWindow 내에 렌더링할 수 있습니다.
const infoWindow = new google.maps.InfoWindow();
// Handle clicks to show the HTML description
map.data.addListener('click', (event) => {
// Access the 'description' property from the GeoJSON feature
const htmlContent = event.feature.getProperty('description');
if (htmlContent) {
infoWindow.setContent(htmlContent);
infoWindow.setPosition(event.latLng);
infoWindow.open(map);
}
});
4. 맞춤 정보 창 및 ExtendedData
원래 KML에서 <ExtendedData>를 사용한 경우 이러한 이름-값 쌍은 GeoJSON 속성으로 변환됩니다. 데이터 영역에는 이러한 항목의 기본 UI가 없으므로 맞춤 정보 창을 구현하여 반복하고 표시해야 합니다.
event.feature.getProperty('attribute_name')를 사용하여 이러한 속성에 액세스하고 infoWindow.setContent() 메서드에 전달할 맞춤 HTML 문자열 또는 DOM 요소를 구성할 수 있습니다.
5. 동적 스타일 지정 (마우스 오버 효과)
데이터 영역을 사용하면 이벤트에 대한 응답으로 프로그래매틱 방식으로 기능 스타일을 업데이트할 수 있습니다. overrideStyle()를 사용하여 기능의 모양을 일시적으로 변경하고(예: 마우스 오버 시) revertStyle()를 사용하여 전역 스타일로 돌아갑니다.
// Set a base style for all features
map.data.setStyle({
fillColor: 'blue',
strokeWeight: 1
});
// Highlight feature on mouseover
map.data.addListener('mouseover', (event) => {
map.data.revertStyle(); // Clear previous highlights
map.data.overrideStyle(event.feature, {strokeWeight: 8});
});
// Revert style on mouseout
map.data.addListener('mouseout', (event) => {
map.data.revertStyle();
});
자세한 구현 세부정보는 데이터 영역: 이벤트 처리 및 데이터 영역: 동적 스타일 지정에 관한 문서를 참고하세요.
이전 경로: 서드 파티 라이브러리를 사용한 클라이언트 측 렌더링
KmlLayer에서 서드 파티 솔루션으로 이전하는 개발자를 위해 이 가이드에서는 deck.gl 및 geoxml3를 사용하여 마우스 클릭 및 동적 이벤트와 같은 대화형 데이터를 처리하는 데 중점을 둡니다.
초기 설정
상호작용을 구현하기 전에 이전 경로: 서드 파티 라이브러리를 사용한 클라이언트 측 렌더링 가이드의 설정 단계를 따랐는지 확인하세요. 여기에는 다음이 포함됩니다.
- deck.gl: 벡터 지도 유형 (캔버스 요구사항)을 사용하도록 지도를 변환합니다.
- geoxml3: 자체 호스트에서 라이브러리 스크립트를 제공하고 교차 출처 리소스 공유 (CORS)를 관리합니다.
1. deck.gl을 사용한 대화형 데이터
deck.gl은 KML을 직접 입력 형식으로 지원하며 KML 파일에 제공된 데이터를 기반으로 클릭과 같은 기능 상호작용을 자동으로 처리합니다.
- KMLLoader 처리:
@loaders.gl/kml모듈을 사용하여 지오메트리와 속성이deck.gl에서 기본적으로 상호작용 이벤트를 트리거하는 데 사용하는 형식으로 파싱됩니다. - 기능 클릭수: 기능이 클릭되면
deck.gl가 이벤트를 캡처하고 연결된 메타데이터 (예:<name>또는<description>)를 표시할 수 있습니다. - 예: deckgl-kml-updated 샘플은 지진 마커 위로 마우스를 가져가면 자세한 이벤트 정보가 표시되는 실시간 KML 렌더링을 보여줍니다.
2. geoxml3를 사용한 대화형 데이터
geoxml3는 브라우저에서 KML을 로컬로 파싱하고 스타일 정보를 추출하며 상호작용성을 유지하는 표준 Google 지도 API 객체를 생성합니다.
- 기본 스타일 추출: 라이브러리는 KML에서
<Style>및<StyleMap>요소를 가져와 생성된 마커, 다중선, 다각형에 적용합니다. - 클릭 핸들러: 기본적으로
geoxml3는 이러한 객체에 대한 클릭 핸들러를 제공합니다. 파서 인스턴스화 중에 맞춤 콜백 함수 (createMarker,createOverlay)를 정의하여 자체 선택 로직이나 사이드바 업데이트를 구현할 수도 있습니다. - 예: 이 예에서는 geoxml3를 사용하여 KML을 렌더링하는 방법을 보여줍니다. 마커를 클릭하여 지진 정보를 표시하는 등 상호작용이 있는 원 마커와 같은 맞춤설정이 있습니다.
- 사용 패턴:
var myParser = new geoXML3.parser({
map: map,
processStyles: true, // Automatically handle KML styles
afterParse: function(doc) {
// Code to run after the KML is fully parsed
}
});
myParser.parse('interactive_data.kml');
이미지가 포함된 KML 파일
KmlLayer를 사용하여 위성에서 파생된 데이터, 날씨 패턴 또는 이전 청사진이 포함된 지도와 같은 이미지를 표시하는 개발자를 위해 이 가이드에서는 GroundOverlays 또는 서드 파티 파서로의 이전 경로를 설명합니다.
이전 권장사항: Maps JavaScript API GroundOverlay
이미지를 이전하는 데 권장되는 방법은 google.maps.GroundOverlay 클래스를 사용하는 것입니다. 이렇게 하면 코드에서 직접 특정 지리 좌표에 지도를 배치할 수 있습니다.
1. 구현
경계를 정의하기 위해 KML 파일을 사용하는 대신 이미지 URL과 지도에 있는 직사각형을 나타내는 LatLngBounds 객체를 지정합니다.
- 문서: 지면 오버레이 가이드를 참고하세요.
- 이미지 준비: 이미지가 지리 참조되었지만 올바른 투영 (EPSG:4326)이 아닌 경우 오픈소스 도구
gdalwarp를 사용하여 Maps JS API에서 사용할 이미지를 변형할 수 있습니다.
gdalwarp -t_srs EPSG:4326 image.jp2 image.jpg
이전 경로: 서드 파티 라이브러리 사용
워크플로에서 데이터를 KML 형식으로 유지해야 하는 경우 geoxml3 또는 deck.gl와 같은 서드 파티 라이브러리를 사용하여 이미지 오버레이를 렌더링할 수 있습니다.
면책 조항: 이러한 서드 파티 솔루션은 Google에서 지원되지 않습니다. 하지만 테스트를 거쳤으며 대부분의 사용 사례에서 작동합니다.
1. geoxml3
geoxml3는 브라우저에서 간단한 GroundOverlay 요소를 로컬로 파싱하고 이를 Google 지도 API 객체로 변환하는 데 적합합니다.
사용 예:
const geoXmlParser = new geoXML3.parser({
map: map,
afterParse: function(doc) {
console.log("Parsing complete. Number of documents: " + doc.length);
const bounds = doc[0].gbounds;
if (bounds && !bounds.isEmpty()) {
map.fitBounds(bounds);
}
},
createOverlay: function(groundOverlayData) {
// Extract bounds and URL from parsed KML data
const imageUrl = groundOverlayData.icon.href;
const imageBounds = {
north: parseFloat(groundOverlayData.latLonBox.north),
south: parseFloat(groundOverlayData.latLonBox.south),
east: parseFloat(groundOverlayData.latLonBox.east),
west: parseFloat(groundOverlayData.latLonBox.west)
};
// Create the Google Maps GroundOverlay
const nativeOverlay = new google.maps.GroundOverlay(imageUrl, imageBounds);
nativeOverlay.setMap(map);
}
});
geoXmlParser.parse('your_file.kml');
2. deck.gl
deck.gl의 표준 GeoJsonLayer는 벡터 데이터를 처리하지만 BitmapLayer를 사용하는 수동 구현을 통해 GroundOverlays도 지원할 수 있습니다.
이 접근 방식에서는 KMLLoader를 활용하여 파일을 파싱한 다음 KML 데이터에서 추출한 이미지 URL과 좌표를 사용하여 BitmapLayer를 명시적으로 정의합니다.
- 요구사항:
deck.gl를 사용하려면 벡터 지도 유형이 필요합니다. - 문서: deck.gl 비트맵 레이어
고급 사례: gdal2tiles를 사용하여 타일 피라미드 만들기
이미지 타일 피라미드가 포함된 복잡한 KML 파일의 경우 마이그레이션이 더 어렵고 이미지 데이터를 추출해야 합니다.
- 도구:
gdal2tiles는 KMZ 피라미드에서 데이터를 추출하고 타일을 표시하는 표준 Maps JavaScript API 코드를 생성할 수 있습니다. 최종 결과를 기존 지도에 통합하려면 수동으로 수정해야 할 수도 있습니다.
gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz
네트워크 링크가 있는 KML 파일
네트워크 링크가 있는 KML 파일을 처리하려면 KmlLayer의 자동 클라우드 측 가져오기에서 더 명시적인 데이터 관리 전략으로 전환해야 합니다.
지원되는 솔루션: 데이터 세트를 위한 데이터 기반 스타일 지정 (DDS)
Google Maps Platform 데이터 세트는 기본적으로 <NetworkLink> 요소를 파싱하지 않으므로 데이터 구조에 따라 마이그레이션 전략을 선택해야 합니다.
- 전략 A: 개별 데이터 세트 (사용자 제어 레이어에 가장 적합) 이전에 네트워크 링크였던 각 KML 파일을 Google Cloud 콘솔에 개별 데이터 세트로 업로드합니다. 그런 다음 JavaScript를 사용하여
map.getDatasetFeatureLayer(datasetId)를 호출하고 가시성 또는 스타일을 조정하여 필요할 때 이러한 레이어를 동적으로 로드하고 표시할 수 있습니다. - 전략 B: 병합된 KML 파일 (고성능 디스플레이에 가장 적합) 다양한 네트워크 연결 파일의 모든 기능을 하나의 포괄적인 KML 파일로 결합한 후 데이터 세트로 업로드합니다. 그런 다음 특성 속성을 기반으로 동적 스타일 지정을 사용하여 특정 데이터 하위 집합을 즉시 필터링하고 표시할 수 있습니다.
동적 데이터 업데이트: 네트워크 링크의 '자동 새로고침' 동작을 모방하려면 소스 데이터가 변경될 때마다 데이터 세트 API를 사용하여 데이터 세트의 새 버전을 프로그래매틱 방식으로 업로드하세요.
오픈소스 솔루션: deck.gl 및 geoxml3
deck.gl와 geoxml3 모두 KML <NetworkLink> 요소를 파싱하고 자동으로 가져오는 기능을 강력하게 지원하지는 않습니다.
deck.gl
deck.gl는 명시적으로 NetworkLink를 지원하지 않는 KMLLoader (togeojson 기반)를 사용합니다.
- 좋은 솔루션이 아닌 이유: 파서는 안정성과 단순성을 보장하기 위해 자체 네트워크 요청을 하지 않는 동기식 '간편한' 변환기로 설계되었습니다. 애플리케이션이 여러 다른 URL을 가리키는 KML 파일을 사용하는 경우
deck.gl에서 자동으로 해결하지 않습니다.
geoxml3
geoxml3는 Maps JS API용 KML을 파싱하기 위해 개발되었지만 네트워크 링크 지원은 실험적이며 유지관리되지 않습니다.
- 좋은 해결책이 아닌 이유: 이 기능은 오래되고 테스트가 제대로 이루어지지 않은 특정 'network_link' 브랜치에만 있습니다. 복잡한 링크 구조나 CORS와 같은 최신 보안 요구사항을 처리하지 못할 수 있으므로 프로덕션 데이터 마이그레이션에 이 방법을 사용하는 것은 권장되지 않습니다.
요약 추천
안정적인 이전을 위해 개발자는 네트워크 링크가 있는 파일에 서드 파티 파서를 사용하지 말고 데이터 세트 API를 사용하여 데이터 가져오기 로직을 재빌드해야 합니다. 이렇게 하면 유지관리되지 않는 클라이언트 측 파서를 사용하는 대신 Google Maps Platform 인프라 내에서 데이터를 안전하게 관리할 수 있습니다.
KML을 사용하여 화면 오버레이 표시
KmlLayer에서 데이터 기반 스타일 지정 (DDS)과 같은 최신 대안으로 이전하는 개발자는 데이터 세트에서 화면 오버레이가 지원되지 않는다는 점에 유의해야 합니다. 고정된 이미지, 로고 또는 범례를 지도 위에 표시하는 것과 동일한 효과를 내려면 Maps JavaScript API를 사용하여 맞춤 컨트롤을 만들어야 합니다.
1. KML 파일에서 확인할 사항
이에 상응하는 맞춤 컨트롤을 빌드하려면 KML 파일에서 다음 주요 속성에 대해 <ScreenOverlay> 요소를 검사하세요.
<Icon><href>: 표시할 이미지의 URL입니다.<screenXY>: 오버레이가 화면에 배치되는 위치를 정의합니다.x=0, y=1(분수)는 왼쪽 상단에 해당합니다.x=1, y=1는 오른쪽 상단에 해당합니다.x=0, y=0는 왼쪽 하단에 해당합니다.x=1, y=0는 오른쪽 하단에 해당합니다.
<size>: 오버레이의 너비와 높이를 정의합니다.<rotation>: 이미지를 회전해야 하는지 나타냅니다.
2. 구현: 맞춤 컨트롤 만들기
맞춤 컨트롤은 기본적으로 지도에 사전 정의된 위치 중 하나로 '푸시'되는 표준 HTML 요소 (예: <div> 또는 <img>)입니다.
KML 위치를 ControlPosition에 매핑
Maps JavaScript API는 ControlPosition enum을 사용하여 컨트롤을 고정합니다. 아래 표를 사용하여 KML <screenXY>을 적절한 JS API 상수에 매핑하세요.
KML 위치 (screenXY)
|
JS API ControlPosition
|
왼쪽 상단 (x:0, y:1)
|
TOP_LEFT (기존) 또는 BLOCK_START_INLINE_START (논리적)
|
오른쪽 상단 (x:1, y:1)
|
TOP_RIGHT 또는 BLOCK_START_INLINE_END
|
왼쪽 하단 (x:0, y:0)
|
BOTTOM_LEFT 또는 BLOCK_END_INLINE_START
|
오른쪽 하단 (x:1, y:0)
|
BOTTOM_RIGHT 또는 BLOCK_END_INLINE_END
|
3. 이전 예: 고정된 로고 오버레이
다음 예는 지도의 오른쪽 상단에 배치된 KML ScreenOverlay 로고를 모방합니다.
CSS 스타일 지정
CSS를 사용하여 '오버레이'의 크기와 모양을 정의합니다.
#logo-control {
padding: 10px;
background-color: rgba(255, 255, 255, 0.8);
margin: 10px;
border-radius: 2px;
box-shadow: 0 1px 4px rgba(0,0,0,0.3);
}
#logo-control img {
width: 150px; /* Equivalent to KML <size> */
display: block;
}
JavaScript 구현
map.controls 배열에 요소를 추가합니다.
function initMap() {
const map = new google.maps.Map(document.getElementById("map"), {
zoom: 12,
center: { lat: 41.85, lng: -87.65 },
});
// 1. Create the container for the overlay
const logoControlDiv = document.createElement("div");
logoControlDiv.id = "logo-control";
// 2. Create the image (KML <Icon>)
const logoImage = document.createElement("img");
logoImage.src = "https://example.com/logo.png";
logoImage.alt = "Company Logo";
logoControlDiv.appendChild(logoImage);
// 3. Position the control (KML <screenXY>)
// In this case, we use TOP_RIGHT
map.controls[google.maps.ControlPosition.TOP_RIGHT].push(logoControlDiv);
}