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 SupportCompositeFragment 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.

SupportCompositeFragment

The Fragment subclass related to LiveSight functionality is SupportCompositeFragment. 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, SupportCompositeFragment also includes all of the methods found in SupportMapFragment. SupportCompositeFragment is useful in the situation where an application wants to include both map and LiveSight functionality.

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

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

Adding and Initializing SupportCompositeFragment

The first step to integrate LiveSight functionality into an application is to insert a SupportCompositeFragment into the view layout. This is accomplished by adding com.here.android.mpa.ar.SupportCompositeFragment 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.SupportCompositeFragment"
  android:id="@+id/compositefragment"
  android:layout_width="fill_parent"
  android:layout_height="fill_parent"/>
Note: When using SupportCompositeFragment you do not have to also use SupportMapFragment. SupportCompositeFragment is a superset of SupportMapFragment.

After adding SupportCompositeFragment to the layout the fragment must be initialized by calling SupportCompositeFragment.init(OnEngineInitListener) method. During this asynchronous initialization the MapEngine is initialized to create an instance of Map that is associated with SupportCompositeFragment. 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 SupportCompositeFragment compositeFragment = (SupportCompositeFragment)
     getFragmentManager().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 SupportCompositeFragment");
      }
    }
  });
}
Note: com.here.android.mpa.ar.SupportCompositeFragment 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.SupportCompositeFragment or the map engine will fail to initialize properly. This applies only when using com.here.android.mpa.ar.SupportCompositeFragment.
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.SupportCompositeFragment.