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 NMFCameraUpdate object and the -moveCamera: method. With various properties of the NMFCameraUpdate, 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 an NMFCameraUpdate object which determines how a camera moves. NMFCameraUpdate is a class that defines where and how a camera moves. You can create an NMFCameraUpdate object only by using factory methods, which are defined in the NMFCameraUpdate. The list below describes some factory methods.

• +cameraUpdateWithPosition:cameraUpdateWithPosition:): Moves the position of the camera to the specified CameraPosition.
• +cameraUpdateWithScrollTo:cameraUpdateWithScrollTo:): Sets the target point of the camera to the specified coordinates.
• +cameraUpdateWithScrollBy:cameraUpdateWithScrollBy:): Moves the target point of the camera up, down, left or right by the specified points.
• +cameraUpdateWithZoomTo:cameraUpdateWithZoomTo:): Sets the zoom level of the camera to the specified value.
• +cameraUpdateWithFitBounds:cameraUpdateWithFitBounds:): Changes the camera position to the coordinates where the whole area is shown, with the maximum zoom level.

Make a call to -moveCamera: of the NMFMapView with the created object as a parameter, and the camera moves.

The following code example creates an NMFCameraUpdate object that changes the target point to (37.5666102, 126.9783881), and calls the -moveCamera: method to move the camera.

let cameraUpdate = NMFCameraUpdate(scrollTo: NMGLatLng(lat: 37.5666102, lng: 126.9783881))
mapView.moveCamera(cameraUpdate)

let cameraUpdate = NMFCameraUpdate(scrollTo: NMGLatLng(lat: 37.5666102, lng: 126.9783881))
mapView.moveCamera(cameraUpdate)

NMFCameraUpdate *cameraUpdate = [NMFCameraUpdate cameraUpdateWithScrollTo:NMGLatLngMake(37.5666102, 126.9783881)];
[self.mapView moveCamera:cameraUpdate];

Animation

Before calling the -moveCamera: by using the NMFCameraUpdate object, you can specify NMFCameraUpdate.animation 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 NMFCameraUpdate.animate, you can animate the camera movement. The animation receives the NMFCameraUpdateAnimation object, which represents animation types, as a parameter. Animation types defined in the NMFCameraUpdateAnimation enum are listed below.

• None: Moves without animation. It is the default value.
• Linear: Moves at a regular speed.
• EaseIn: Naturally accelerates. It is appropriate for moving a short distance.
• EaseOut: Naturally 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 EaseIn animation to the camera movement.

let cameraUpdate = NMFCameraUpdate(scrollTo: NMGLatLng(lat: 37.5666102, lng: 126.9783881))
cameraUpdate.animation = .easeIn
mapView.moveCamera(cameraUpdate)

let cameraUpdate = NMFCameraUpdate(scrollTo: NMGLatLng(lat: 37.5666102, lng: 126.9783881))
cameraUpdate.animation = .easeIn
mapView.moveCamera(cameraUpdate)

NMFCameraUpdate *cameraUpdate = [NMFCameraUpdate cameraUpdateWithScrollTo:NMGLatLngMake(37.5666102, 126.9783881)];
cameraUpdate.animation = NMFCameraUpdateAnimationEaseIn
[self.mapView moveCamera:cameraUpdate];

Duration

By specifying the animationDuration parameter of the NMFCameraUpdate, you can change the duration of animations. Note that if the animation type is NMFCameraUpdateAnimationNone, the duration is ignored. Also note that if the animationDuration is 0, the camera moves without animation although an animation type is specified.

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

let cameraUpdate = NMFCameraUpdate(scrollTo: NMGLatLng(lat: 37.5666102, lng: 126.9783881))
cameraUpdate.animation = .fly
cameraUpdate.animationDuration = 1
mapView.moveCamera(cameraUpdate)

let cameraUpdate = NMFCameraUpdate(scrollTo: NMGLatLng(lat: 37.5666102, lng: 126.9783881))
cameraUpdate.animation = .fly
cameraUpdate.animationDuration = 1
mapView.moveCamera(cameraUpdate)

NMFCameraUpdate *cameraUpdate = [NMFCameraUpdate cameraUpdateWithScrollTo:NMGLatLngMake(37.5666102, 126.9783881)];
cameraUpdate.animation = NMFCameraUpdateAnimationFly;
cameraUpdate.animationDuration = 1;
[self.mapView 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 animationDuration property of the NMFMapView.

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

mapView.animationDuration = 0.5

mapView.animationDuration = 0.5

mapView.animationDuration = 0.5f;

Cancel animations

The camera movement animation can be cancelled for a variety of reasons. When you call the -moveCamera: of NMFMapView 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.

let coord1 = NMGLatLng(lat: 37.5666102, lng: 126.9783881);
let coord2 = NMGLatLng(lat: 37.57000, lng: 126.97618);

// Camera animation for 2 sec.
let cameraUpdate = NMFCameraUpdate(scrollTo: coord1)
cameraUpdate.animation = .easeIn
cameraUpdate.animationDuration = 2
mapView.moveCamera(cameraUpdate)

// 1 sec later, a new camera movement starts and the previous camera animation is cancelled.
DispatchQueue.main.asyncAfter(deadline: .now() + 1) {
    let cameraUpdate = NMFCameraUpdate(scrollTo: coord2)
    cameraUpdate.animation = .easeIn
    mapView.moveCamera(cameraUpdate)
}

let coord1 = NMGLatLng(lat: 37.5666102, lng: 126.9783881);
let coord2 = NMGLatLng(lat: 37.57000, lng: 126.97618);

// Camera animation for 2 sec.
let cameraUpdate = NMFCameraUpdate(scrollTo: coord1)
cameraUpdate.animation = .easeIn
cameraUpdate.animationDuration = 2
mapView.moveCamera(cameraUpdate)

// 1 sec later, a new camera movement starts and the previous camera animation is cancelled.
DispatchQueue.main.asyncAfter(deadline: .now() + 1) {
    let cameraUpdate = NMFCameraUpdate(scrollTo: coord2)
    cameraUpdate.animation = .easeIn
    mapView.moveCamera(cameraUpdate)
}

NMGLatLng *coord1 = NMGLatLngMake(37.5666102, 126.9783881);
NMGLatLng *coord2 = NMGLatLngMake(37.57000, 126.97618);

// Camera animation for 2 sec.
NMFCameraUpdate *cameraUpdate = [NMFCameraUpdate cameraUpdateWithScrollTo:coord1];
cameraUpdate.animation = NMFCameraUpdateAnimationEaseIn;
cameraUpdate.animationDuration = 2;
[self.mapView moveCamera:cameraUpdate];

// 1 sec later, a new camera movement starts and the previous camera animation is cancelled.
dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(1.0 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
    NMFCameraUpdate *cameraUpdate = [NMFCameraUpdate cameraUpdateWithScrollTo:coord2];
    cameraUpdate.animation = NMFCameraUpdateAnimationEaseIn;
    [self.mapView moveCamera:cameraUpdate];
});

You can also use the -cancelTransitions of NMFMapView 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.
let cameraUpdate = NMFCameraUpdate(scrollTo: coord1)
cameraUpdate.animation = .easeIn
cameraUpdate.animationDuration = 2
mapView.moveCamera(cameraUpdate)

// 1 sec later, cancelTransitions() is called and the previous camera animation is cancelled.
DispatchQueue.main.asyncAfter(deadline: .now() + 1) {
    mapView.cancelTransitions()
}

// Camera animation for 2 sec.
let cameraUpdate = NMFCameraUpdate(scrollTo: coord1)
cameraUpdate.animation = .easeIn
cameraUpdate.animationDuration = 2
mapView.moveCamera(cameraUpdate)

// 1 sec later, cancelTransitions() is called and the previous camera animation is cancelled.
DispatchQueue.main.asyncAfter(deadline: .now() + 1) {
    mapView.cancelTransitions()
}

// Camera animation for 2 sec.
NMFCameraUpdate *cameraUpdate = [NMFCameraUpdate cameraUpdateWithScrollTo:coord1];
cameraUpdate.animation = NMFCameraUpdateAnimationEaseIn;
cameraUpdate.animationDuration = 2;
[self.mapView moveCamera:cameraUpdate];

// 1 sec later, cancelTransitions() is called and the previous camera animation is cancelled.
dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(1.0 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
    [self.mapView cancelTransitions];
});

Callback and event

With the completion block of -moveCamera:completion:, instead of -moveCamera:, you can get a result called back for a camera movement. You can also add a delegate to the NMFMapView to get events for all camera movements in your map.

Camera movement callback

Implement a callback block with -moveCamera:completion:, and you can get a callback when a camera movement for the NMFCameraUpdate is completed or cancelled. If an animation set for camera movements is cancelled, the isCancelled parameter of the completion block is set to YES; otherwise, it is set to NO. 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.

let cameraUpdate = NMFCameraUpdate(scrollTo: NMGLatLng(lat: 37.5666102, lng: 126.9783881))
cameraUpdate.animation = .easeIn
cameraUpdate.animationDuration = 2
mapView.moveCamera(cameraUpdate) { (isCancelled) in
    if isCancelled {
        print("Camera movement cancelled")
    } else {
        print("Camera movement finished")
    }
}

let cameraUpdate = NMFCameraUpdate(scrollTo: NMGLatLng(lat: 37.5666102, lng: 126.9783881))
cameraUpdate.animation = .easeIn
cameraUpdate.animationDuration = 2
mapView.moveCamera(cameraUpdate) { (isCancelled) in
    if isCancelled {
        print("Camera movement cancelled")
    } else {
        print("Camera movement finished")
    }
}

NMFCameraUpdate *cameraUpdate = [NMFCameraUpdate cameraUpdateWithScrollTo:NMGLatLngMake(37.5666102, 126.9783881)];
cameraUpdate.animation = NMFCameraUpdateAnimationEaseIn;
cameraUpdate.animationDuration = 2;
[self.mapView moveCamera:cameraUpdate completion:^(bool isCancelled) {
    if (isCancelled) {
        NSLog(@"Camera movement cancelled");
    } else {
        NSLog(@"Camera movement finished");
    }
}];

Camera change event

For whatever reason, if a camera moves, an event occurs. Declare an NMFMapViewDelegate protocol in the view controller that is using the NMFMapView and add it with the NMFMapView.delegate method, and you can receive a camera change event. When the camera’s position is changed, the -mapViewRegionIsChanging:byReason:NMFMapViewDelegate%28im%29mapViewRegionIsChanging:byReason:) callback method is called.

The reason and animated parameters are passed to the -mapView:regionWillChangeAnimated:byReason: method that is called before the camera movement begins, and the -mapView:regionDidChangeAnimated:byReason: method that is called after the camera movement is completed. The reason parameter is a reason for the camera movement that triggers an event. You can call NMFCameraUpdate.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:

• NMFMapChangedByDeveloper: Indicates that the camera moved by the developer’s API call. It is the default value.
• NMFMapChangedByGesture: Indicates that the camera moved in response to a user’s gesture.
• NMFMapChangedByControl: Indicates that the camera moved in response to a user’s button tapping.
• NMFMapChangedByLocation: Indicates that the camera moved by the location tracking feature.

The following code example adds a delegate method that logs reasons for camera changes and sets a reason to move the camera.

func mapViewRegionIsChanging(_ mapView: NMFMapView, byReason reason: Int) {
    print("Camera change - reason: \(reason)")
}

let cameraUpdate = NMFCameraUpdate(scrollTo: NMGLatLng(lat: 37.5666102, lng: 126.9783881))
cameraUpdate.animation = .easeIn
cameraUpdate.animationDuration = 2
cameraUpdate.reason = 1000

mapView.moveCamera(cameraUpdate)

func mapViewRegionIsChanging(_ mapView: NMFMapView, byReason reason: Int) {
    print("Camera change - reason: \(reason)")
}

let cameraUpdate = NMFCameraUpdate(scrollTo: NMGLatLng(lat: 37.5666102, lng: 126.9783881))
cameraUpdate.animation = .easeIn
cameraUpdate.animationDuration = 2
cameraUpdate.reason = 1000

mapView.moveCamera(cameraUpdate)

- (void)mapViewRegionIsChanging:(NMFMapView *)mapView byReason:(NSInteger)reason {
    NSLog(@"Camera change - reason : %ld", (long)reason);
}

NMFCameraUpdate *cameraUpdate = [NMFCameraUpdate cameraUpdateWithScrollTo:NMGLatLngMake(37.5666102, 126.9783881)];
cameraUpdate.animation = NMFCameraUpdateAnimationEaseIn;
cameraUpdate.animationDuration = 2;
cameraUpdate.reason = 1000;

[self.mapView moveCamera:cameraUpdate];

Pivot

The NMFCameraUpdate.pivot property 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 NMFMapView, the pivot is the property of NMFCameraUpdate 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.

let cameraUpdate = NMFCameraUpdate(scrollTo: NMGLatLng(lat: 37.5666102, lng: 126.9783881))
cameraUpdate.pivot = CGPoint(x: 0.5, y: 0.8)

mapView.moveCamera(cameraUpdate)

let cameraUpdate = NMFCameraUpdate(scrollTo: NMGLatLng(lat: 37.5666102, lng: 126.9783881))
cameraUpdate.pivot = CGPoint(x: 0.5, y: 0.8)

mapView.moveCamera(cameraUpdate)

NMFCameraUpdate *cameraUpdate = [NMFCameraUpdate cameraUpdateWithScrollTo:NMGLatLngMake(37.5666102, 126.9783881)];
cameraUpdate.pivot = CGPointMake(0.5, 0.8);

[self.mapView moveCamera:cameraUpdate];

Limitation of movement

With NMFMapView’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 minZoomLevel and maxZoomLevel 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.

mapView.minZoomLevel = 5.0
mapView.maxZoomLevel = 18.0

mapView.minZoomLevel = 5.0
mapView.maxZoomLevel = 18.0

self.mapView.minZoomLevel = 5.0;
self.mapView.maxZoomLevel = 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.

mapView.extent = NMGLatLngBounds(southWestLat: 31.43, southWestLng: 122.37, northEastLat: 44.35, northEastLng: 132)

mapView.extent = NMGLatLngBounds(southWestLat: 31.43, southWestLng: 122.37, northEastLat: 44.35, northEastLng: 132)

self.mapView.extent = NMGLatLngBoundsMake(31.43, 122.37, 44.35, 132);

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.