지면 오버레이

플랫폼 선택: Android iOS JavaScript

지면 오버레이는 위도/경도 좌표에 연결된 이미지 오버레이로, 지도를 드래그하거나 확대/축소하면 움직입니다.

코드 샘플

GitHub의 ApiDemos 저장소에는 지면 오버레이를 보여주는 샘플이 있습니다.

• GroundOverlayDemoActivity - Java: Java의 지면 오버레이 기능 및 리스너
• GroundOverlayDemoActivity - Kotlin: Kotlin의 지면 오버레이 기능 및 리스너

소개

지면 오버레이는 지도에 고정된 이미지입니다. 마커와 달리 화면이 아닌 지표면을 기준으로 방향이 정해지므로, 지도를 회전하거나 기울이거나 확대/축소하면 이미지의 방향이 바뀝니다. 지면 오버레이는 단일 이미지를 지도의 한 영역에 고정하려는 경우에 유용합니다. 지도의 상당 부분을 덮는 광범위한 이미지를 추가하려면 타일 오버레이를 사용하는 것이 좋습니다.

오버레이 추가

GroundOverlay를 추가하려면 이미지와 위치를 모두 정의하는 GroundOverlayOptions 객체를 만드세요. 선택사항으로 지도에서의 이미지 배치에 영향을 미치는 추가 설정을 지정할 수도 있습니다. 필요한 옵션을 정의한 후 GoogleMap.addGroundOverlay() 메서드에 객체를 전달하여 이미지를 지도에 추가합니다. addGroundOverlay() 메서드가 GroundOverlay 객체를 반환합니다. 나중에 이 객체를 수정하려면 객체에 대한 참조를 보관하고 있어야 합니다.

참고: 이미지가 지도에 추가되면 변의 길이가 2의 거듭제곱인 이미지로 변환됩니다. 변의 길이가 2의 거듭제곱인 원본 이미지(예: 128x512 또는 1024x1024)를 사용하면 이와 같은 변환이 일어나지 않습니다.

방법:

1. 새 GroundOverlayOptions 객체를 인스턴스화합니다.
2. 이미지를 BitmapDescriptor로 지정합니다.
3. 이용 가능한 메서드 중 하나를 사용하여 이미지의 위치를 설정합니다.
   • position(LatLng location, float width, float height)
   • position(LatLng location, float width)
   • positionFromBounds(LatLngBounds bounds)
4. 선택사항인 속성(예: transparency)을 원하는 대로 설정합니다.
5. GoogleMap.addGroundOverlay()를 호출하여 이미지를 지도에 추가합니다.

아래의 예는 기존 GoogleMap 객체에 지면 오버레이를 추가하는 방법을 보여줍니다.

Kotlin

val newarkLatLng = LatLng(40.714086, -74.228697)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f)
map.addGroundOverlay(newarkMap)

      

Java

LatLng newarkLatLng = new LatLng(40.714086, -74.228697);

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f);
map.addGroundOverlay(newarkMap);

      

지면 오버레이를 지도에 추가한 후 변경하거나 삭제하려면 GroundOverlay 객체를 보유하고 있어야 합니다. 나중에 이 객체를 변경하여 오버레이를 수정할 수 있습니다.

Kotlin

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
val imageOverlay = map.addGroundOverlay(newarkMap)

      

Java

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);

      

오버레이 삭제

GroundOverlay.remove() 메서드를 사용하여 지면 오버레이를 삭제할 수 있습니다.

Kotlin

imageOverlay?.remove()

      

Java

imageOverlay.remove();

      

오버레이 변경

지면 오버레이 이미지가 지도에 추가된 후에 GroundOverlay.setImage(BitmapDescriptor) 메서드를 사용하여 해당 이미지를 변경할 수 있습니다.

Kotlin

// Update the GroundOverlay with a new image of the same dimension

// Update the GroundOverlay with a new image of the same dimension
imageOverlay?.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))

      

Java

// Update the GroundOverlay with a new image of the same dimension
imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));

      

setImage() 메서드는 기존 이미지를 동일한 크기의 다른 이미지로 대체합니다.

지면 오버레이 위치 지정

지면 오버레이의 위치를 지정하는 데는 두 가지 방법이 있습니다.

• LatLng를 사용하여 오버레이의 중심을 맞추고 이미지의 크기를 미터 단위로 지정합니다.
• LatLngBounds를 사용하여 이미지의 북동쪽 및 남서쪽 모서리를 지정합니다.

지면 오버레이를 지도에 추가하기 전에 지면 오버레이의 위치를 지정해야 합니다.

위치를 사용하여 이미지 배치

이미지를 추가할 때에는 앵커를 고정할 LatLng 및 오버레이의 너비(단위: 미터)를 지정합니다. anchor는 기본적으로 이미지의 중심에 고정됩니다. 선택사항으로 오버레이의 길이(단위: 미터)를 지정할 수도 있습니다. 오버레이의 길이를 지정하지 않으면 이미지의 비율을 유지하도록 자동으로 계산됩니다.

아래의 코드는 너비가 8.6km이고 길이가 6.5km인 40.714086, -74.228697 위치에 이미지를 배치합니다. 이미지는 왼쪽 하단에 고정됩니다.

Kotlin

val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0f, 1f)
    .position(LatLng(40.714086, -74.228697), 8600f, 6500f)

      

Java

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0, 1)
    .position(new LatLng(40.714086, -74.228697), 8600f, 6500f);

      

LatLngBounds를 사용하여 이미지 위치 지정

이미지가 포함된 LatLngBounds를 제공합니다. LatLngBounds는 이미지의 북동쪽 및 남서쪽 모서리를 지정합니다. 이미지는 지도에 그려질 때 경계에 맞춰 회전합니다. 경계가 원래의 가로세로 비율과 일치하지 않으면 이미지가 왜곡됩니다.

아래의 코드에서는 이미지의 남서쪽 모서리를 40.712216,-74.22655, 북동쪽 모서리를 40.773941, -74.12544로 고정하여 지도에 이미지를 배치합니다.

Kotlin

val newarkBounds = LatLngBounds(
    LatLng(40.712216, -74.22655),  // South west corner
    LatLng(40.773941, -74.12544)   // North east corner
)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds)

      

Java

LatLngBounds newarkBounds = new LatLngBounds(
    new LatLng(40.712216, -74.22655),       // South west corner
    new LatLng(40.773941, -74.12544));      // North east corner
GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds);

      

데이터를 지면 오버레이와 연결

GroundOverlay.setTag()를 호출하여 임의의 데이터 객체를 지면 오버레이와 함께 저장하고, GroundOverlay.getTag()를 사용하여 데이터 객체를 가져올 수 있습니다.

다음 코드 샘플은 지면 오버레이와 함께 문자열 설명을 저장합니다.

Kotlin

val sydneyGroundOverlay = map.addGroundOverlay(
    GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
        .position(LatLng(-33.873, 151.206), 100f)
        .clickable(true)
)
sydneyGroundOverlay?.tag = "Sydney"

      

Java

GroundOverlay sydneyGroundOverlay = map.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206), 100)
    .clickable(true));

sydneyGroundOverlay.setTag("Sydney");

      

다음과 같은 경우에 데이터를 지면 오버레이와 함께 저장하고 검색하면 도움이 됩니다.

• 앱에서 여러 지면 오버레이를 지원하고 있으며 사용자가 각 지면 오버레이를 클릭할 때마다 다르게 처리하고자 하는 경우
• 고유한 레코드 식별자가 있는 시스템과 연결하고 여기서 오버레이가 해당 시스템의 특정 레코드를 나타내는 경우
• 오버레이 데이터가 오버레이의 Z-색인을 결정하는 우선순위를 나타낼 수 있는 경우

지면 오버레이 이벤트 처리

기본적으로 지면 오버레이는 클릭할 수 없습니다. GroundOverlay.setClickable(boolean)을 호출하여 클릭 가능 여부를 사용 설정 또는 사용 중지할 수 있습니다.

OnGroundOverlayClickListener를 사용하여 클릭 가능한 지면 오버레이에 대한 클릭 이벤트를 수신합니다. 지도에 이 리스너를 설정하려면 GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener)를 호출하세요. 사용자가 지면 오버레이를 클릭하면 onGroundOverlayClick(GroundOverlay) 콜백을 수신하게 됩니다.

참고: 여러 오버레이 또는 도형(마커, 다중선, 다각형, 원, 지면 오버레이)이 겹치는 경우에는, 클릭 이벤트가 먼저 마커의 클러스터를 통해 순환된 다음 클릭 가능한 다른 오버레이 또는 도형에 대해 Z-색인 값을 기반으로 트리거됩니다. 클릭당 한 개 이하의 이벤트가 트리거됩니다. 즉 Z-색인 값이 더 낮은 오버레이나 도형에는 클릭이 전달되지 않습니다. 마커 Z-색인 및 클릭 이벤트에 대해 자세히 알아보세요.