SDK for Android Developer's Guide

LiveSight

LiveSight enables user experiences that use the real world as an interface. With LiveSight developers can overlay geospatial content on the real world which is displayed using the device camera. Additionally, an immersive experience is created by using the device sensors to track movement in space and update the view accordingly.

The key concepts covered in this section include adding LiveSight to an Android application, transitioning from Map Mode to LiveSight Mode, and customizing the LiveSight experience. The classes covered include AndroidXCompositeFragment and ARController.

Note: LiveSight requires the following sensors enabled:
  • GPS
  • Compass
  • Accelerometer
  • Gyroscope
LiveSight does not function properly or does not function at all if these sensors are not working or incorrectly calibrated.

AndroidXCompositeFragment

The Fragment subclass related to LiveSight functionality is AndroidXCompositeFragment. It is called "composite" because it exposes both Map and LiveSight functionality in one Android UI component, with an easy way to switch between the two; therefore, in addition to methods related to LiveSight functionality, AndroidXCompositeFragment also includes all of the methods found in AndroidXMapFragment. AndroidXCompositeFragment is useful in the situation where an application wants to include both map and LiveSight functionality.

The remainder of this section uses AndroidXCompositeFragment in code samples and discussions.

Note: AndroidXCompositeFragment.getScreenCapture(OnScreenCaptureListener) method has the same functionality as AndroidXMapFragment.getScreenCapture(OnScreenCaptureListener). It does not support taking screen snapshots of the LiveSight Camera View or AR Objects on a map.

Adding and Initializing AndroidXCompositeFragment

The first step to integrate LiveSight functionality into an application is to insert a AndroidXCompositeFragment into the view layout. This is accomplished by adding com.here.android.mpa.ar.AndroidXCompositeFragment to the Android XML layout file as follows:

<!-- Example fragment. This can be integrated and annotated
like any other android Fragment or View widget -->
<fragment
  class="com.here.android.mpa.ar.AndroidXCompositeFragment"
  android:id="@+id/compositefragment"
  android:layout_width="fill_parent"
  android:layout_height="fill_parent"/>
Note: When using AndroidXCompositeFragment you do not have to also use AndroidXMapFragment. AndroidXCompositeFragment is a superset of AndroidXMapFragment.

After adding AndroidXCompositeFragment to the layout the fragment must be initialized by calling AndroidXCompositeFragment.init(OnEngineInitListener) method. During this asynchronous initialization the MapEngine is initialized to create an instance of Map that is associated with AndroidXCompositeFragment. The ARController is also be created. For more information about ARController, see Customizing LiveSight.

The following code example illustrates the basic initialization flow when an Activity is created. init(OnEngineInitListener) method uses OnEngineInitListener parameter to signal the caller when the asynchronous initialization is completed.


@Override
public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  // setIsolatedDiskCacheRootPath must be called before setContentView is called
  boolean success = com.here.android.mpa.common.MapSettings.setIsolatedDiskCacheRootPath(
    getApplicationContext().getExternalFilesDir(null) + File.separator + ".here-maps",
    "{YOUR_INTENT_NAME}"); /* ATTENTION! Do not forget to update {YOUR_INTENT_NAME} */
  if (!success) {
    Toast.makeText(getApplicationContext(), "Unable to set isolated disk cache path.", 
      Toast.LENGTH_LONG);
    return;
  }

  // Before calling setContentView, the app must be granted all required permissions such as
  // Manifest.permission.WRITE_EXTERNAL_STORAGE if using a shared disk cache or using 
  // an isolated disk cache pointing to an external location.
  // Failing to do so will result map engine failed to initialize properly.
  setContentView(R.layout.activity_main);
  // Search for the Composite Fragment
  final AndroidXCompositeFragment compositeFragment = (AndroidXCompositeFragment)
     getSupportFragmentManager().findFragmentById(R.id.compositefragment);
  // initialize the Composite Fragment and
  // retrieve the map that is associated to the fragment
  compositeFragment.init(new OnEngineInitListener() {
    @Override
    public void onEngineInitializationCompleted(
        OnEngineInitListener.Error error) {
      if (error == OnEngineInitListener.Error.NONE) {
        // now the map is ready to be used
        map = compositeFragment.getMap();
        // the arController is also ready to be used now
        arController = compositeFragment.getARController();
      } else {
        System.out.println(
          "ERROR: Cannot initialize AndroidXCompositeFragment");
      }
    }
  });
}
Note: com.here.android.mpa.ar.AndroidXCompositeFragment has Fragment.setRetainInstance(boolean) set to true; therefore, onCreate(Bundle) should not be called again when Activity is re-created (for example, after an orientation change).
Note: Ensure the required application permissions are granted before Activity.setContentView is called on the layout containing com.here.android.mpa.ar.AndroidXCompositeFragment or the map engine will fail to initialize properly. This applies only when using com.here.android.mpa.ar.AndroidXCompositeFragment.
Note: If the use of isolated disk cache is desired with LiveSight, MapSettings.setIsolatedDiskCacheRootPath must be called before Activity.setContentView on the layout containing com.here.android.mpa.ar.AndroidXCompositeFragment.