TransitionCameraBehavior
public class TransitionCameraBehavior : CameraBehavior, CameraHdTransition
extension TransitionCameraBehavior: NativeBase
extension TransitionCameraBehavior: Hashable
Provides a generic dynamic camera behavior that transitions between two pre-configured camera behaviors based on lane detection and data consistency. This allows for optimized camera positioning depending on whether high-definition lane data is available or not.
The camera will automatically switch between two pre-configured camera behaviors
(HD and SD) based on the current navigation context and data consistency.
This is a generic base class that works with any CameraBehavior types,
allowing transitions between different camera behavior implementations.
Transition criteria:
- SD -> HD: switches to HD when at least
minimumHdLengthInMetersof consecutive HD lane data is available ahead AND the route carpet is currently being rendered. - HD -> SD: switches back to SD when HD lane data runs low AND a real non-HD boundary exists ahead AND the minimum HD duration has been traveled.
- HD is forced off when the route carpet data is not shown (e.g. carpet generation failure or missing layers) to avoid presenting an HD camera without HD visuals.
- HD stays on when approaching the end of the route with only HD data remaining (no non-HD boundary), regardless of remaining distance.
Construction-zone awareness:
Traffic incidents of type CONSTRUCTION are taken into account at span level.
When the algorithm looks ahead for the next minimumHdLengthInMeters of
HD data, any route span tagged with a CONSTRUCTION incident is treated as a
non-HD boundary, because lane data is typically unreliable across construction
zones. The effective HD coverage ahead is capped at the start of the nearest
construction span, so the same minimumHdLengthInMeters threshold drives
the resulting SD<->HD transition. HD mode therefore always guarantees at least
minimumHdLengthInMeters of dependable HD data ahead: when a construction
zone falls within that window, the camera switches back to SD immediately,
bypassing the usual minimum HD travel distance even if HD was just entered.
The lookahead is intentionally span-scoped (not section-scoped), so a single
distant incident does not block HD over long stretches of the route.
Note: TransitionCameraBehavior cannot be nested - the hd_camera_behavior and sd_camera_behavior parameters must not be instances of TransitionCameraBehavior.
Note: This is a beta release of this feature and may contain bugs or exhibit unexpected behaviour. Related APIs are subject to change without a deprecation process.
-
Creates a new instance of this class.
Throws
InstantiationErrorInstantiationErrorwhenTransitionCameraBehavior.init(CameraBehavior, CameraBehavior, Int32).hdCameraBehaviororTransitionCameraBehavior.init(CameraBehavior, CameraBehavior, Int32).sdCameraBehavioris aTransitionCameraBehavior.Declaration
Swift
public init(hdCameraBehavior: CameraBehavior, sdCameraBehavior: CameraBehavior, minimumHdLengthInMeters: Int32) throwsParameters
hdCameraBehaviorConfiguration for high-definition lane camera behavior. Used when HD lane data is available and provides detailed lane-level positioning. Must not be a TransitionCameraBehavior.
sdCameraBehaviorConfiguration for standard-definition lane camera behavior. Used as fallback when HD lane data is not available or during transitions. Must not be a TransitionCameraBehavior.
minimumHdLengthInMetersMinimum length of HD lane data required ahead to maintain HD camera mode. The camera transitions to SD mode when HD data availability falls below this distance.
-
Creates a new instance of this class following the recommended configuration. The default configuration sets
FixedCameraBehaviorfor both HD and SD view. HD camera behavior uses 21 asFixedCameraBehavior.zoomand 75 asFixedCameraBehavior.cameraTiltInDegrees. SD camera behavior uses 17 asFixedCameraBehavior.zoomand 45 asFixedCameraBehavior.cameraTiltInDegrees.minimumHdLengthInMetersis set to 500.Declaration
Swift
public init() -
The normalized principal point. 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.
Declaration
Swift
public var normalizedPrincipalPoint: Anchor2D { get set } -
The view rectangle for camera updates. Defines a sub-space of the screen that the behavior should consider for camera updates. Using a view rectangle keeps the camera positioning consistent across different screen types and orientations without per-screen principal point adjustments. Defaults to
nil. If not set, it uses the viewport bounds of the underlying map view.Declaration
Swift
public var viewRectangle: Rectangle2D? { get set } -
Defines how the camera starts following the current position when this camera behavior becomes active. Use
CameraTransitionMode.instantto skip the camera animation, for example when returning from a route overview to guidance. The default value isCameraTransitionMode.animated.Declaration
Swift
public var cameraTransitionMode: CameraTransitionMode { get set } -
Minimum HD lane data length threshold in meters. The camera transitions from HD to SD mode when HD lane data availability falls below this distance ahead, or transitions to HD mode when sufficient HD data is detected.
Declaration
Swift
public var minimumHdLengthInMeters: Int32 { get set } -
Gets the HD camera behavior configuration.
Declaration
Swift
public func getHdCameraBehavior() -> CameraBehaviorReturn Value
Configuration for high-definition lane camera behavior.
-
Sets the HD camera behavior configuration. This defines camera positioning optimized for HD lane visualization. Must not be a TransitionCameraBehavior.
Throws
InstantiationErrorInstantiationErrorwhenTransitionCameraBehavior.setHdCameraBehavior(...).hdCameraBehavioris aTransitionCameraBehavior.Declaration
Swift
public func setHdCameraBehavior(hdCameraBehavior: CameraBehavior) throwsParameters
hdCameraBehaviorThe HD camera behavior to set. Must not be a TransitionCameraBehavior.
-
Gets the SD camera behavior configuration.
Declaration
Swift
public func getSdCameraBehavior() -> CameraBehaviorReturn Value
Configuration for standard-definition lane camera behavior.
-
Sets the SD camera behavior configuration. This defines camera positioning for standard lane visualization. Must not be a TransitionCameraBehavior.
Throws
InstantiationErrorInstantiationErrorwhenTransitionCameraBehavior.setSdCameraBehavior(...).sdCameraBehavioris aTransitionCameraBehavior.Declaration
Swift
public func setSdCameraBehavior(sdCameraBehavior: CameraBehavior) throwsParameters
sdCameraBehaviorThe SD camera behavior to set. Must not be a TransitionCameraBehavior.