Package com.here.sdk.mapview

Class MapCameraUpdateFactory

java.lang.Object
com.here.NativeBase
com.here.sdk.mapview.MapCameraUpdateFactory
public final class MapCameraUpdateFactory extends NativeBase

Factory for creating MapCameraUpdate to change map's camera.

For some factory methods you can apply an additional padding in pixels by setting a viewRectangle parameter based on the current size of the map view: 

int leftPaddingInPixels = 5;
 int rightPaddingInPixels = 5;
 int topPaddingInPixels = 5;
 int bottomPaddingInPixels = 5;
 int horizontalPaddingInPixels = leftPaddingInPixels + rightPaddingInPixels;
 int verticalPaddingInPixels = topPaddingInPixels + bottomPaddingInPixels;

 Point2D origin = new Point2D(leftPaddingInPixels, topPaddingInPixels);
 Size2D sizeInPixels = new Size2D(mapView.getWidth() - horizontalPaddingInPixels, mapView.getHeight() - verticalPaddingInPixels);
 Rectangle2D paddedViewRectangle = new Rectangle2D(origin, sizeInPixels);

The origin indicates the top-left corner of the rectangle. An origin of (0, 0) indicates also the top-left corner of the map's viewport.

  • Method Details

    • lookAt

      @NonNull public static MapCameraUpdate lookAt(@NonNull GeoCoordinatesUpdate target)

      Creates an update to position the map camera to look at the given target, preserving the current orientation at look-at target and map measure.

      Any target sub-element value that is not finite will be excluded from the update.

      The altitude of the target point is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

      Parameters:
      target -

      The look-at target position in geodetic coordinates, altitude is ignored, the target is considered to be located on the ground.

      Returns:

      MapCameraUpdate instance.

    • lookAt

      @NonNull public static MapCameraUpdate lookAt(@NonNull GeoCoordinatesUpdate target, @NonNull GeoOrientationUpdate orientation)

      Creates an update to position the map camera to look at the given target with the given orientation preserving the current map measure (zoom level/distance/scale) Any target or orientation sub-element value that is not finite will be excluded from the update.

      The altitude of the target point is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

      Parameters:
      target -

      The look-at target position in geodetic coordinates.

      orientation -

      Geodetic orientation at look-at target.

      Returns:

      MapCameraUpdate instance.

    • lookAt

      @NonNull public static MapCameraUpdate lookAt(@NonNull GeoCoordinatesUpdate target, @NonNull MapMeasure measure)

      Creates an update to position the map camera to look at the given target with the given map measure preserving the current orientation at look-at target. Any target sub-element value that is not finite will be excluded from the update. If the map measure is not valid, the current map camera distance to the target point is preserved.

      The altitude of the target point is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

      Parameters:
      target -

      The look-at target position in geodetic coordinates.

      measure -

      The desired map measure.

      Returns:

      MapCameraUpdate instance.

    • lookAt

      @NonNull public static MapCameraUpdate lookAt(@NonNull GeoCoordinatesUpdate target, @NonNull GeoOrientationUpdate orientation, @NonNull MapMeasure measure)

      Creates an update to position the map camera to look at the given target with the given orientation and map measure. Any target or orientation sub-element value that is not finite will be excluded from the update. If the map measure is not valid, the current map camera distance to the target point is preserved.

      The altitude of the target point is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

      Parameters:
      target -

      The look-at target position in geodetic coordinates.

      orientation -

      Geodetic orientation at look-at target.

      measure -

      The desired map measure.

      Returns:

      MapCameraUpdate instance.

    • lookToMatch

      @NonNull public static MapCameraUpdate lookToMatch(@NonNull GeoCoordinates geoPoint, @NonNull Point2D viewPoint, @NonNull GeoOrientationUpdate orientation, @NonNull MapMeasure measure)

      Creates an update to position the map camera to look at the map with the given orientation and map measure and with the given geo point located at the given view point.

      The altitude of the target point is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

      Note that this is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

      Parameters:
      geoPoint -

      The geo point that will be matched to the given view point. Note: the geo point will differ from the look at target of the camera. After this update the camera will still look at the principal point and therefore the look at target will be different from the geo point, since the geo point will correspond to the given view point and the look at target will correspond to the principal point. Look at target and the geo point will be identical only if the given view point is identical to the principal point.

      viewPoint -

      View point coordinates in pixels.

      orientation -

      Geodetic orientation at look-at target.

      measure -

      The desired map measure.

      Returns:

      MapCameraUpdate instance.

    • lookToMatch

      @NonNull public static MapCameraUpdate lookToMatch(@NonNull GeoCoordinates geoPoint, @NonNull Point2D viewPoint)

      Creates an update to position the map camera to look at the map with the given geo point located at the given view point. Note that this is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

      The altitude of the target point is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

      Parameters:
      geoPoint -

      The geo point that will be matched to the given view point. Note: the geo point will differ from the look at target of the camera. After this update the camera will still look at the principal point and therefore the look at target will be different from the geo point, since the geo point will correspond to the given view point and the look at target will correspond to the principal point. Look at target and the geo point will be identical only if the given view point is identical to the principal point.

      viewPoint -

      View point coordinates in pixels.

      Returns:

      MapCameraUpdate instance.

    • lookAt

      @NonNull public static MapCameraUpdate lookAt(@NonNull List<GeoCoordinates> points, @NonNull Rectangle2D viewRectangle, @NonNull GeoOrientationUpdate orientation, @NonNull MapMeasure measureLimit)

      Create an update to look at the given geo locations and fit them inside the given rectangle, in accordance with a map measure limit.

      If the provided points list is empty, no update will be applied to the camera.

      If the viewRectangle parameter is invalid, fully or partially outside the map view, then the entire map viewport will be used as viewRectangle. Thus, no padding will be applied. A viewRectangle is considered invalid, when its width or height are negative or zero, its origin coordinates (x, y) are invalid, when they are negative.

      All viewRectangle values need to be finite to be considered as valid. If measure limit is not valid, no update will be applied to the map camera.

      The altitude of the target points is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

      Parameters:
      points -

      Array of points in geodetic space that should be visible inside the given view rectangle.

      viewRectangle -

      View rectangle in viewport pixel coordinates inside which the geographical target area is displayed.

      orientation -

      Geodetic orientation at the new calculated target point.

      measureLimit -

      Map measure limit:

      • as distance: the minimum distance from map camera to earth surface at the center of the view rectangle in meters. The map camera should not be positioned closer to the center of view rectangle than this.
      • as zoom level: the maximum zoom level for the new map camera state. Internally converted to minimum distance from map camera to earth surface at the center of view rectangle in meters. This is not the zoom level for the calculated lookAt target point. Can be used to not zoom closer than a given level.
      • as scale: the minimum scale for the new map camera state. Internally converted to minimum distance from map camera to earth surface at the center of view rectangle in meters. This is not the scale for the calculated lookAt target point.
      Returns:

      MapCameraUpdate instance.

    • lookAt

      @NonNull public static MapCameraUpdate lookAt(@NonNull GeoCoordinatesUpdate target, @NonNull GeoOrientationUpdate orientation, @NonNull List<GeoCoordinates> points, @NonNull Rectangle2D viewRectangle, @NonNull MapMeasure minMeasure, @NonNull MapMeasure maxMeasure)

      Creates an update to position the camera to look at the given target with the given orientation and obeying map measure limits, so that the given geo locations are inside the given rectangle. Such position update can possibly not be found.

      Any target or orientation sub-element value that is not finite will be excluded from the update.

      If the provided points list is empty, no update will be applied to the map camera.

      If the viewRectangle parameter is invalid, fully or partially outside the map view, then the entire map viewport will be used as viewRectangle. Thus, no padding will be applied. A viewRectangle is considered invalid, when its width or height are negative or zero, its origin coordinates (x, y) are invalid, when they are negative.

      If map measures are not valid, no update will be applied to the map camera.

      The altitude of the target points is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

      Parameters:
      target -

      The look-at target position in geodetic coordinates.

      orientation -

      Geodetic orientation at look-at target.

      points -

      Array of points in geodetic space that should be visible inside the given view rectangle.

      viewRectangle -

      View rectangle in viewport pixel coordinates inside which the geographical points are displayed.

      minMeasure -

      Minimum map measure:

      • as distance: the minimum distance from map camera to earth surface at the look-at target in meters. The map camera should not be positioned closer to target than this.
      • as zoom level: the maximum zoom level for the new map camera state. Internally converted to minimum distance from map camera to earth surface at the look-at target in meters. Can be used to not zoom closer than a given level.
      • as scale: the minimum scale for the new map camera state. Internally converted to minimum distance from map camera to earth surface at the look-at target in meters.
      maxMeasure -

      Maximum map measure:

      • as distance: the maximum distance from map camera to earth surface at the look-at target in meters. The map camera should not be positioned further from target than this.
      • as zoom level: the minimum zoom level for the new map camera state. Internally converted to minimum distance from map camera to earth surface at the look-at target in meters. Can be used to not zoom further than a given level.
      • as scale: the maximum scale for the new map camera state. Internally converted to minimum distance from map camera to earth surface at the look-at target in meters.
      Returns:

      MapCameraUpdate instance.

    • lookAt

      @NonNull public static MapCameraUpdate lookAt(@NonNull GeoBox target, @NonNull GeoOrientationUpdate orientation, @NonNull Rectangle2D viewRectangle)

      Create an update to look at the given geo-box and fit it inside the given rectangle.

      If geoBox is not valid, no update will be applied to the map camera.

      If the viewRectangle parameter is invalid, fully or partially outside the map view, then the entire map viewport will be used as viewRectangle. Thus, no padding will be applied. A viewRectangle is considered invalid, when its width or height are negative or zero, its origin coordinates (x, y) are invalid, when they are negative.

      All viewRectangle values need to be finite to be considered as valid.

      In cases where it is not possible to find a solution for the given parameters, the resulting MapCameraUpdate will not change the map camera.

      The altitude of the target points is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

      Parameters:
      target -

      Geodetic box that should be visible inside the given view rectangle.

      orientation -

      Geodetic orientation at the target point.

      viewRectangle -

      View rectangle in viewport pixel coordinates inside which the geographical target area is displayed.

      Returns:

      MapCameraUpdate instance.

    • lookAt

      @NonNull public static MapCameraUpdate lookAt(@NonNull GeoBox target, @NonNull Rectangle2D viewRectangle)

      Creates an update to look at the given geo-box and fit it inside the given rectangle, preserving current orientation and zooming at the center of view rectangle.

      If geoBox is not valid, no update will be applied to the map camera.

      If the viewRectangle parameter is invalid, fully or partially outside the map view, then the entire map viewport will be used as viewRectangle. Thus, no padding will be applied. A viewRectangle is considered invalid, when its width or height are negative or zero, its origin coordinates (x, y) are invalid, when they are negative.

      In cases where it is not possible to find a solution for the given parameters, the resulting MapCameraUpdate will not change the map camera.

      The altitude of the target points is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

      Parameters:
      target -

      Geodetic box that should be visible inside the given view rectangle.

      viewRectangle -

      View rectangle in viewport pixel coordinates.

      Returns:

      MapCameraUpdate instance.

    • lookAt

      @NonNull public static MapCameraUpdate lookAt(@NonNull GeoBox target)

      Creates an update to look at the given geo-box, preserving current orientation and zooming at the center of viewport.

      If geoBox is not valid, no update will be applied to the map camera.

      The altitude of the target points is ignored. Any subsequent camera updates and animations will consider the target point as being located on the ground.

      Parameters:
      target -

      Geodetic box that should be visible inside the viewport rectangle.

      Returns:

      MapCameraUpdate instance.

    • panBy

      @NonNull public static MapCameraUpdate panBy(double xOffset, double yOffset)

      Creates an update to pan map camera over the map by the specified number of pixels in the x and y direction starting from current principal point position.

      Parameters:
      xOffset -

      X offset in pixels

      yOffset -

      Y offset in pixels

      Returns:

      MapCameraUpdate instance.

    • orbitBy

      @NonNull public static MapCameraUpdate orbitBy(@NonNull GeoOrientationUpdate delta, @NonNull Point2D origin)

      Creates an update to orbit map camera around a pixel origin by specified geodetic orientation delta. If the origin cannot be converted to geo coordinates, no update will be applied to the map camera.

      Orientation elements that are not valid will be excluded from the update. Resulting bearing values are wrapped around degrees range [0, 360]. Resulting tilt values are clamped inside degrees range [0, 180]. Resulting roll values are wrapped around degrees range [-180, 180].

      Parameters:
      delta -

      Geodetic orientation delta update.

      origin -

      Screen pixel origin of rotation.

      Returns:

      MapCameraUpdate instance.

    • rotateBy

      @NonNull public static MapCameraUpdate rotateBy(@NonNull GeoOrientationUpdate delta)

      Creates an update to change map camera orientation by specified geodetic orientation delta. Orientation elements that are not valid will be excluded from the update. Resulting bearing values are wrapped around degrees range [0, 360]. Resulting tilt values are clamped inside degrees range [0, 180]. Resulting roll values are wrapped around degrees range [-180, 180].

      Parameters:
      delta -

      Geodetic orientation delta update.

      Returns:

      MapCameraUpdate instance.

    • zoomBy

      @NonNull public static MapCameraUpdate zoomBy(double factor, @NonNull Point2D origin)

      Creates an update to zoom map camera by a given factor preserving a given focus point.

      Values greater than 1 zoom in map camera, by moving it closer to the ground; less than 1 - zoom out, which moves map camera further.

      If factor is zero, negative or not finite, no update will be applied to the map camera.

      If the focusPoint is not inside the viewport bounds, then the current principal point will be used.

      Parameters:
      factor -

      Zooming factor.

      origin -

      Pixel location on the screen to use as zoom origin.

      Returns:

      MapCameraUpdate instance.

    • zoomTo

      @NonNull public static MapCameraUpdate zoomTo(double zoomLevel)

      Creates an update to move map camera's viewpoint to a particular zoom level by adjusting its position.

      If zoomLevel is not finite, no update will be applied to the map camera.

      Parameters:
      zoomLevel -

      The desired zoom level.

      Returns:

      MapCameraUpdate instance.

    • setPrincipalPoint

      @NonNull public static MapCameraUpdate setPrincipalPoint(@NonNull Point2D principalPoint)

      Creates an update to change the map camera's principal point (where the view vector intersects the image plane - default is the center of the view). Point values are in screen coordinates and values that fall outside of the viewport, are clamped. (0,0) is top left of the viewport.

      Parameters:
      principalPoint -

      Principal point in absolute viewport pixel coordinates.

      Returns:

      MapCameraUpdate instance.

    • setNormalizedPrincipalPoint

      @NonNull public static MapCameraUpdate setNormalizedPrincipalPoint(@NonNull Anchor2D principalPoint)

      Creates an update to change the map camera's principal point (where the view vector intersects the image plane - default is (0.5, 0.5)). Point values are in normalized screen coordinates.

      If the principalPoint is outside [0,1] interval, it is clamped. (0,0) is top left of the viewport, (1,1) is bottom right.

      Parameters:
      principalPoint -

      Principal point in normalized screen coordinates.

      Returns:

      MapCameraUpdate instance.

    • setVerticalFieldOfView

      @NonNull public static MapCameraUpdate setVerticalFieldOfView(double verticalFieldOfView)

      Creates an update to change the vertical field of view of the map camera.

      If verticalFieldOfView is not finite, no update will be applied to the map camera.

      If the verticalFieldOfView is outside [1, 150] interval, it is clamped.

      Parameters:
      verticalFieldOfView -

      Vertical field of view in degrees.

      Returns:

      MapCameraUpdate instance.

    • compositeUpdate

      @NonNull public static MapCameraUpdate compositeUpdate(@NonNull List<MapCameraUpdate> mapCameraUpdates) throws MapCameraUpdate.InstantiationException

      Creates a composite camera update from a list of camera updates. The result update will be equivalent to executing all given updates sequentially in the order they were provided.

      MapCameraAnimation instances derived from the MapCameraAnimationFactory and a composite camera update are not supported. An AnimationListener will receive an AnimationState.Cancelled signal when trying to apply such animations.

      Parameters:
      mapCameraUpdates -

      List of MapCamera updates.

      Returns:

      MapCameraUpdate instance.

      Throws:
      MapCameraUpdate.InstantiationException -

      Indicates an instantiation issue.