Your search returned no results

Try another search term or view Stack Exchange, where we have active conversations with Developers about GIS.

    http://gis.stackexchange.com/
    Support channel in Stack Exchange

    Thousands of developers around the world have helped make CartoDB a success, and we have active conversations with them about GIS in Stack Exchange.

    Go to Stack Exchange

    Getting Started

    The following workflow guides you through the process of getting started with the Mobile SDK.

    Prerequisites
    1. Download the SDK by managed libraries, or by individual packages
    2. Register your mobile app to get your API Key
    3. Create your mobile project, based on the platform of your device
    4. Create your first mobile app with basic map features
    5. Use our sample mobile apps to test your project, and re-use prepackaged styles

    Prerequisites

    You must have account access to develop location apps with CARTO Engine.

    • View our pricing page for details about which accounts include the Mobile SDK

    • Access to Mobile SDK features are managed by CARTO. If you cannot reproduce any of the steps in this Getting Started section, contact us to ensure that you have account access, and that the Mobile SDK features are enabled for your account

    Downloading the SDK

    To begin using the Mobile SDK, download the required SDK packages and libraries based on your mobile platform. Contact us if you have questions about Mobile SDK packages and what features are included.

    There are multiple ways to download SDK packages:

    • Use the Managed library package based on your platform - this is the suggested method for managing SDK features, and also contains some default style files

    • Download specific versions of SDK packages as zip files, and add them to you projects

    Managed Libraries

    These SDK libraries are managed by CARTO and include all the required libraries to support the Mobile SDK. In some cases, managed libraries are not available and the direct download package url is provided.

    Download Packages

    If you do not want to use package manager, you can download SDK from the Github mobile-sdk project releases page

    Registering your App

    You must register your mobile applications under your CARTO.com account settings. Once an app is added, you can retrieve the mobile app license key, which is needed for your app code.

    The following procedure describes how to register mobile apps under your account settings. While the number of mobile apps is unlimited, application quota consumption rules are enforced based on your account plan. Contact us if you have questions about your mobile account options.

    1. Access your Account settings from the CARTO Dashboard

      Access mobile apps from API keys

      Your profile information appears.

    2. Click API keys

      The API key page opens, displaying options for CARTO or Mobile Apps.

    3. Click Mobile apps to add mobile applications to your account

      Note: If this option is not visible from your account settings, contact us to ensure that Mobile SDK features are enabled for your account.

      No registered mobile apps

    4. Click NEW APPLICATION

      The new application settings appear.

    5. Enter options for the mobile application

      New mobile app settings

      The following mobile application settings are available:

      Mobile Application Settings Description
      App icon Select an icon to represent your mobile application in your account
      Name An informative name of the mobile application in your account
      Description A description about the mobile application in your account
      Platform Identifies the type of mobile app platform. Some options may not be available, based on your account plan

      Note: Once a mobile application is saved, you cannot edit the Platform setting. As an alternative, you can delete the application and recreate it with new settings.

      Tip: When you select a Platform, the Application ID displays more details about what identifiers, or packages, are required.

      Platform App ID hint
      Application ID The identification of the mobile app in the App store that is required for development with the Mobile SDK.

      The following application ids identify the Platform selected:

      - Android: package from the AndroidManifest.xml file or applicationId in build.gradle

      - iOS: Bundle Identifier. You can find it in the project properties in Xcode

      - Xamarin Android: package from the AndroidManifest.xml file

      - Xamarin iOS: Bundle Identifier from the project Info.plist

      - Windows Phone: UUID from the Windows package.appmanifest
      App type Identifies the type of mobile application, which are subject to different quota limitations

      - Open: This app type is open to the public and is available as free download in public app stores

      - Private: Available for Enterprise accounts only, allows organizations to publish their apps internally and have paid app use cases.
    6. Click SAVE CHANGES

      The Mobile apps page refreshes, displaying the added mobile application and the features enabled.

    Access your API Key

    Once your mobile apps are registered for your account, you can retrieve the API Key for each application. This is useful when you need to copy and paste the API Key for mobile development.

    1. From the Mobile apps section of your API Keys, click a mobile application name

      Registered mobile apps

      The application settings appear, and include the license key and amount of quota for the application.

    2. Copy the API Key from the License key section

      The following example displays the API Keys section for a selected mobile application. Note, the API Key in the example image is blurred out for privacy.

      Example of mobile app settings

    3. Click the back navigation arrow, located next to the app name, to return Mobile apps section of your API Keys

    License Key Rules

    Mobile App API Keys cannot be regenerated manually, but are automatically regenerated in the following scenarios.

    • If you upgrade your account plan that includes additional mobile features, the Mobile apps license key is automatically regenerated

    • If you change the App type the Mobile apps license key is regenerated

    You will receive a notification when mobile api keys are regenerated.

    Deleting an App

    Once a mobile application is saved, you cannot edit the Platform setting. As an alternative, you can delete the application and recreate it with new settings.

    1. From the Mobile apps section of your API Keys, click a mobile application name

      The application settings appear, and include the license key and amount of quota for the application.

    2. Click Delete this application from the bottom of the app settings

      Delete mobile app

    3. Click the back navigation arrow, located next to the app name, to return Mobile apps section of your API Keys

    Creating your Project

    Once your mobile apps are registered and you have your API Keys, it is recommended to familiarize yourself with the setup for the platform that you are using. Some of these platforms contain unique map features that are only available based on the mobile platform. You can then use sample mobile apps and add basic and advanced map features.

    Android Implementation

    If using Android as the mobile platform, follow this implementation procedure.

    1) Add the following to the build.gradle of your project:

      dependencies {
          compile 'com.carto:carto-mobile-sdk:4.1.0@aar'
      }

    2) Define INTERNET permission for your AndroidManifest.xml

    <uses-permission android:name="android.permission.INTERNET"/>

    3) Define your application layout

    Define main layout as res/layout/main.xml, so that it contains com.carto.ui.MapView element:

    <?xml version="1.0" encoding="utf-8"?>
    <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        android:layout_width="fill_parent"
        android:layout_height="fill_parent"
        android:orientation="vertical" >
       <com.carto.ui.MapView
        android:id="@+id/mapView"
        android:layout_width="fill_parent" 
        android:layout_height="fill_parent" 
        />
    </LinearLayout>

    4) Find the MapView object

    Define the MapView type in your main activity class and load layout. This enables you to load the MapView from the layout. The object itself was already created during the layout creation process, this step is specific to finding and referencing the MapView object in your request.

    Java

    	public class HelloMap3DActivity extends Activity {
        	private MapView mapView;
    
    	    @Override
    	    public void onCreate(Bundle savedInstanceState) {
    	        super.onCreate(savedInstanceState);
    	        setContentView(R.layout.main);
    			
    			mapView = (MapView) this.findViewById(R.id.mapView);
    		}
    	}

    Kotlin

    class MainActivity : AppCompatActivity() {
        val LICENSE = "<YOUR-LICENSE-KEY"
    
        var mapView: MapView? = null
    
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.main);
    
            MapView.registerLicense(LICENSE, this)
    
    	   mapView = findViewById(R.id.mapView) as MapView
    
        }
        

    5) Initialize the mobile map

    The map object needs a default map source in order to initialize. There are several requirements for this to work properly.

    • Replace YOUR_LICENSE_KEY with your Mobile App API Key

    • Define the first layer of the map, which will be the basemap layer. This is a vector map layer, which requires that you load and define styles in the assets of this layer. You can also add other map layers once a basemap is configured

    Example

    The following example shows the complete code for initializing your Android mobile map.

    Java

    	
    	// Create basemap layer with bundled style
    	CartoOnlineVectorTileLayer baseLayer = new CartoOnlineVectorTileLayer(CartoBaseMapStyle.CARTO_BASEMAP_STYLE_DEFAULT);
    	 
    	// Add layer to map
    	mapView.getLayers().add(baseLayer);

    Kotlin

    	   
    	// Create basemap layer with bundled style
    	val layer = CartoOnlineVectorTileLayer(CartoBaseMapStyle.CARTO_BASEMAP_STYLE_DEFAULT)
    	// Add layer to map
    	mapView?.layers?.add(layer)

    You can now start using the application on your phone and view the default basemap.

    iOS Implementation

    If using iOS as the mobile platform, follow this implementation procedure.

    1) Create new project in Xcode and add Mobile SDK framework using Podfile

    • Create a new ‘Single View application’ in your Xcode project

    • Get current version of CARTO Mobile SDK using CocoaPod:

    // Add to your CocoaPods Podfile:
    
    pod 'CartoMobileSDK', '4.1.0'

    2) Modify Controller for Map View

    • Extend ViewController and add MapView manipulation code into it. Ensure it is Objective C++, not plain Objective C class

    • Rename ViewController.m (comes with template) to ViewController.mm, to avoid compilation issues

    • Implement ViewController.h to extend GLKViewController, instead of UIViewController

    • You must replace YOUR_LICENSE_KEY with your Mobile Apps and API Key in the code below

    #import  <GLKit/GLKit.h>
    
    @interface ViewController : GLKViewController
    
    @end
    
    #import "ViewController.h"
    #import <CartoMobileSDK/CartoMobileSDK.h>
    
    @implementation ViewController
    
    - (void)loadView {
      // 1. The initial step: register your license. 
      // **Note:** This must be done before using MapView
      [NTMapView registerLicense:@"YOUR_LICENSE_KEY"];
      [super loadView];
    }
    
    
    - (void)viewDidLoad
    {
    
     [super viewDidLoad];
      // 1. Add minimal map definition code 
    
      // 2. Ensure the storyboard has NTMapView connected as a view
      NTMapView* mapView = (NTMapView*) self.view;
    
      // 3. Create online vector tile layer, use style asset embedded in the project
      NTVectorTileLayer* vectorTileLayer = [[NTCartoOnlineVectorTileLayer alloc] initWithSource: @"nutiteq.osm"];
    
      // 4. Add vector tile layer
      [[mapView getLayers] add:vectorTileLayer];
    
    
    @end

    3) Modify storyboard to enable Map View

    The default storyboard template uses UIView class, you must use NTMapView instead.

    Note: If you are using iPhone (Main_iPhone.storyboard) or iPad (Main_iPad.storyboard) files for iOS, you must repeat this step to change the default storyboard.

    • Open Main.Storyboard, select View Controller Scene -> View Controller -> View

    • From Navigator window, select Identity Inspector, change the first parameter (Custom Class) to NTMapView (from the default UIView).

    Xcode storyboard

    4) Run the iOS app

    The map should appear with the default world map provided by OpenStreetMap, as defined in your ViewController. You can zoom, rotate, and tilt with these default settings.

    5) View the MapView object method changes

    // 1. Set the base projection to be used for MapView, MapEventListener and Options methods
      NTEPSG3857* proj = [[NTEPSG3857 alloc] init];
      [[mapView getOptions] setBaseProjection:proj]; // Since EPSG3857 is the default base projection, this is not needed
    
      // 2. General options
      [[mapView getOptions] setRotatable:YES]; // allows the map to rotate (this is the default behavior)
      [[mapView getOptions] setTileThreadPoolSize:2]; // use two threads to download tiles
    
      // 3.Set initial location and other parameters, _do not animate_
      [mapView setFocusPos:[proj fromWgs84:[[NTMapPos alloc] initWithX:24.650415 y:59.428773]]  durationSeconds:0];
      [mapView setZoom:14 durationSeconds:0];
      [mapView setRotation:0 durationSeconds:0];

    Xamarin (Android and iOS) Implementation

    If using Xamarin as the mobile platform, follow these implementation procedures for Xamarin (Android) and Xamarin (iOS).

    1. Add library as nuget CartoMobileSDK.iOS and/or nuget CartoMobileSDK.Android from the main repo, and add to your mobile app.

    2. Register your mobile app to get the API Key

      Note: If you are using both Xamarin Android and iOS, register each platform as its own app.

    3. Create a cross-platform project for your apps

      Each platform still needs to be registered as its own app, since many app aspects (such as UI, file system, and so on) are platform-specific. However, when executing API requests with the Mobile SDK, you can create one Xamarin project for Android and iOS and share the code. Some exceptions apply in regards to API calls which need Android context, or file system references. For example, the following API requests are platform specific:

      • Register license key: MapView.RegisterLicense()
      • Create package manager: new CartoPackageManager()

      Almost all of the map related API code (such as adding layers and objects to map, handling interactions and clicks, etc.) can be shared for iOS and Android through one project!

    The following sections describe the common code that can be shared, and the individual platform setup requirements for Xamarin options.

    Xamarin Common Code for all Xamarin platforms
    Xamarin Forms App
    Xamarin Android App
    Xamarin iOS App

    Xamarin Common Code

    The following common code can be used for both Xamarin Android and Xamarin iOS apps. This is useful if you are sharing code between projects.

    1) Add a marker, based on defined coordinates

    Add the following code after creating the MapView.

    Note: You must have Icon.png that is a bitmap, located in the Assets folder of your project

      // 1. Create overlay layer for markers
      var proj = new EPSG3857();
      var dataSource = new LocalVectorDataSource (proj);
      var overlayLayer = new VectorLayer (dataSource);
      mapView.Layers.Add (overlayLayer);
    
      // 2. Create Marker style
      var markersStyleBuilder = new MarkerStyleBuilder ();
      markersStyleBuilder.Size = 20;
      UnsignedCharVector iconBytes = AssetUtils.LoadBytes("Icon.png");
      var bitmap = new Bitmap (iconBytes, true);
      markersStyleBuilder.Bitmap = bitmap;
    
      // Example Marker for London
      var marker = new Marker (proj.FromWgs84(new MapPos(-0.8164,51.2383)), markersStyleBuilder.BuildStyle ());
      dataSource.Add (marker);



    Tip: See mobile-dotnet-samples for other common map options for the Xamarin mobile platform, such as:

    • Control map view - set zoom, center, tilt etc.
    • Listen events (MapListener.cs) of clicks to map and map objects
    • Add other objects: Lines, Polygons, Points, Balloons (callouts). You can even add 3D objects and use customized Balloons
    • Download offline map packages for a country, or smaller region

    Xamarin Forms Apps

    Xamarin Forms (version 3.3.0 and higher) support Native Controls. If you add Mobile SDK apps for iOS and Android platforms, Xamarin Native Controls is available by default. See the blog Embedding Native Controls into Xamarin.Forms for details.

    While you can share most of code using Native Controls, you just need to specify the platform when creating the project:

    #if __IOS__
     // 1. iOS specific code
                var mapView = new Carto.Ui.MapView();
                mapView.Frame = new CGRect(20, 20, 280, 80);
                stack.Children.Add(mapView);
    #endif
     // 2. Indicate the common code from both platforms
        var baseLayer = new Carto.Layers.CartoOnlineVectorTileLayer("nutiteq.osm");
         mapView.Layers.Add(baseLayer);
    

    Note: Native Controls only work if you create or update Form in the code, using the xml definition will not work. This Xamrin development requirement is subject to change with each release. Mobile SDK with Xamarin Forms is currently in being tested with Native apps. Please contact us if you have an issues.

    Xamarin Android App

    Follow these steps to add native apps to your Xamarin Android package.

    1) Add the nuget package CartoMobileSDK to your mobile app project

    2) Add MapView to your application main layout

     
    <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="fill_parent"
        android:layout_height="fill_parent"
        android:orientation="vertical" >
       <carto.ui.MapView
        android:id="@+id/mapView"
        android:layout_width="fill_parent" 
        android:layout_height="fill_parent" 
        />
    </LinearLayout>

    3) Create MapView object, add a base layer

    Load layout from a xml, and load the MapView from Layout. Or, create it with code. A definition of a base layer is enough for minimal map configuration.

    using Carto.Ui;
    using Carto.Layers;
    using Carto.DataSources;
    
    [Activity (Label = "Carto.HelloMap", MainLauncher = true)]
    public class MainActivity : Activity
    {
    
      protected override void OnCreate ( Bundle bundle )
      {
        base.OnCreate ( bundle );
    
        // 1. Register license BEFORE creating MapView (done in SetContentView)
        MapView.registerLicense("YOUR_LICENSE_KEY", this);
    
        /// 2. Set our view from the "main" layout resource
        SetContentView ( Resource.Layout.Main );
      
        /// 3. Get our map from the layout resource 
        var mapView = FindViewById<MapView> ( Resource.Id.mapView );
    
        /// 4. Online vector base layer
        var baseLayer = new CartoOnlineVectorTileLayer("nutiteq.osm");
    
        /// 5. Set online base layer  
        mapView.Layers.Add(baseLayer);
      }

    Xamarin iOS App

    Follow these steps to add apps to your Xamarin iOS package.

    1) Uncompress CARTO Xamarin iOS SDK package to your project

    Note: All the .dll files should be located in the Assemblies folder

    2) Copy vector style file (osmbright.zip) to your project. You can get it from our Sample Apps. This is needed for vector basemap.

    3) Add Map object to app view. When using Storyboards, use OpenGL ES View Controller (GLKit.GLKViewController) as a template for the map and replace GLKView with MapView as the underlying view class. In the example below, it is assumed that the outlet name of the map view is Map.

    4) Initiate map, set base layer

    Add into MainViewController.cs:

    using Carto.Ui;
    using Carto.Layers;
    using Carto.DataSources;
    
    public class MainViewController : GLKit.GLKViewController
    {
      public override void ViewDidLoad ()
      {
        base.ViewDidLoad ();
    
        // GLKViewController-specific parameters for smoother animations
        ResumeOnDidBecomeActive = false;
        PreferredFramesPerSecond = 60;
    
        // Register license BEFORE creating MapView 
        MapView.RegisterLicense("YOUR_LICENSE_KEY");
    
        // Online vector base layer
        var baseLayer = new CartoOnlineVectorTileLayer("nutiteq.osm");
    
        // Set online base layer.
        // Note: assuming here that Map is an outlet added to the controller.
        Map.Layers.Add(baseLayer);
      }
    
      public override void ViewWillAppear(bool animated)
      {
        base.ViewWillAppear (animated);
    
        // GLKViewController-specific, do on-demand rendering instead of constant redrawing
        // This is VERY IMPORTANT as it stops battery drain when nothing changes on the screen!
        Paused = true;
      }

    Windows Phone Implementation

    If using Windows Phone as the mobile platform, follow this implementation procedure.

    Note: The Windows Phone 10 implementation of the Mobile SDK is experimental. Please contact us if you run into any issues.

    1. Install SDK VSIX package for Windows (*Request this package from CARTO Mobile support)

      The following requirements are mandatory:

      • Windows Phone version 10
      • MS Visual Studio 2013 Community edition, or better
      • Windows Phone 10 SDK, should come with Visual Studio
      • Visual Studio extension (VSIX) for CARTO Maps SDK component. Download and start the package to install it
    2. Register your app and select Windows Phone as the app type

      • Ensure you enter the same application ID as your Package.appmanifest > Packaging > Package name. For example, the sample app ID is c882d38a-5c09-4994-87f0-89875cdee539
    3. Create a cross-platform project for your Windows Phone app

      You can create one .Net project for Android, iOS, Windows Phone and share map-related code. Each platform still needs to be registered as its own app, since many app aspects (such as UI, file system, and so on) are platform-specific. However, when executing API requests with the Mobile SDK, you can create one project for adding layers and objects to map, handling interactions and click, and so on.

      Tip: .Net sample app contains two solutions: one for Windows Phone and another for Xamarin, and they share one project hellomap-shared with map-related code.

    Creating a WP App

    Follow these steps in order to create a Windows Phone (WP) mobile application.

    1) Ensure you have the CARTO Visual Studio Extension installed, and your app project has Internet connection

    In the Solution Explorer References section, add Carto Maps SDK for Windows Phone. You will find it from the Windows Phone 8.1 extensions. We do not have NuGet package yet, please let us know if this is something that interests you.

    2) Copy vector style file .zip to your project Assets folder, available from the Sample Apps. This is needed for vector basemaps

    3) Create MapView object, and add a base layer

    You can create a MapView object with code. A definition of a base layer is enough for the minimal map configuration.

    using Carto.Core;
    using Carto.Graphics;
    using Carto.DataSources;
    using Carto.Projections;
    using Carto.Layers;
    using Carto.Styles;
    using Carto.VectorElements;
    
    ...
    
    protected async override void OnLaunched(LaunchActivatedEventArgs e)
    {
      if (mapView == null)
      {
            // 1. Register CARTO app license
            var licenseOk = Carto.Ui.MapView.RegisterLicense("YOUR_LICENSE_KEY");
    
            // 2. Create map view and initialize
            mapView = new Carto.Ui.MapView();
    
            // 3. Online vector base layer
            var baseLayer = new CartoOnlineVectorTileLayer("osmbright-v3.zip");
    
            // 4. Set online base layer.
            // Note: assuming here that Map is an outlet added to the controller.
            mapView.Layers.Add(baseLayer);
            
      }
    
      // Place the page in the current window and ensure that it is active.
      Windows.UI.Xaml.Window.Current.Content = mapView;
      Windows.UI.Xaml.Window.Current.Activate();
    }
    
    private Carto.Ui.MapView mapView; 
    
    ...
    
    

    Adding a Marker (WP)

    To create a map marker at a defined coordinate on a Windows Phone mobile app, add following code (after creating a MapView.

    Note: You must have an Icon.png bitmap, located in the Assets folder of your project

    // 1. Create overlay layer for markers
    var proj = new EPSG3857();
    var dataSource = new LocalVectorDataSource(proj);
    var overlayLayer = new VectorLayer(dataSource);
    mapView.Layers.Add(overlayLayer);
    
    // 2. Create Marker style
    var markersStyleBuilder = new MarkerStyleBuilder();
    markersStyleBuilder.Size = 20;
    UnsignedCharVector iconBytes = AssetUtils.LoadBytes("Icon.png");
    var bitmap = new Bitmap(iconBytes, true);
    markersStyleBuilder.Bitmap = bitmap;
    
    // Example Marker for London
    var marker = new Marker(proj.FromWgs84(new MapPos(-0.8164, 51.2383)), markersStyleBuilder.BuildStyle());
    dataSource.Add(marker);
    
    

    Tip: See mobile-dotnet-samples sample project (solution: hellomap-winphone.sln) for other WP map actions, such as:

    • Control map view - set zoom, center, tilt etc.
    • Listen events (MapListener.cs) of clicks to map and map objects
    • Add other objects: Lines, Polygons, Points, Balloons (callouts). You can even add 3D objects and use customized Balloons.
    • Download offline map packages for country or smaller region

    Basic Map Features

    This section describes the basic map components that are required when creating mobile apps with the SDK. The following key objects are required for each mobile app:

    • MapView is the object which goes to your app view hierarchy. It provides methods for directly manipulating the map and its view. For example, you can set center location, zoom, and so on. MapViews contain objects for the map layers and map options

      • Layer (member of MapView) is an object that provides methods for adding data to the map

        • DataSource (member of Layers) is an object created as a member of the Layer object, which defines where the data comes from. There are specific DataSource implementations which keep data in memory, load from a persistent file or on-line API
      • Objects (member of MapView) is an object that provides methods for adjusting the map parameters

    Layers

    Map data is organized by Layers, which are needed for rendering your visualization. The usual approach is to add one TileLayer as a general background then add one or more interactive VectorLayers on top of the first layer. You can then include Markers, Texts, Popups and other map features on the top layer.

    DataSource

    For mobile maps, each map layer is required to have a DataSource, which defines where the layer retrieves data. Several common data source implementations are built directly into the Mobile SDK, but you can also define your own data sources using the following parameters.

    • HTTPRasterTileDataSource is used for retrieving map tiles as images over HTTP connection

    • LocalVectorDataSource stores data in memory and is used for adding vector objects to the map, per each user session

    Tip: For details about selecting different DataSources for your mobile map layers, see Loading Map Data.

    Basemap

    Basemaps apply the map background required for rendering data. Basemaps are required as the bottom layer. You can add a vector layer that contains the background of your mobile map by using the following code:

    MapView Objects

    In following examples, vector elements (Markers, Points, Lines, Polygons, Texts and BalloonPopups) are added to a mobile map application. For each object, the styling is defined and objects are created based on given coordinates. These coordinates are store in the memory-based vector data source parameter, LocalVectorDataSource.

    • Before adding any MapView objects, you must create a VectorLayer as the data source and add the layer to the map

    Note: A popup (callout, bubble) which appears when you click on map is a map object of its own, and should be added using object click listener. For details, see Add a BalloonPopup.

    Add a Marker

    Add a marker and apply marker styling using the following code:

    Example Marker on a Mobile Map

    pin

    Add a Point

    Points are used to indicating specific location points on a map, similar to Markers. However, Points do not have overlapping controls and cannot be use with billboard style version 2.5D. If you have a lot of data (thousands of points) and are not using 2.5D views, use Points as an alternative to Markers. Your rendering time will be significantly faster.

    You can add any type of vector objects to the same Layer and UnculledVectorDataSource. This enables you to reuse settings for a defined Marker. It is recommended to define different Layers and DataSources for managing your objects, as it allows you to:

    • Select and delete all objects of DataSource

    • Specify the drawing order of layers. The drawing order within a single Layer is undefined. For multiple layers, layers that are added are drawn underneath the initial map layer

    Add a point and apply point styling using the following code:

    Add a Line

    Lines can be added to the same VectorDataSource. Add a line and apply line styling using the following code:

    Example Line on a Mobile Map

    line

    Add a Polygon

    Add a polygon and apply polygon styling using the following code. The following examples add a polygon with polygon holes:

    Example Polygon on a Mobile App

    polygon

    Add Text

    Text style parameters are similar to Markers, as both are Billboards - which are MapView objects that contain the following features:

    • Control and prohibit text overlapping, based on priority and the location of where the text appears

    • Display text as billboards in 2.5D (tilted) view by defining the OrientationMode parameter. There are 3 options: show on ground, and rotate with map (like street names), show on ground (do not rotate with map), or show as billboard (no rotation).

    Add text and apply text styling using the following code.

    Example Text on a Mobile Map

    text

    Add a BalloonPopup

    A BalloonPopup appears based on click event of an object. You can also add a defined BalloonPopup. Add BalloonPops using the following code. Note that these examples contain several special styling elements, such as:

    • Image (info.png) as the “Left Image”
    • Arrow (arrow.png) as the “Right Image”
    • Styled appearance of tuned radius values

    Tip: To use these styling elements as part of your own project, copy the above .png files, (available from the Sample Apps), to your local map application project.

    Example BalloonPopup on a Mobile Map

    popup

    Add 3D Model Objects

    One special feature of the Mobile SDK is that you can add 3D objects (models) to a mobile map. For example, you can add small moving car or other decorative or informative elements.

    Note: 3D objects are added to the same LocalVectorDataSource as 2D objects. However, 3D objects are only supported using the Nutiteq Markup Language (NML) format, as it was created by our mobile partner, Nutiteq. This custom format is optimized for the multi-resolution of 3D files on mobile apps. For details about tuning the performance of 3D models, see LocalVectorDataSource Performance.

    The following procedure describes how to setup and add a 3D object to your mobile MapView:

    1. Select a NML file

      Tip: You can retrieve some free samples from Nutiteq’s NHL sample page.

      If you have own model as Collada DAE (or KMZ) format, then you would need CARTO Mobile 3D converter tools to convert it to NML, so it can be used in mobile. Please contact us for more information.

    2. Adjust the file size of the 3D object for rendering

      Note: Typically, NML files are smaller than 100K. Anything larger than that takes too long to render. Consider applying lower detail models for your 3D objects. You can then add these models to the res/raw folder of your Android app, or as a resource file in your iOS project.

    3. Load the model file in the code to add it to your map application by using the following code:

    Example 3D Model Object on a Mobile Map

    3d animated

    LocalVectorDataSource Performance

    You can define the spatialIndexType of the LocalVectorDataSource to improve the performance of how a 3D model loads, by defining a spatial index to the DataSource. By default, no spatial index is defined. The following rules apply:

    • Do not define a spatial index if the number of elements is small, below ~1000 points or markers (or even less if you have complex lines and polygons). This is the default option

    • Apply NT_LOCAL_SPATIAL_INDEX_TYPE_KDTREE as the index type if there are a larger number of elements

    The advantage of defining a spatial index is that CPU usage decreases for large number of objects, improving the map performance of panning and zooming. However, displaying overlays may slightly delay the map response, as the spatial index is not loaded immediately when your move the map, it only moves after some hundred milliseconds.

    The overall maximum number of objects on map is limited to the RAM available for the app. Systems define several hundred MB for iOS apps, and closer to tens of MB for Android apps, but it depends on the device and app settings (as well as the density of the data). It is recommended to test your app with the targeted mobile platform and full dataset for the actual performance.

    The following code describes how to adjust the LocalVectorDataSource performance by defining a spatial index:



    Note: If you have very complex lines or polygons, this creates objects with high numbers (more than hundreds of points per object) of vertexes. For example, the GPS traces for long periods of time, recording a point every second or so.

    Spatial indexing will not help in this case, as you need to show the whole track on the screen. In this case, apply the automatic line simplification parameter for the LocalVectorDataSource. This reduces the number of polygon and line points, while maintaining the original object shape.

    Tip: Automatic simplification is zoom-dependent. When a map is zoomed out, more aggressive simplification is used. When you zoom in, less simplification is applied until you see the original details.

    There are several ways to simplify geometries for automatic simplification by using the following code. Note that simplification is applied in two passes:

    • First pass applies fast Radial Distance vertex rejection
    • Second pass applies Ramer-Douglas-Peuckerworst algorithm (with the worst case quadratic complexity)

    All this is can be applied with just one line of code - as shown in the following example (under iOS) for minimal 1-pixel simplification, the result is invisible but effects are significant, depending on your DataSource:

    The automatic simplification renders a GPU tasks faster with some additional computation (CPU). For aggressive simplification, you will notice a decrease in the of line quality, so use is sparingly.

    Sample Apps

    Once you have installed the mobile dependencies and have installed the required libraries, the following sample mobile applications can be used to test apps on multiple mobile platforms. Some of these samples include some useful style files that you can use with your Mobile SDK projects.

    Android Samples

    iOS Samples

    Xamarin and Windows Phone Samples