HERE Android SDK Developer's Guide

Street-Level Objects

The street-level API exposes access and allows interaction with two different types of objects that are part of the street-level scene:

  • PROXY_OBJECT - provided automatically in the street-level scene when it is displayed.
  • USER_OBJECT - provided by the application and can be added in to the street-level scene.

The supported street-level proxy objects are:

  • StreetLevelBuilding - a building that is visible in the street-level scene
  • StreetLevelLink - a navigation arrow that can be clicked by the user to navigate from one panorama to another

The following code snippet highlights the selected building from a street-level scene. All the logic is implemented in the StreetLevelGesture.OnGestureListener.onObjectsSelected(List<StreetLevelSelectedObject> selectedObjects) method.


private StreetLevelGesture.OnGestureListener listener
  = new StreetLevelGesture.OnGestureListener() {

  ...
  @Override
  public boolean onObjectsSelected
      (List<StreetLevelSelectedObject> selectedObjects) {
    boolean consumed = false;

    for (StreetLevelSelectedObject object : selectedObjects) {
      if (object!= null) {
        ViewObject viewObject = (ViewObject) object.getObject();
        if (viewObject instanceof StreetLevelBuilding) {

          StreetLevelBuilding building
              = (StreetLevelBuilding) viewObject;
          building.setHighlight(0.5f);
          consumed = true;
          break;
        }
      }
    }
    return consumed;
  }
  ...

};

The supported street-level user objects are:

  • StreetLevelIcon - an image that has a specified location on the street level map
  • StreetLevelBillboard - a billboard that has a specified location on the street-level map
Note: Both objects can also be attached to a StreetLevelBuilding.

The major differences between these objects are the way the size is specified and how they are rendered when a zoom operation is performed. The billboard has the size specified in meters so it is always rendered relative to the size of the building, while the StreetLevelIcon has the size specified in pixels and has a StreetLevelIconSize.ScalePolicy to define the rendering size. Relevant StreetLevelModel methods that control adding and removing street-level objects are:

  • StreetLevelModel.addStreetLevelObject(StreetLevelObject streetLevelObject)
  • StreetLevelModel.removeStreetLevelObject(StreetLevelObject streetLevelObject)

The easiest way to enhance an application by displaying a street-level user object is to create the object, set the content (desired image) and properties (image size and building identifier) and add it to the street-level model as described in the code snippet below.


@Override
public boolean onObjectsSelected(List<StreetLevelSelectedObject> selectedObjects) {
  boolean consumed = false;
  for (StreetLevelSelectedObject object : selectedObjects) {
    if (object != null) {
      ViewObject viewObject = (ViewObject) object.getObject();
      if (viewObject instanceof StreetLevelBuilding) {
        StreetLevelBuilding building = (StreetLevelBuilding) viewObject;
        building.setHighlight(0.5f);
        consumed = true;
        // Create Image
        com.here.android.mpa.common.Image streetLevelImage =
          new com.here.android.mpa.common.Image();
        try {
          streetLevelImage.setImageResource(
            R.drawable.streetLevelIconImage);
        } catch (Exception io) {
          System.out.println(
            "ERROR: Cannot create street " + "level icon image");
        }
        // Create Icon and set properties
        StreetLevelIcon streetLevelIcon = new
          StreetLevelIcon(building.getPosition(),streetLevelImage);

        StreetLevelIconSize size = new StreetLevelIconSize(100,100);
        streetLevelIcon.setSize(size);
        streetLevelIcon.setAttachmentIdentifier(building.getIdentifier());
        // Add icon to the street level
        streetLevelModel.addStreetLevelObject(streetLevelIcon);
        break;
      }
    }
  }
  return consumed;
}
Note: It is not necessary to have both the StreetLevelFragment and the MapFragment in the same activity. However, before a StreetLevelFragment can be used, the area to be displayed in the StreetLevelFragment must be previously shown on the Map in order for the related data to be downloaded onto the device.

Placing Street-level Objects

The HERE Android SDK also allows you to control the placement of a street-level object. For example, you may wish to put a large billboard to cover the entire side of a building, or you may want a small icon in the middle of a road. Whether it is a billboard or an icon, you can use the StreetLevelIconPlacement class to control how your street-level object is presented to the user.

The first step to place your object is to determine whether your street-level object is attached to a building, or placed according a geocoordinate location.
  • For objects attached to a building, call setAttachmentIdentifier(Identifier) with a building Id.
  • For objects not attached to a building, the HERE SDK places the object at its geocoordinate position. You can optionally call setAnchorPoint(PointF) to indicate which part of the billboard is used as the anchor, hovering exactly over the specified geocoordinate position.
Note: Using the StreetLevelIconPlacement.HorizontalPlacement.DEFAULT placement mode places the object at its geocoordinate position, even if setAttachmentIdentifier() has been set.

Next, call the StreetLevelIconPlacement constructor to create a StreetLevelIconPlacement object, and call setPlacementMode() to set it to the street-level object. See the following tables to see descriptions of the valid vertical and horizontal placement modes.

VerticalPlacement value Notes
TERRAIN The vertical placement height parameter is evaluated as meters above the current terrain.
ATTACHMENT Used with objects that are attached to buildings. The height parameter is evaluated as a ratio of the building height, with 0 indicating the ground level, and 1 being the top of the building.
FACADE Used with HorizontalPlacement.FACADE. Refer to the table below. (If this value is used with another horizontal placement mode, the HERE SDK treats it as HorizontalPlacement.TERRAIN.)
DEFAULT The vertical placement height parameter is evaluated as meters above sea level.
HorizontalPlacement value Notes
FACADE
  • Used for objects attached to buildings
  • Places the street-level object on the side of the building that is most visible to the camera
  • Object placement is updated as the camera moves
  • Using it with VerticalPlacement.FACADE places the object at a height as defined by you or the HERE SDK, whichever is higher
SURFACE
  • Used for objects attached to buildings
  • "Snaps" object to the closest point on the building, as determined by the object's geocoordinate position
  • Object is viewable through the attached building's faces (For example, an object that has "snapped" to building face A is viewable through building face B, even if A is obstructed)
TRACK_CAMERA
  • Used for objects not attached to buildings
  • Object is placed at the camera location. The object's geocoordinate is ignored
  • VerticalPlacement mode is ignored, regardless of the set value
  • Vertical placement height is evaluated as meters above or below the camera
CENTROID
  • Used for objects attached to buildings
  • Can only be used for icons, not billboards
  • When used, icon is placed as if it is in the center of the attached building
  • You can see the icon through the faces of the attached building
DEFAULT
  • The object is placed at its geocoordinate position, even if it is associated with a building.

Orienting Street-level Objects

You can control the orientation of street-level billboards by using the StreetLevelBillboardOrientation class. To use this class, call its constructor to create an object instance, and then set it to your billboard object using StreetLevelBillboard.setOrientation().

The StreetLevelBillboardOrientation constructor has three arguments: an orientation mode enum, a normal vector indicating how the billboard is oriented, and an up vector indicating how the billboard stands. Vectors may be ignored depending on the orientation mode.

The following is a list of the possible orientation mode values:
  • FIXED - Orients the billboard according to a normal and up vector.
  • VERTICAL_FIXED - The billboard is always upright. The horizontal orientation of the billboard is set according to a normal vector.
  • BILLBOARD - The billboard is always upright and oriented towards the camera.