map.md

Map

Packages dependencies Be aware that you need to have installed at least the following packages:

• A MAPDATA package, which contains maps information such as zoom levels and scales.
• 2D only A TILES package, which contains .3cm files that will be displayed.
• 3D only A MAP3DPACKAGE package, which contains all 3D files.

You can easily check if the package is available on the device with the following method: ISSite#hasPackage(EPackageType.MAP_DATA);.

Display a MapView

A ISMapView is provided and can be used to display a 2D/3D map component with specific interactive areas. The API also provides advanced features such as additional rendering layouts management (promotional, special areas etc …) or specific events handling. To use this component you have to make sure that you have downloaded all the required packages.

The ISMapView will display a 2D tiled map or 3D plane of the site (depending on your ISERenderMode), and provide common map interaction (such as move, center, and pinch to zoom), animation and more. It also handle the ISZone rendering and touch behavior.

The ISMap3DView uses the JPCT Android engine and you can refer to its documentation here.

In order to use our MapAPI, you will need to instanciate a ISMap2DView or a ISMap3DView (you can not use both instance simultaneously):

// ISMap2DView Java instanciation
ISMap2DView mMapView = new ISMap2DView(getActivity()); 

<!-- ISMap2DView instanciation via xml layout -->
<com.insiteo.lbs.map.ISMap2DView
    android:id="@+id/map"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"/>

Prerequisites You will need to initialize Insiteo before instantiating ISMapView. ISMapView events will be notified via the ISIMapListener interface. The single ISIMapListener associated to the map is by default the Context that created it (the Activity in most cases) but can be change with the ISMapView#setListener(ISIMapListener listener) method (useful when your using the ISMapView in a Fragment).

Adding graphical objects on map

The ISMapView also allows you to display custom interactive objects. This can be done by implementing the renderer interface ISIRenderer and the Render Touch Object interface ISIRTO or by simply extending the ISGenericRenderer and ISGenericRTO that already provide common behavior (icon and label rendering, touch handling and so on, you can check their behavior in our SampleApp).

The ISMapView will also detect touches, and dispatch them to all ISIRTO. A listener can be set on the map view, to be notified of clicks on specific ISIRTO class (see ISMapView class documentation).

Adding, removing ISGenericRTO to the ISMapView and listening for their events:

/* This method will add the rto at the map center */
ISGenericRto genericRTO = new ISGenericRTO(mapView.getScreenCenter(), "MyRTO");
mapView.addRTO(genericRTO);

/* And to remove it */
mapView.removeRTO(genericRTO);

/* This method will add the rto to the given zone */
ISGenericRto genericRTO = new ISGenericRTO(mapView.getScreenCenter(), "MyRTO");
genericRTO.setLabel("MyRTO");
mapView.addRTOInZone(zoneId, genericRTO);

/* And to remove it */
mapView.removeRTOFromZone(zoneId, genericRTO);

/* Add a listener for this type of IRTO */
mMapView.setRTOListener(listener, GfxRto.class);

Create your own ISRenderer

A renderer is a class that defines drawing and touch behavior for a certain type of IRTO. Once added to the ISMapView a renderer will have its render2D or render3D method call by the map rendering loop to enable to do its rendering operation and it will also be notify when to handle touch events (onTouchDown, onTouchPointerDown, onTouchMove, onTouchPointerUp, onTouchUp). If you want to use your own customized renderer, you will need to create a class that implements the IRenderer interface. Then you will be able to specify your own renderering and touch behavior.

IRenderer uses a priority value that will define it's 2D rendering and touch order. Highest priority renderered last (so on the top) and notify by touch first.

To register a new renderer as a map's renderer, simply do like this:

/* How to add a custom renderer */
mapView.addRenderer(myCustomRenderer);

Create your own ISIRTO

To draw a customized rendering object on the map, you will need to create a class that implements the ISIRTO interface. Then you will be able to specify your object's behavior through methods like:

/* The method you will need to override in order to manually manage your object 2D rendering */
public void render2D(Canvas aCanvas, double aRatio, Point aOffset, float aAngle) {
}

/* The method you will need to override in order to manually manage your object 3D rendering */
public void render3D(ISWorld world, FrameBuffer frameBuffer, Map map, double ratio, float angle) {
}

/* Because once added to the world a 3D object will always be drawn it is up to you to remove the object from the world when required */
public void remove3DObject(ISWorld world) {
}

/* Method that gets called when the IRTO have to handle a touch down event */
public ETouchObjectResult onTouchDown(Touch aTouch) {

Where to find my ISRTO?

All ISIRTO of class corresponding to the custom renderer class, when added via ISMapView, will be put in custom renderer. If you add an ISIRTO and there are no ISIrenderer defined for that specific class, the ISMapView will automatically create a ISGenericRenderer to handle it. So creating your own ISIRTO does not mean that you necessarily have to create you own ISIrenderer.

Zone offsets in 3D

In 3D, you can specify an offset through the z axis still by using the following method mapView.addRTOInZone(zoneId, rto, zoneOffset).

Zone/POI

With the Insiteo API, you can link your content to our zone based system. To do that you will have to register this content through our back office. For example you can link a shop to one of our zone and then, get back this content in your application, simply by requesting our API.

Link with external content

With the Insiteo framework, you can link your content to our zone based system. To do that you will have to register this content through our back office. For example you can link a shop to one of our zone and then, get back this content in your application, simply by requesting our framework.

Insiteo Interactive maps - 2 minutes tutorial

To get all related Insiteo zones for a given external POI, you can use the ISMapDBHelper class like so:

// Get all Zone/POI assocations for a given external identifier
List<ZonePoi> zonePois = ISMapDBHelper.getZoneAssocFromExtPoi(extPoiID);

Note: A list is returned, because you can link a POI to several zones and a zone can contains several POIs.

To get all POIs related to a given Insiteo zone, you can use the ISMapDBHelper class like so:

//Get all external Zone/POI assocations for a given zone identifier
public static List<ISZonePoi> getPoiAssocFromZone(int aZoneId, boolean aExternal);

Each method returns an ISZonePoi object which contains a position in meters and an offset (if specified) in order to place your on ISIRTO on our map.

Zone/Poi associations offsets

If you want an offset to be used when drawing an ISIRTO in a ISZone you have to explicitly set it we adding the ISIRTO to the ISMapView.

Best practices

It is best practice to call the ISMapView onPause and onResume methods in your Activity or Fragment respective methods.

Where to go from there?

• Get your first location.
• Configure your iBeacons.
• Compute your first itinerary.
• Setup your first geofencing zone.
• Enable analytics.

You missed a thing?

• Project setup.