HERE Android SDK Developer's Guide

Customizing LiveSight

LiveSight is highly configurable, allowing developers and designers to create many different and immersive experiences. The ARController class serves as a facade for overall LiveSight functionality, containing all of the methods and callbacks available for controlling and customizing LiveSight behavior.

The methods used to customize LiveSight reside in the ARController and also the following inner classes:
  • ARController.UpViewParams
  • ARController.UpViewTransitionParams
  • ARController.DownViewParams
  • ARController.IntroAnimationParams
  • ARController.IconParams
  • ARController.InfoParams
  • ARController.CameraParams
  • ARController.FilterParams
  • ARController.SelectedItemParams

UpViewParams, UpViewTransitionParams, and DownViewParams

UpViewParams and DownViewParams encapsulate the customizable parameters that are applicable for the Up and Down views. UpViewTransitionParams encapsulates customizable parameters that are applicable when you move up from the down view and enter the camera view.

IntroAnimationParams

IntroAnimationParams encapsulates parameters about various intro animations. Intro animation refers to the animation that is used while the app is entering LiveSight. During LiveSight entry, a few transition operations happen simultaneously, and each of these can be assigned a different animation style. These customizable transition operations are: map zoom (the map zooms in towards the ground level), heading change (the current heading changes to the current device heading), position change (the current position changes to the current device position or a LiveSight-specific position), and pitch change (the pitch changes according to the 3D orientation of the device).

IconParams and InfoParams

IconParams encapsulates customizable parameters for the front, back, and down icons. In addition to setting icon sizes, you can also set how icons animate when they first appear ("pop-up"), receive a tap, or appear while transitioning from the Down to Up view ("fly"). For more information on down, front, and back icons, consult the section Adding and Interacting with LiveSight Content.

InfoParams allow you to customize how Info Views animate when they first appear ("pop-up"), receive a tap, or appear while transitioning from the Down to Up view ("fly").

CameraParams

CameraParams encapsulates parameters that are related to the camera-enabled Up view. The CameraParams.setSize(Size) method allows you to set the camera resolution to be used for the LiveSight camera view. Note that using a high camera resolution may cause performance degradation. The default camera resolution is 680x480.

HeadingFilterParams, PitchFilterParams, and ZoomFilterParams

HeadingFilterParams, PitchFilterParams, and ZoomFilterParams are all instances of the ARController.FilterParams class. These objects encapsulate the customizable parameters for the heading, pitch, and zoom data sampling. Methods in Filter allow you to customize how data samples are read from the device sensors.

SelectedItemParams

SelectedItemParams encapsulates parameters that control behavior when an ARObject is in the selected or unselected state. For example, you can increase the size of a selected icon. By default, objects are neither in the selected or unselected state. When an ARObject is selected, all other ARObjects are changed to the unselected state. When selection is canceled, all objects are returned to the neutral state.

Other ARController Settings

In addition to the previous parameter classes, you can use methods in ARController to customize the following areas in LiveSight:
  • Alternative Center Location — LiveSight is not only limited to the current device location. It is possible to use the ARController to set an alternative location ("space shift") for your LiveSight experience.
  • Icon Display Behavior — Adjust settings related to the icon display, such as as only showing Front items, or using Down icons in the map.
  • Device Orientation Behavior — Set whether the Down view is updated with the device sensor's orientation data.
  • Layout Updates — By default, LiveSight icons are set to update dynamically according to the current device position. However, you can set ARController so that the Layout (containing the front and back icons) does not update until the device position has changed significantly past a threshold.

External Sensor Data

LiveSight also provides the ability to switch from using integrated device sensor data to one or more data feeds provided by external sources. You may need to do this when more accuracy is required for object projection results in the Up state, or when you require a distributed LiveSight solution where data from multiple sensors are provided over TCP/IP.

ARController.ExternalSensors is the entry point for using external sensor data. You can enable or disable input from one or more external sensors by using this class with the values defined in the ARController.SensorType enum, with the exception of CAMERA. For example:

arController.ExternalSensors.utilize(SensorType.GPS, true);
Note: This call should only be made when ARController is stopped or paused.

After the external sensor is enabled, the integrated device sensor data is no longer used, and you must start providing sensor data into the LiveSight engine using the pushData(SensorType, double, double, double, long) method. Note that the parameters are treated differently if a different SensorType is used. For more information on providing data using this method, see the API reference.

Animation Interpolators

The visual appearance of many of the LiveSight animations can be changed by using different animation interpolators. The available interpolator types include:

  • LINEAR - Linear interpolation
  • ACCELERATE - Starts slow, and then accelerates
  • DECELERATE - Starts quick, and then decelerates
  • ACCELERATE_DECELERATE - Starts and ends slowly, but accelerates through the middle
  • OVERSHOOT - Flings forward and overshoots the last value, then comes back
  • ANTICIPATE - Starts backward, then flings forward
  • ANTICIPATE_OVERSHOOT - Starts forward, then flings forward and overshoots the target value, and finially goes back to the final value
  • BOUNCE - Rate of change 'bounces' at the end

Listeners provided by ARController

The ARController class provides a variety of listener classes that can be used to trigger event-driven code in your application. The listeners provided are:

Listener Name Purpose
OnCameraEnteredListener Listener for the Camera view-entered event. This event is triggered just before the camera frame is displayed.
OnCameraExitedListener Listener for the Camera view-exited event. This event is triggered just after the camera frame is exited.
OnCompassCalibrationChangedListener Listener for compass calibration changed event. This event is triggered by the system when the compass calibration status changes.
OnMapEnteredListener Listener for the "Map view entered" event. This event is triggered just before the Map view is displayed.
OnMapExitedListener Listener for the "Map view exited" event. This event is triggered just after the Map view is exited.
OnObjectTappedListener Listener for object selection events.
OnPanListener Listener for pan events.
OnPoseListener Listener for pose update events.
OnPreDrawListener Listener for pre-draw event. This event is triggered just before a draw is performed. This listener is useful in case a client wants to update things while in LiveSight Mode and serialize the update action with the LiveSight draw cycle. This callback is performed in both Map view and Camera view.
OnPreDrawMapListener Listener for the map pre-draw event. This event is triggered just before the map is being drawn. This listener is useful in the case where the client wants to update things on the map and serialize the update action with the draw cycle.
OnPrePresentListener Listener for the event that occurs before the frame is composited. This event occurs after the draw event.
OnPostPresentListener Listener for the event that occurs after the frame is composited.
OnLivesightStatusListener Listener for hardware and component errors related to LiveSight.
OnPitchFunction Listener for pitch changes. Allows you to override the default LiveSight pitch/zoom curve.
OnRadarUpdateListener Listener for radar update events.
OnSensorCalibrationChangedListener Listener for sensor calibration events.
OnTapListener Listener for tap events.
OnTouchDownListener Listener for touch "down" events.
OnTouchUpListener Listener for touch "up" events.
Note: OnPreDrawMapListener is a replacement for the OnMapRenderListener.onPreDraw() callback, which is not triggered while in LiveSight Mode.

All of these Listeners are added and removed by way of their respective addOnXYZListener and removeOnXYZListener methods provided by the ARController.

Draw and Present Phases

To understand how to use OnPreDrawMapListener, OnPrePresentListener, and OnPostPresentListener, it is important to understand the order and differences between Present and Draw. The order of LiveSight phases and events are as follows:

  1. Pre-Draw event
  2. Draw phase
  3. Pre-Present event
  4. Present phase
  5. Post-Present event

The Draw phase is the action of filling graphics buffers with the various components of the scene, which are applicable for the current LiveSight View. In the Draw phase, the LiveSight engine is composing different layers in a frame, such as a map and icons for the Down view, and the camera feed and icons for the Up view. This phase occurs before the Present phase, and since the Pre-Draw event is triggered before this phase, you should use the Pre-Draw event if you want, for example, for an icon to change for the next frame.

Note the absence of the Post-Draw event. If you want to do something just before presenting, use the Pre-Present event, which is the same as Post-Draw, since the Pre-Present event occurs after "Draw" but before the "Present" phase.

The Present phase refers to the composition of the buffers filled in the draw phase into the frame. In other words, this phase takes buffers and blends their contents into one buffer to be displayed. For example, this is how icons are placed on top of the camera frame. After the "Present" phase, the Post-Present event is triggered.