Package com.here.sdk.navigation

Class AutomotiveCameraBehavior

java.lang.Object
com.here.NativeBase
com.here.sdk.navigation.AutomotiveCameraBehavior
All Implemented Interfaces:
CameraBehavior
public final class AutomotiveCameraBehavior extends NativeBase implements CameraBehavior

Provides a high-level camera controller for automotive navigation that manages both tracking and area camera behaviors. This class acts as a facade, delegating camera operations to either a TrackingCameraBehavior for following the vehicle during navigation or an AreaCameraBehavior for showing overview areas such as points of interest or route previews.

The controller supports three states: tracking mode (following the vehicle), area mode (showing geographic regions), or inactive (no automatic camera control). The inactive state allows external control of the camera, such as when responding to user touch events or when UI logic temporarily disables automatic camera behavior.

Camera configuration, including animation durations, zoom policies, and maneuver handling settings, can be provided through a JSON configuration string or file. The configuration is validated and parsed during construction.

Note: 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.

  • Constructor Details

    • AutomotiveCameraBehavior

      public AutomotiveCameraBehavior()

      Creates a new instance of this class with default camera behaviors and configuration. This constructor automatically creates and configures the underlying TrackingCameraBehavior and AreaCameraBehavior instances with default settings.

    • AutomotiveCameraBehavior

      public AutomotiveCameraBehavior(@NonNull String configJson) throws InstantiationErrorException

      Creates a new instance of this class configured from a JSON string. The JSON configuration is validated during construction and applied to the underlying TrackingCameraBehavior and AreaCameraBehavior instances.

      Parameters:
      configJson -

      A JSON string containing automotive camera configuration settings.

      Throws:
      InstantiationErrorException -

      InstantiationErrorException when the JSON is malformed or contains invalid values.

  • Method Details

    • setAreaCameraBehaviorVisiblePoints

      public void setAreaCameraBehaviorVisiblePoints(@NonNull List<GeoCoordinates> points, boolean includeCurrentPosition)

      Configures the Area camera to frame the specified points. The camera calculates the optimal zoom level and center position to display all provided coordinates within the viewport. Use this for showing a single point of interest or multiple points such as safety cameras.

      This function does not change getActiveCameraType(). To display the configured area view, set getActiveCameraType() to AutomotiveCameraBehavior.ActiveCameraType.AREA.

      Calling this function overrides any previously set geographic bounding box configured via setAreaCameraBehaviorGeobox(com.here.sdk.core.GeoBox).

      Parameters:
      points -

      The list of geographic coordinates to display.

      includeCurrentPosition -

      When true, the current vehicle position is included in the visible area calculation, ensuring the vehicle remains visible alongside the provided points.

    • setAreaCameraBehaviorGeobox

      public void setAreaCameraBehaviorGeobox(@NonNull GeoBox geobox)

      Configures the Area camera to frame the specified geographic bounding box. The camera automatically calculates the appropriate zoom level and center position to ensure the entire area is visible within the viewport.

      This function does not change getActiveCameraType(). To display the configured area view, set getActiveCameraType() to AutomotiveCameraBehavior.ActiveCameraType.AREA.

      Calling this function overrides any previously set visible points configured via setAreaCameraBehaviorVisiblePoints(java.util.List<com.here.sdk.core.GeoCoordinates>, boolean).

      Parameters:
      geobox -

      The geographic bounding box to display.

    • isManeuverDetectionEnabled

      public boolean isManeuverDetectionEnabled()

      Gets whether maneuver-based camera adjustments are enabled.

      When enabled, the tracking camera automatically adjusts zoom and framing to provide better visibility of upcoming turns and maneuvers during navigation. The specific adjustments and their timing are defined in the camera configuration.

      If tracking is currently active when this property is changed, the setting takes effect immediately. Otherwise, it will apply the next time tracking is activated. The initial state is determined by the camera configuration provided during construction.

      Returns:

      Enables or disables automatic camera adjustments during upcoming maneuvers.

    • setManeuverDetectionEnabled

      public void setManeuverDetectionEnabled(boolean value)

      Sets whether maneuver-based camera adjustments are enabled.

      When enabled, the tracking camera automatically adjusts zoom and framing to provide better visibility of upcoming turns and maneuvers during navigation. The specific adjustments and their timing are defined in the camera configuration.

      If tracking is currently active when this property is changed, the setting takes effect immediately. Otherwise, it will apply the next time tracking is activated. The initial state is determined by the camera configuration provided during construction.

      Parameters:
      value -

      Enables or disables automatic camera adjustments during upcoming maneuvers.

    • getViewRectangle

      @Nullable public Rectangle2D getViewRectangle()

      Gets the current view rectangle, if it's set.

      Defines a sub-space of the screen that the behavior should consider for camera updates. This property is forwarded to both the tracking and area cameras, ensuring consistent viewport constraints across all camera modes. If not set, it uses the viewport bounds of the underlying map view.

      Returns:

      The view rectangle for camera updates.

    • setViewRectangle

      public void setViewRectangle(@Nullable Rectangle2D value)

      Sets a view rectangle for both child cameras.

      Defines a sub-space of the screen that the behavior should consider for camera updates. This property is forwarded to both the tracking and area cameras, ensuring consistent viewport constraints across all camera modes. If not set, it uses the viewport bounds of the underlying map view.

      Parameters:
      value -

      The view rectangle for camera updates.

    • getActiveCameraType

      @NonNull public AutomotiveCameraBehavior.ActiveCameraType getActiveCameraType()

      Gets the type of camera currently handling camera updates.

      Defines which camera behavior is currently active: AutomotiveCameraBehavior.ActiveCameraType.NONE (free navigation), AutomotiveCameraBehavior.ActiveCameraType.TRACKING, or AutomotiveCameraBehavior.ActiveCameraType.AREA.

      Returns:

      The active camera type.

    • setActiveCameraType

      public void setActiveCameraType(@NonNull AutomotiveCameraBehavior.ActiveCameraType value)

      Sets the type of camera currently handling camera updates. If AutomotiveCameraBehavior.ActiveCameraType.AREA is selected, the most recently configured area framing is used. If AutomotiveCameraBehavior.ActiveCameraType.TRACKING is selected, the tracking camera behavior is used. To deactivate set to AutomotiveCameraBehavior.ActiveCameraType.NONE.

      Defines which camera behavior is currently active: AutomotiveCameraBehavior.ActiveCameraType.NONE (free navigation), AutomotiveCameraBehavior.ActiveCameraType.TRACKING, or AutomotiveCameraBehavior.ActiveCameraType.AREA.

      Parameters:
      value -

      The active camera type.

    • getOrientationMode

      @NonNull public AutomotiveCameraBehavior.OrientationMode getOrientationMode()

      Gets the current orientation mode.

      Defines the camera's viewing angle and orientation for tracking mode. In AutomotiveCameraBehavior.OrientationMode.MODE_2D, the camera looks straight down and rotates with the vehicle heading. In AutomotiveCameraBehavior.OrientationMode.MODE_3D, the camera is tilted for a perspective view. In AutomotiveCameraBehavior.OrientationMode.MODE_NORTH_UP, the camera maintains north-up orientation regardless of vehicle heading.

      Changes to this property take effect immediately on the tracking camera and are preserved when switching between tracking and area modes.

      Returns:

      The current orientation mode of the camera.

    • setOrientationMode

      public void setOrientationMode(@NonNull AutomotiveCameraBehavior.OrientationMode value)

      Sets the orientation mode for the tracking camera.

      Defines the camera's viewing angle and orientation for tracking mode. In AutomotiveCameraBehavior.OrientationMode.MODE_2D, the camera looks straight down and rotates with the vehicle heading. In AutomotiveCameraBehavior.OrientationMode.MODE_3D, the camera is tilted for a perspective view. In AutomotiveCameraBehavior.OrientationMode.MODE_NORTH_UP, the camera maintains north-up orientation regardless of vehicle heading.

      Changes to this property take effect immediately on the tracking camera and are preserved when switching between tracking and area modes.

      Parameters:
      value -

      The current orientation mode of the camera.

    • getNormalizedPrincipalPoint

      @NonNull public Anchor2D getNormalizedPrincipalPoint()

      Gets the currently set normalized principal point to be used during navigation.

      Normalized principal point to be used during navigation. Defaults to (0.5, 0.775), which means the camera will use the position slightly at the bottom of the mapview.

      Specified by:
      getNormalizedPrincipalPoint in interface CameraBehavior
      Returns:

      The normalized principal point.

    • setNormalizedPrincipalPoint

      public void setNormalizedPrincipalPoint(@NonNull Anchor2D value)

      Sets a normalized principal point to be used during navigation.

      Normalized principal point to be used during navigation. Defaults to (0.5, 0.775), which means the camera will use the position slightly at the bottom of the mapview.

      Specified by:
      setNormalizedPrincipalPoint in interface CameraBehavior
      Parameters:
      value -

      The normalized principal point.