Camera Movement

You can move the camera by making API calls or using user gestures. To move the camera by calling an API, you should use the CameraUpdate object and the moveCamera() method. With various properties of the CameraUpdate, you can specify the camera position, animations, callbacks, and so on.

Move the camera by making API calls

To move the camera, you should first create a CameraUpdate object which determines how a camera moves. CameraUpdate is a class that defines where and how a camera moves. You can create a CameraUpdate object only by using factory methods, which are defined in the CameraUpdate. The list below describes some factory methods.

• toCameraPosition(): Moves the position of the camera to the specified CameraPosition.
• scrollTo(): Sets the target point of the camera to the specified coordinates.
• scrollBy(): Moves the target point of the camera up, down, left or right by the specified pixels.
• zoomTo(): Sets the zoom level of the camera to the specified value.
• fitBounds(): Changes the camera position to the coordinates where the whole area is shown, with the maximum zoom level.

Make a call to NaverMap.moveCamera() with the created object as a parameter, and the camera moves.

The following code example creates a CameraUpdate object that changes the target point to (37.5666102, 126.9783881), and calls the NaverMap.moveCamera() method to move the camera.

CameraUpdate cameraUpdate =
    CameraUpdate.scrollTo(new LatLng(37.5666102, 126.9783881));
naverMap.moveCamera(cameraUpdate);

CameraUpdate cameraUpdate =
    CameraUpdate.scrollTo(new LatLng(37.5666102, 126.9783881));
naverMap.moveCamera(cameraUpdate);

val cameraUpdate = CameraUpdate.scrollTo(LatLng(37.5666102, 126.9783881))
naverMap.moveCamera(cameraUpdate)

Animation

Before calling the moveCamera() by using the CameraUpdate object, you can call CameraUpdate.animate() to animate the camera movement. When an animation is specified, the camera slowly moves to the target point during the specified period of time.

Animation types

Using CameraUpdate.animate(), you can animate the camera movement. The animate() method receives the CameraAnimation object, which represents animation types, as a parameter. Animation types defined in the CameraAnimation enum are listed below.

• None: Moves without animation. It is the default value.
• Linear: Moves at a regular speed.
• Easing: Naturally accelerates and decelerates. It is appropriate for moving a short distance.
• Fly: Naturally gets smaller and then larger. It is appropriate for moving a long distance.

The following code example adds the Easing animation to the camera movement.

CameraUpdate cameraUpdate =
    CameraUpdate.scrollTo(new LatLng(37.5666102, 126.9783881))
        .animate(CameraAnimation.Easing);
naverMap.moveCamera(cameraUpdate);

CameraUpdate cameraUpdate =
    CameraUpdate.scrollTo(new LatLng(37.5666102, 126.9783881))
        .animate(CameraAnimation.Easing);
naverMap.moveCamera(cameraUpdate);

val cameraUpdate = CameraUpdate.scrollTo(LatLng(37.5666102, 126.9783881))
        .animate(CameraAnimation.Easing)
naverMap.moveCamera(cameraUpdate)

Duration

By specifying the duration parameter of the animate() method, you can change the duration of animations. Note that if the animation type is None, the duration is ignored. Also note that if the duration is 0, the camera moves without animation although an animation type is specified.

The following code example add the Fly animation to the camera movement and sets the duration to 1 sec.

CameraUpdate cameraUpdate =
    CameraUpdate.scrollTo(new LatLng(37.5666102, 126.9783881))
        .animate(CameraAnimation.Fly, 1000);
naverMap.moveCamera(cameraUpdate);

CameraUpdate cameraUpdate =
    CameraUpdate.scrollTo(new LatLng(37.5666102, 126.9783881))
        .animate(CameraAnimation.Fly, 1000);
naverMap.moveCamera(cameraUpdate);

val cameraUpdate = CameraUpdate.scrollTo(LatLng(37.5666102, 126.9783881))
        .animate(CameraAnimation.Fly, 1000)
naverMap.moveCamera(cameraUpdate)

If the duration is not specified, the default animation duration of the map applies. You can change the default animation duration, by using the defaultCameraAnimationDuration property of the NaverMap.

The following code example changes the default animation duration of the map to 500 ms.

naverMap.setDefaultCameraAnimationDuration(500);

naverMap.setDefaultCameraAnimationDuration(500);

naverMap.defaultCameraAnimationDuration = 500

Cancel animations

The camera movement animation can be cancelled for a variety of reasons. When you call NaverMap.moveCamera() to start a new camera movement, the previous camera movement is automatically cancelled.

The following code example starts a camera animation with the duration of 2 seconds and 1 second later, starts a new camera movement to cancel the previous camera animation.

LatLng coord1 = new LatLng(37.5666102, 126.9783881);
LatLng coord2 = new LatLng(37.57000, 126.97618);

// Camera animation for 2 sec.
naverMap.moveCamera(CameraUpdate.scrollTo(coord1)
    .animate(CameraAnimation.Easing, 2000));

// 1 sec later, a new camera movement starts and the previous camera animation
// is cancelled.
new Handler().postDelayed(() -> {
    naverMap.moveCamera(CameraUpdate.scrollTo(coord2)
        .animate(CameraAnimation.Easing))
}, 1000);

LatLng coord1 = new LatLng(37.5666102, 126.9783881);
LatLng coord2 = new LatLng(37.57000, 126.97618);

// Camera animation for 2 sec.
naverMap.moveCamera(CameraUpdate.scrollTo(coord1)
    .animate(CameraAnimation.Easing, 2000));

// 1 sec later, a new camera movement starts and the previous camera animation
// is cancelled.
new Handler().postDelayed(() -> {
    naverMap.moveCamera(CameraUpdate.scrollTo(coord2)
        .animate(CameraAnimation.Easing))
}, 1000);

val coord1 = LatLng(37.5666102, 126.9783881)
val coord2 = LatLng(37.57000, 126.97618)
// Camera animation for 2 sec.
naverMap.moveCamera(CameraUpdate.scrollTo(coord1)
        .animate(CameraAnimation.Easing, 2000))

// 1 sec later, a new camera movement starts and the previous camera animation
// is cancelled.
Handler().postDelayed({
    naverMap.moveCamera(CameraUpdate.scrollTo(coord2)
            .animate(CameraAnimation.Easing))
}, 1000)

You can also use NaverMap.cancelTransitions() to explicitly cancel the camera animation. When this method is invoked, the current camera animation is cancelled and the camera stops at the current position. With the stop gesture enabled, if a user taps the map, the same result occurs.

The following code example calls cancelTransitions() to cancel the camera animation.

// Camera animation for 2 sec.
naverMap.moveCamera(CameraUpdate.scrollTo(coord1)
    .animate(CameraAnimation.Easing, 2000));

// 1 sec later, cancelTransitions() is called and the previous camera animation
// is cancelled.
new Handler().postDelayed(() -> {
    naverMap.cancelTransitions();
}, 1000);

// Camera animation for 2 sec.
naverMap.moveCamera(CameraUpdate.scrollTo(coord1)
    .animate(CameraAnimation.Easing, 2000));

// 1 sec later, cancelTransitions() is called and the previous camera animation
// is cancelled.
new Handler().postDelayed(() -> {
    naverMap.cancelTransitions();
}, 1000);

// Camera animation for 2 sec.
naverMap.moveCamera(CameraUpdate.scrollTo(coord1)
        .animate(CameraAnimation.Easing, 2000))

// 1 sec later, cancelTransitions() is called and the previous camera animation
// is cancelled.
Handler().postDelayed({
    naverMap.cancelTransitions()
}, 1000)

Callback and event

With the callback property of CameraUpdate, you can get a result called back for a camera movement. You can also add an event listener to NaverMap to get events for all camera movements in your map.

Camera movement callback

Set a callback object with finishCallback() and cancelCallback(), and you can get a callback when a camera movement for the CameraUpdate is finished or cancelled. If an animation set for camera movements is cancelled, a callback set in cancelCallback() is called; otherwise, the one set in finishCallback() is called. In other words, if no animation is set for camera movements, a camera movement is always considered to be successfully finished.

The following code example sets a callback that displays toast messages when a camera movement is finished or cancelled.

CameraUpdate cameraUpdate =
    CameraUpdate.scrollTo(new LatLng(37.5666102, 126.9783881))
        .animate(CameraAnimation.Easing, 2000)
        .finishCallback(() -> {
            Toast.makeText(context, "Camera movement finished",
             Toast.LENGTH_SHORT).show();
        })
        .cancelCallback(() -> {
            Toast.makeText(context, "Camera movement cancelled",
             Toast.LENGTH_SHORT).show();
        });

naverMap.moveCamera(cameraUpdate);

CameraUpdate cameraUpdate =
    CameraUpdate.scrollTo(new LatLng(37.5666102, 126.9783881))
        .animate(CameraAnimation.Easing, 2000)
        .finishCallback(() -> {
            Toast.makeText(context, "Camera movement finished",
             Toast.LENGTH_SHORT).show();
        })
        .cancelCallback(() -> {
            Toast.makeText(context, "Camera movement cancelled",
             Toast.LENGTH_SHORT).show();
        });

naverMap.moveCamera(cameraUpdate);

val cameraUpdate = CameraUpdate.scrollTo(LatLng(37.5666102, 126.9783881))
        .animate(CameraAnimation.Easing, 2000)
        .finishCallback {
            Toast.makeText(context, "Camera movement finished",
                    Toast.LENGTH_SHORT).show()
        }
        .cancelCallback {
            Toast.makeText(context, "Camera movement cancelled",
                    Toast.LENGTH_SHORT).show()
        }

naverMap.moveCamera(cameraUpdate)

Camera change event

For whatever reason, if a camera moves, an event occurs. Add OnCameraChangeListener using the NaverMap.addOnCameraChangeListener() method, and you can receive a camera change event. When the camera’s position is changed, the onCameraChange() callback method is called.

The parameters, reason and animated are passed to onCameraChange(). The reason parameter is a reason for the camera movement that triggers an event. You can call CameraUpdate.reason() to specify a camera movement reason, which can be used by the event listener to determine why an event occurred. The parameter has a pre-defined negative number if the camera movement is made by the NAVER Maps SDK’s embedded features including gestures and controls; you can also define a positive number for other reasons. Pre-defined reasons are as follows:

• REASON_DEVELOPER: Indicates that the camera moved by the developer’s API call. It is the default value.
• REASON_GESTURE: Indicates that the camera moved in response to a user’s gesture.
• REASON_CONTROL: Indicates that the camera moved in response to a user’s button tapping.
• REASON_LOCATION: Indicates that the camera moved by the location tracking feature.

The animated parameter indicates whether an animation is set for the camera movement that triggers an event.

The following code example adds an event listener that logs reasons for camera changes and sets a reason to move the camera.

naverMap.addOnCameraChangeListener((reason, animated) -> {
    Log.i("NaverMap",
        "Camera change - reson: " + reason + ", animated: " + animated);
});

CameraUpdate cameraUpdate =
    CameraUpdate.scrollTo(new LatLng(37.5666102, 126.9783881))
        .animate(CameraAnimation.Easing, 2000)
        .reason(1000);

naverMap.moveCamera(cameraUpdate);

naverMap.addOnCameraChangeListener((reason, animated) -> {
    Log.i("NaverMap",
        "Camera change - reson: " + reason + ", animated: " + animated);
});

CameraUpdate cameraUpdate =
    CameraUpdate.scrollTo(new LatLng(37.5666102, 126.9783881))
        .animate(CameraAnimation.Easing, 2000)
        .reason(1000);

naverMap.moveCamera(cameraUpdate);

naverMap.addOnCameraChangeListener { reason, animated ->
    Log.i("NaverMap", "Camera change - reson: $reason, animated: $animated")
}

val cameraUpdate = CameraUpdate.scrollTo(LatLng(37.5666102, 126.9783881))
        .animate(CameraAnimation.Easing, 2000)
        .reason(1000)

naverMap.moveCamera(cameraUpdate)

Pivot

The CameraUpdate.pivot() method specifies a pivot point. A pivot point is a proportion value where the top left of the screen is (0, 0), and the bottom right is (1, 1). It is the point on the screen, based on which the camera moves. When a pivot point is set, the movement, zoom level change and rotation of the camera are performed based on the point, rather than the center of the screen.

For example, if you set the pivot point to (0.5, 0.8) and move the camera, the camera is located at the coordinates of the (0.5, 0.8) point after the camera movement is done. If you zoom in the map with the same pivot point, the map zooms in based on (0.5, 0.8), rather than the center of the map. Therefore, the pivot point can make the camera location after the camera movement different from the specified target location.

Considering that the pivot sets a point where the camera should be located on the screen, it works the same as content padding. However, unlike content padding, the property of NaverMap, the pivot is the property of CameraUpdate and thus only applies to one camera change and does not permanently affect the map object.

The following code example sets the pivot point to (0.5, 0.8) and moves the camera.

CameraUpdate cameraUpdate =
    CameraUpdate.scrollTo(new LatLng(37.5666102, 126.9783881))
        .pivot(new PointF(0.5f, 0.8f));

naverMap.moveCamera(cameraUpdate);

CameraUpdate cameraUpdate =
    CameraUpdate.scrollTo(new LatLng(37.5666102, 126.9783881))
        .pivot(new PointF(0.5f, 0.8f));

naverMap.moveCamera(cameraUpdate);

val cameraUpdate = CameraUpdate.scrollTo(LatLng(37.5666102, 126.9783881))
        .pivot(PointF(0.5f, 0.8f))

naverMap.moveCamera(cameraUpdate)

Limitation of movement

With NaverMap’s properties, you can restrict the camera movement to a specified area and set the maximum and minimum zoom level.

Minimum and maximum zoom level

The minZoom and maxZoom properties specify the minimum and maximum zoom levels of the camera.

The following code example limits the camera’s zoom level to the range, 5-18.

naverMap.setMinZoom(5.0);
naverMap.setMaxZoom(18.0);

naverMap.setMinZoom(5.0);
naverMap.setMaxZoom(18.0);

naverMap.minZoom = 5.0
naverMap.maxZoom = 18.0

Camera area

The extent property restricts the camera’s target position to a specified area. Even if an API call is made to move the camera out of the specified area, the target position is adjusted to be within the area.

The following code example restricts the camera’s target position to areas near Korea.

naverMap.setExtent(
    new LatLngBounds(new LatLng(31.43, 122.37), new LatLng(44.35, 132)));

naverMap.setExtent(
    new LatLngBounds(new LatLng(31.43, 122.37), new LatLng(44.35, 132)));

naverMap.extent = LatLngBounds(LatLng(31.43, 122.37), LatLng(44.35, 132.0))

When you restrict the camera area, it is recommended to set the minimum zoom level. Otherwise, the limited areas may be displayed too small when the map zooms out.