HERE Android SDK Developer's Guide

StreetLevelModel

The class StreetLevelModel is a member of com.here.android.mpa.streetlevel .

Class Summary

public final class StreetLevelModel

extends java.lang.Object

Represents a model for street level data.

[For complete information, see the section Class Details]

See also:

StreetLevelCoverage

Nested Class Summary

Table 1. Nested Classes in StreetLevelModel
Nested Classes

public static abstract interface StreetLevelModel.OnEventListener

Represents a listener to provide notification upon completion of a StreetLevelModel event.

public static abstract interface StreetLevelModel.OnRetrievalListener

Listener class to be used with getStreetLevel(GeoCoordinate, StreetLevelModel.OnRetrievalListener) to retrieve a StreetLevel.

Constructor Summary

Table 2. Constructors in StreetLevelModel
Constructors

StreetLevelModel ()

Public Constructor

Field Summary

Table 3. Fields in StreetLevelModel
Fields

public static final float MOVE_PRESERVE_HEADING

Pass this parameter value if the heading level is to be preserved when a StreetLevel object is redrawn.

public static final float MOVE_PRESERVE_PITCH

Pass this parameter value if the pitch level is to be preserved when a StreetLevel object is redrawn.

public static final float MOVE_PRESERVE_ZOOM

Pass this parameter value if the zoom level is to be preserved when a StreetLevel object is redrawn.

Method Summary

Table 4. Methods in StreetLevelModel
Methods

public void addStreetLevelModelListener (OnEventListener eventListener)

Adds a StreetLevelModel.OnEventListener to listen for street level model events.

public boolean addStreetLevelObject (StreetLevelObject streetLevelObject)

Adds a StreetLevelObject to the StreetLevel.

public void cancelMoveTo (boolean animate)

Cancels a StreetLevel transition initiated previously by a call to moveTo(StreetLevel, boolean, float, float, float) or moveTo(StreetLevel, boolean, GeoCoordinate, float).

public void executeSynchronized (Runnable task)

Execute a batched set of commands to the StreetLevelModel.

public PointF geoToPixel (GeoCoordinate geoCoordinates)

Converts a specified GeoCoordinate into a corresponding PointF that represents screen pixel coordinates.

public float getHeading ()

Gets the current heading of the StreetLevel.

public int getHeight ()

Gets the current height of the StreetLevelModel, in pixels.

public float getMaxHeading ()

Gets the maximum heading value that is valid for the StreetLevel.

public float getMaxPitch ()

Gets the maximum pitch value that is valid for the StreetLevel.

public float getMaxZoom ()

Gets the maximum zoom value that is valid for the StreetLevel.

public float getMinHeading ()

Gets the minimum heading value that is valid for the StreetLevel.

public float getMinPitch ()

Gets the minimum pitch value that is valid for the StreetLevel.

public float getMinZoom ()

Gets the minimum zoom value that is valid for the StreetLevel.

public float getOverlayTransparency ()

Gets the current overlay transparency value of the StreetLevel, a float within the range of [0..1].

public float getPitch ()

Gets the current pitch of the StreetLevel.

public GeoCoordinate getPosition ()

Gets the current camera position for the StreetLevelModel.

public java.util.List <StreetLevelSelectedObject> getSelectedObjects (PointF p)

Gets the List of StreetLevelSelectedObject objects which have been selected at the specified screen pixel coordinates.

public StreetLevelModelState getState ()

Gets the current state of the StreetLevelModel.

public boolean getStreetLevel (GeoCoordinate center, OnRetrievalListener listener)

Asynchronously gets the StreetLevel closest to a specified GeoCoordinate.

public StreetLevel getStreetLevel (GeoCoordinate center, int searchRadius)

Synchronously gets the StreetLevel closest to a specified GeoCoordinate.

public StreetLevel getStreetLevel (PointF point)

Gets the StreetLevel closest to a specified on-screen PointF .

public StreetLevel getStreetLevel ()

Gets the current active StreetLevel.

public int getWidth ()

Gets the current width of the StreetLevelModel, in pixels.

public float getZoom ()

Gets the current zoom level of the StreetLevel.

public boolean isCompassMapVisible ()

Gets the boolean indicating whether the street level compass map is shown for the StreetLevelModel.

public boolean isMoving ()

Determines whether the StreetLevelModel is moving from one StreetLevel to another.

public boolean isNavigationArrowVisible ()

Gets the current visibility state of the street navigation arrow.

public boolean isStreetGeometryVisible ()

Gets the current visibility state of street geometry.

public boolean isStreetLevelDataNeeded ()

Determines whether more StreetLevel data is needed.

public void moveCamera (GeoCoordinate position, float heading, float pitch, float zoom)

Moves the camera position to the specified position.

public void moveTo (StreetLevel streetLevel, boolean animation, float heading, float pitch, float zoom)

Moves the view to a specified StreetLevel (animating or not), while simultaneously setting the street level's heading (a fraction within the range of minimum and maximum levels), pitch (a fraction within the range of minimum and maximum levels), and zoom level (a fraction within the range of minimum and maximum levels).

public void moveTo (StreetLevel streetLevel, boolean animation, GeoCoordinate cameraHeading, float zoom)

Moves the view to a specified StreetLevel (animating or not), while simultaneously setting the street level's heading (a fraction within the range of minimum and maximum levels) and zoom (a fraction within the range of minimum and maximum levels).

public void pan (PointF from, PointF to)

Pans the StreetLevel from one specified on-screen PointF to another.

public GeoCoordinate pixelToGeo (PointF p)

Converts a pair of screen pixel coordinates into a corresponding GeoCoordinate.

public void removeStreetLevelModelListener (OnEventListener eventListener)

Removes an existing StreetLevelModel.OnEventListener.

public boolean removeStreetLevelObject (StreetLevelObject streetLevelObject)

Removes a StreetLevelObject from the StreetLevel.

public void rotate (PointF from, PointF to)

Rotates the StreetLevel from one specified on-screen PointF to another.

public void setCompassMapVisible (boolean visible)

Sets a StreetLevelModel to either show or hide the street level compass map.

public void setHeading (float heading)

Sets a heading for the StreetLevel.

public void setNavigationArrow (Image icon)

Sets an Image for the icon to be used as a street navigation arrow.

public void setNavigationArrowVisible (boolean visible)

Sets the visibility state for the street navigation arrow.

public void setOverlayTransparency (float alpha)

Sets an overlay transparency value for the StreetLevel, a float within the range of [0..1].

public void setPitch (float pitch)

Sets a pitch for the StreetLevel.

public void setStreetGeometryVisible (boolean visible)

Sets the visibility state for street geometry.

public void setZoom (float zoom)

Sets a zoom level for the StreetLevel.

public List toCameraOrientation (PointF point)

Determines the camera orientation required to display a specified PointF in the center of the screen.

Class Details

Represents a model for street level data. For areas with appropriate street level coverage, applications can bind a StreetLevelModel with a StreetLevelFragment to render 360-degree street level imagery.

See also:

StreetLevelCoverage

Constructor Details

StreetLevelModel ()

Public Constructor

Field Details

public static final float MOVE_PRESERVE_HEADING

Pass this parameter value if the heading level is to be preserved when a StreetLevel object is redrawn. This is the one valid value that lies outside the range of typical moveTo(StreetLevel, boolean, GeoCoordinate, float) parameters.

public static final float MOVE_PRESERVE_PITCH

Pass this parameter value if the pitch level is to be preserved when a StreetLevel object is redrawn. This is the one valid value that lies outside the range of typical moveTo(StreetLevel, boolean, GeoCoordinate, float) parameters.

public static final float MOVE_PRESERVE_ZOOM

Pass this parameter value if the zoom level is to be preserved when a StreetLevel object is redrawn. This is the one valid value that lies outside the range of typical moveTo(StreetLevel, boolean, GeoCoordinate, float) parameters.

Method Details

public void addStreetLevelModelListener (OnEventListener eventListener)

Adds a StreetLevelModel.OnEventListener to listen for street level model events.

Note: it is recommended to remove street level model event listeners after they are destroyed.

Parameters:

See also:

removeStreetLevelModelListener(OnEventListener)

public boolean addStreetLevelObject (StreetLevelObject streetLevelObject)

Adds a StreetLevelObject to the StreetLevel.

Parameters:

Returns:

True if the StreetLevelObject was added successfully, false otherwise

See also:

removeStreetLevelObject(StreetLevelObject)

public void cancelMoveTo (boolean animate)

Cancels a StreetLevel transition initiated previously by a call to moveTo(StreetLevel, boolean, float, float, float) or moveTo(StreetLevel, boolean, GeoCoordinate, float). The original view will be re-established.

Parameters:

  • animate

    A boolean specifying whether the move back to the original view is animated

public void executeSynchronized (Runnable task)

Execute a batched set of commands to the StreetLevelModel. This is useful to improve performance when multiple operations require re-rendering of the display.

Parameters:

  • task

    Task block to execute synchronously.

public PointF geoToPixel (GeoCoordinate geoCoordinates)

Converts a specified GeoCoordinate into a corresponding PointF that represents screen pixel coordinates.

Note: this method could return null if the conversion fails.

Parameters:

Returns:

The PointF representing screen pixel coordinates (could be null)

public float getHeading ()

Gets the current heading of the StreetLevel.

Returns:

The current heading

public int getHeight ()

Gets the current height of the StreetLevelModel, in pixels.

Returns:

The current height

public float getMaxHeading ()

Gets the maximum heading value that is valid for the StreetLevel.

Returns:

The maximum heading value

public float getMaxPitch ()

Gets the maximum pitch value that is valid for the StreetLevel.

Returns:

The maximum pitch value

public float getMaxZoom ()

Gets the maximum zoom value that is valid for the StreetLevel.

Returns:

The maximum zoom value

public float getMinHeading ()

Gets the minimum heading value that is valid for the StreetLevel.

Returns:

The minimum heading value

public float getMinPitch ()

Gets the minimum pitch value that is valid for the StreetLevel.

Returns:

The minimum pitch value

public float getMinZoom ()

Gets the minimum zoom value that is valid for the StreetLevel.

Returns:

The minimum zoom value

public float getOverlayTransparency ()

Gets the current overlay transparency value of the StreetLevel, a float within the range of [0..1]. The overlay transparency is the transparency for the objects overlaid on top of the street level image like link arrows, street names, icons etc.

Returns:

The current overlay transparency value

public float getPitch ()

Gets the current pitch of the StreetLevel.

Returns:

The current pitch

public GeoCoordinate getPosition ()

Gets the current camera position for the StreetLevelModel.

Returns:

The GeoCoordinate representing the current camera position

public java.util.List <StreetLevelSelectedObject> getSelectedObjects (PointF p)

Gets the List of StreetLevelSelectedObject objects which have been selected at the specified screen pixel coordinates.

Note: use getObject() instanceof to determine the exact types of StreetLevelSelectedObject objects that have been selected ( StreetLevelBuilding, StreetLevelLink, etc.).

Parameters:

  • p

    Screen Pixel coordinate

Returns:

The List of selected StreetLevelSelectedObject objects

public StreetLevelModelState getState ()

Gets the current state of the StreetLevelModel. This is a compound call to get the zoom level, heading, pitch from one API.

Returns:

The StreetLevelModelState

public boolean getStreetLevel (GeoCoordinate center, OnRetrievalListener listener)

Asynchronously gets the StreetLevel closest to a specified GeoCoordinate. This is an optimized version of getStreetLevel(GeoCoordinate, int) as it retrieves the StreetLevel with optimal radius base on the current zoom level.

Parameters:

  • center

    A GeoCoordinate representing the geographical position used to determine the closest StreetLevel.

  • listener

    Callback listener to be notified when retrieval request completes.

Returns:

True if retrieval request can be processed. False, otherwise.

Throws:

  • NullPointerException

See also:

getStreetLevel(GeoCoordinate, int)

getStreetLevel(PointF)

getStreetLevel()

public StreetLevel getStreetLevel (GeoCoordinate center, int searchRadius)

Synchronously gets the StreetLevel closest to a specified GeoCoordinate.

The search is constrained by a specified radius, in meters, from the specified GeoCoordinate .

Parameters:

  • center

    A GeoCoordinate representing the geographical position used to determine the closest StreetLevel

  • searchRadius

    Desired search radius, in meters, from center.

Returns:

The StreetLevel

See also:

getStreetLevel(GeoCoordinate, OnRetrievalListener)

getStreetLevel(PointF)

getStreetLevel()

public StreetLevel getStreetLevel (PointF point)

Gets the StreetLevel closest to a specified on-screen PointF .

Parameters:

  • point

    A PointF representing the on-screen point used to determine the closest StreetLevel

Returns:

The StreetLevel

See also:

getStreetLevel(GeoCoordinate, OnRetrievalListener)

getStreetLevel(GeoCoordinate, int)

getStreetLevel()

public StreetLevel getStreetLevel ()

Gets the current active StreetLevel.

Returns:

The current StreetLevel

See also:

getStreetLevel(GeoCoordinate, OnRetrievalListener)

getStreetLevel(GeoCoordinate, int)

getStreetLevel(PointF)

public int getWidth ()

Gets the current width of the StreetLevelModel, in pixels.

Returns:

The current width

public float getZoom ()

Gets the current zoom level of the StreetLevel.

Returns:

The current zoom level

public boolean isCompassMapVisible ()

Gets the boolean indicating whether the street level compass map is shown for the StreetLevelModel.

Returns:

True if the compass map is visible, false otherwise

public boolean isMoving ()

Determines whether the StreetLevelModel is moving from one StreetLevel to another.

Returns:

True if a StreetLevel move is in progress, false otherwise

public boolean isNavigationArrowVisible ()

Gets the current visibility state of the street navigation arrow.

Returns:

True if the street navigation arrow is currently visible, false otherwise

public boolean isStreetGeometryVisible ()

Gets the current visibility state of street geometry.

Returns:

True if street geometry is currently visible, false otherwise

public boolean isStreetLevelDataNeeded ()

Determines whether more StreetLevel data is needed.

Returns:

True if more data is needed, false otherwise

public void moveCamera (GeoCoordinate position, float heading, float pitch, float zoom)

Moves the camera position to the specified position.

Parameters:

  • position

    Position of the Camera, Can have altitude to move the camera from the default height above the street.

  • heading

    Desired heading of the Camera

  • pitch

    Desired pitch of the Camera

  • zoom

    Desired zoom of the Camera

    Note: if you wish to keep the current heading, pitch or zoom level, pass one or more of the following values as the relevant parameter:

public void moveTo (StreetLevel streetLevel, boolean animation, float heading, float pitch, float zoom)

Moves the view to a specified StreetLevel (animating or not), while simultaneously setting the street level's heading (a fraction within the range of minimum and maximum levels), pitch (a fraction within the range of minimum and maximum levels), and zoom level (a fraction within the range of minimum and maximum levels).

Note: if you wish to keep the current heading, pitch or zoom level, pass one or more of the following values as the relevant parameter:

Parameters:

  • streetLevel

    Desired StreetLevel

  • animation

    A boolean specifying whether the move is animated

  • heading

    Desired heading of the new StreetLevel

  • pitch

    Desired pitch of the new StreetLevel

  • zoom

    Desired zoom level of the new StreetLevel

See also:

moveTo(StreetLevel, boolean, GeoCoordinate, float)

getMinHeading()

getMaxHeading()

getMinPitch()

getMaxPitch()

getMinZoom()

getMaxZoom()

cancelMoveTo(boolean)

public void moveTo (StreetLevel streetLevel, boolean animation, GeoCoordinate cameraHeading, float zoom)

Moves the view to a specified StreetLevel (animating or not), while simultaneously setting the street level's heading (a fraction within the range of minimum and maximum levels) and zoom (a fraction within the range of minimum and maximum levels).

Note: if you wish to keep the current heading or zoom level, pass one or more of the following values as the relevant parameter:

Parameters:

  • streetLevel

    Desired StreetLevel

  • animation

    A boolean specifying whether the move is animated

  • cameraHeading

    A GeoCoordinate representing the desired heading of the new StreetLevel

  • zoom

    Desired zoom level of the new StreetLevel

See also:

moveTo(StreetLevel, boolean, float, float, float)

getMinHeading()

getMaxHeading()

getMinZoom()

getMaxZoom()

cancelMoveTo(boolean)

public void pan (PointF from, PointF to)

Pans the StreetLevel from one specified on-screen PointF to another.

Parameters:

  • from

    An originating on-screen PointF (pre-pan)

  • to

    An on-screen PointF representing the end of the pan

public GeoCoordinate pixelToGeo (PointF p)

Converts a pair of screen pixel coordinates into a corresponding GeoCoordinate.

Note: this method could return null if the conversion fails.

Parameters:

  • p

    Position of screen pixel to convert

Returns:

The GeoCoordinate (could be null)

public void removeStreetLevelModelListener (OnEventListener eventListener)

Removes an existing StreetLevelModel.OnEventListener.

Note: it is recommended to remove street level model event listeners after they are destroyed.

Parameters:

public boolean removeStreetLevelObject (StreetLevelObject streetLevelObject)

Removes a StreetLevelObject from the StreetLevel.

Parameters:

Returns:

True if the StreetLevelObject was removed successfully, false otherwise

public void rotate (PointF from, PointF to)

Rotates the StreetLevel from one specified on-screen PointF to another.

Parameters:

  • from

    An originating on-screen PointF (pre-rotation)

  • to

    An on-screen PointF representing the end of the rotation

public void setCompassMapVisible (boolean visible)

Sets a StreetLevelModel to either show or hide the street level compass map. By default, the compass map is visible.

The compass map is a circular map view that can be viewed by panning downward towards the ground. Its primary purpose is to provide users their direction and location context while they're viewing the street level. Users cannot directly manipulate a compass map, but changes from panning or navigating the street level image are immediately reflected in it.

Parameters:

  • visible

    A boolean specifying whether compass map is going to be visible

public void setHeading (float heading)

Sets a heading for the StreetLevel.

Parameters:

  • heading

    Desired heading

See also:

getMinHeading()

getMaxHeading()

public void setNavigationArrow (Image icon)

Sets an Image for the icon to be used as a street navigation arrow. There is no default navigation arrow image. If user does not provide one, no arrow will be displayed, but there is a hollow area at the bottom of the street level image where the arrow is supposed to be. Navigating the street level is still possible in this case by tapping on the corners of the hollow area.

Parameters:

  • icon

    A Image representing image of the arrow

Throws:

  • NullPointerException

    if icon is null.

  • IllegalArgumentException

    if icon is not valid

public void setNavigationArrowVisible (boolean visible)

Sets the visibility state for the street navigation arrow. By default the navigation arrow is not visible.

Parameters:

  • visible

    A boolean specifying whether the street navigation arrow is visible

public void setOverlayTransparency (float alpha)

Sets an overlay transparency value for the StreetLevel, a float within the range of [0..1]. This method sets the transparency for the objects overlaid on top of the street level image like link arrows, street names, icons etc.

Parameters:

  • alpha

    Desired overlay transparency

public void setPitch (float pitch)

Sets a pitch for the StreetLevel.

Parameters:

  • pitch

    Desired pitch

See also:

getMinPitch()

getMaxPitch()

public void setStreetGeometryVisible (boolean visible)

Sets the visibility state for street geometry.

Parameters:

  • visible

    A boolean specifying whether street geometry is visible or not

public void setZoom (float zoom)

Sets a zoom level for the StreetLevel.

Parameters:

  • zoom

    Desired zoom level

See also:

getMinZoom()

getMaxZoom()

public List toCameraOrientation (PointF point)

Determines the camera orientation required to display a specified PointF in the center of the screen.

Parameters:

  • point

    Desired center PointF which would require a change in camera orientation

Returns:

The list of Float values representing the required camera orientation, where the first element contains the heading (in degrees) and second element contains the pitch (in degrees)