[Android / Kotlin] (3) 네이버 지도 API - 카메라

📷 카메라

네이버 지도 SDK는 기기 화면 건너편의 지도를 카메라로 바라보는 방식으로 지도를 표현합니다.
카메라를 이동, 확대 및 축소, 기울임, 회전시킴으로써 화면에 보이는 지도를 자유자재로 움직일 수 있습니다.

카메라의 위치

카메라의 위치는 카메라가 놓여 있는 대상 지점의 좌표와 줌 레벨, 기울기, 베어링으로 구성됩니다.

1. 대상 지점
   : target은 카메라가 놓여 있는 대상 지점의 좌표를 나타내는 속성입니다. 대상 지점이 변경되면 지도가 동서남북으로 움직입니다.

2. 줌 레벨
   : zoom은 카메라의 줌 레벨을 나타내는 속성입니다.
   줌 레벨은 지도의 축척을 나타냅니다.
   즉, 줌 레벨이 작을수록 지도가 축소되고 클수록 확대됩니다.
   줌 레벨이 커지면 지도에 나타나는 정보도 더욱 세밀해집니다.

3. 기울임 각도
   : tilt는 카메라의 기울임 각도를 나타내는 속성입니다.
   카메라는 기울임 각도만큼 지면을 비스듬하게 내려다봅니다.
   기울임 각도가 0도이면 카메라가 지면을 수직으로 내려다보며, 각도가 증가하면 카메라의 시선도 점점 수평에 가깝게 기울어집니다.
   따라서 기울임 각도가 클수록 더 먼 곳을 볼 수 있게 됩니다.
   카메라가 기울어지면 화면에 보이는 지도에 원근감이 적용됩니다.
   즉, 화면의 중심을 기준으로 먼 곳은 더 작게 보이고 가까운 곳은 더 크게 보입니다.

4. 베어링 각도
   : bearing은 카메라의 베어링 각도를 나타내는 속성입니다.
   베어링은 카메라가 바라보는 방위를 의미합니다.
   카메라가 정북 방향을 바라볼 때 베어링 각도는 0도이며, 시계 방향으로 값이 증가합니다.
   즉, 동쪽을 바라볼 때 90도, 남쪽을 바라볼 때 180도가 됩니다.

CameraPosition 객체

CameraPosition은 카메라의 위치를 나타내는 클래스입니다.
CameraPosition의 모든 속성은 final이므로 생성자로만 지정할 수 있고, 한 번 생성된 객체의 속성은 변경할 수 없습니다.

CameraPosition 객체를 생성할 때 기울임 각도와 베어링 각도는 생략할 수 있습니다. 생략할 경우 0으로 지정됩니다.

카메라 이동

카메라는 API 호출, 사용자의 제스처 등 다양한 방법으로 움직일 수 있습니다.
API를 호출해 카메라를 움직이려면 CameraUpdate 객체와 moveCamera() 메서드를 사용합니다.
CameraUpdate의 다양한 속성을 사용해 카메라의 위치, 애니메이션, 콜백 등을 지정할 수 있습니다.

API 호출로 카메라 이동하기

카메라를 움직이려면 먼저 카메라를 어떻게 움직일지를 나타내는 CameraUpdate 객체를 생성해야 합니다.
CameraUpdate는 카메라를 이동할 위치, 방법 등을 정의하는 클래스입니다.
CameraUpdate 객체는 오직 팩토리 메서드를 이용해서 생성할 수 있으며, CameraUpdate 클래스에 다양한 팩토리 메서드가 정의되어 있습니다.

• toCameraPosition()
  : 카메라의 위치를 지정한 CameraPosition으로 움직입니다.

• scrollTo()
  : 카메라의 대상 지점을 지정한 좌표로 변경합니다.

• scrollBy()
  : 카메라의 대상 지점을 지정한 픽셀만큼 상하좌우로 이동합니다.

• zoomTo()
  : 카메라의 줌 레벨을 지정한 값으로 변경합니다.

• fitBounds()
  : 영역이 온전히 보이는 좌표와 최대 줌 레벨로 카메라의 위치를 변경합니다.

카메라 이동 콜백

finishCallback() 및 cancelCallback()으로 콜백 객체를 지정하면 해당하는 CameraUpdate에 대한 카메라 이동이 완료됐거나 실패했을 때 콜백을 받을 수 있습니다.
카메라 이동에 애니메이션이 지정되어 있고 그 애니메이션이 취소되었을 경우 cancelCallback()에 지정된 콜백이 호출되고, 그 외의 경우에는 finishCallback()에 지정된 콜백이 호출됩니다.
즉, 카메라 이동에 애니메이션이 지정되지 않았으면 카메라 이동은 항상 성공적으로 완료된 것으로 간주됩니다.

카메라 변경 이벤트

어떤 이유에 의해서건 카메라가 움직이면 카메라 변경 이벤트가 발생합니다.
NaverMap.addOnCameraChangeListener() 메서드로 OnCameraChangeListener를 등록하면 카메라 변경 이벤트를 받을 수 있습니다.
카메라의 위치가 변경되면 onCameraChange() 콜백 메서드가 호출됩니다.

onCameraChange()에는 reason과 animated 파라미터가 전달됩니다.
reason은 이벤트를 발생시킨 카메라 이동의 원인입니다.
CameraUpdate.reason()을 호출해 카메라 이동의 원인을 지정할 수 있으며, 이벤트 리스너 내에서 이 값을 이용해 어떤 원인에 의해 발생한 이벤트인지를 판단할 수 있습니다.
제스처, 컨트롤 등 네이버 지도 SDK의 내장 기능에 의해 카메라가 이동한 경우 미리 정의된 음숫값을 가지며, 개발자가 임의의 양숫값을 지정할 수도 있습니다.

• REASON_DEVELOPER
  : reason의 기본값으로, 개발자가 API를 호출해 카메라가 움직였음을 나타냅니다.

• REASON_GESTURE
  : 사용자의 제스처로 인해 카메라가 움직였음을 나타냅니다.

• REASON_CONTROL
  : 사용자의 버튼 선택으로 인해 카메라가 움직였음을 나타냅니다.

• REASON_LOCATION
  : 위치 트래킹 기능으로 인해 카메라가 움직였음을 나타냅니다.

카메라 대기 이벤트

카메라의 움직임이 끝나 대기 상태가 되면 카메라 대기 이벤트가 발생합니다.
NaverMap.addOnCameraIdleListener() 메서드로 OnCameraIdleListener를 등록하면 카메라 대기 이벤트를 받을 수 있습니다.
카메라가 대기 상태가 되면 onCameraIdle() 콜백 메서드가 호출됩니다.

• 카메라가 애니메이션 없이 움직일 때.
  단, 사용자가 제스처로 지도를 움직이는 경우 제스처가 완전히 끝날 때까지(ACTION_UP이 발생할 때까지)는 연속적인 이동으로 간주되어 이벤트가 발생하지 않습니다.
• 카메라 애니메이션이 완료될 때.
  단, 카메라 애니메이션이 진행 중일 때 새로운 애니메이션이 발생하거나, 기존 카메라 이동의 finishCallback() 또는 cancelCallback()으로 지정된 콜백 내에서 카메라 이동이 일어날 경우
  연속적인 이동으로 간주되어 이벤트가 발생하지 않습니다.
• NaverMap.cancelTransitions()가 호출되어 카메라 애니메이션이 명시적으로 취소될 때.