15주년을 맞이한 Google Maps Platform - 최신 뉴스 및 공지사항 확인하기

지면 오버레이

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

코드 샘플

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 객체에 지면 오버레이를 추가하는 방법을 보여줍니다.

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

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

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

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

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

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

오버레이 삭제

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

imageOverlay.remove();

오버레이 변경

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

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

// Update the GroundOverlay with a new image of the same dimensions.
imageOverlay = map.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1975));

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

지면 오버레이 위치 지정

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

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

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

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

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

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

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로 고정하여 이미지를 지도에 배치합니다.

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()를 사용하여 데이터 객체를 가져올 수 있습니다.

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

private GoogleMap mMap;
private GroundOverlay mSydneyGroundOverlay;

mSydneyGroundOverlay = mMap.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206))
    .clickable(true));

mSydneyGroundOverlay.setTag("Sydney");

다음은 데이터를 지면 오버레이와 함께 저장하고 검색하는 것이 유용한 경우입니다.

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

지면 오버레이 이벤트 처리

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

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