지면 오버레이

플랫폼 선택: Android iOS JavaScript

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

코드 샘플

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

소개

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

오버레이 추가

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

방법:

  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) 콜백을 수신하게 됩니다.