MapEventListener contains special functionality that shows, or hides, a small label text over a clicked object. The following label click event rules apply:
If you click on an object, it creates another map object as a BalloonPopup. This contains the text from the metadata of the clicked object
For this reason, our samples apps include a Metadata field value. You can use the metadata value directly, or use the object unique ID as the metadata, to query details about the clicked object from the database.
When a viewer clicks a new location on the map (or click another map object), the original BalloonPopup is deleted, and new one appears at the click location
The BalloonPopup is added to the DataSource, which is linked existing map layers. The same DataSource is used for other vector elements on a map
When you have too many Points of Interest (POIs) that cannot be displayed as individual markers, it results in a cluttered map. It also effects the rendering performance of your map, and may even result in running out of memory. As an alternative, replace individual objects with clusters.
Clusters are markers which display a location of several objects, and typically indicate the number of markers within each object.
CARTO Mobile SDK has built-in cluster feature, which is highly customizable. You can define the following options in your app code:
Styling the cluster objects
Dynamically generate cluster object styles. For example, automatically display the number of objects in each cluster
Define the minimum zoom level for clusters
Set the minimum distance between objects, before it becomes a cluster
Indicate the action when clicking on marker. For example, zoom in, or expand the cluster without zooming
Tip: The cluster expand feature is useful for small clusters (containing up to four objects inside)
API Methods for Clusters
Clusters are generated dynamically, based on VectorDataSource data that loads the map layer. If using an API, it works as a unique layer with the ClusteredVectorLayer method, and includes the following parameters in the a hierarchal order:
Select the layer DataSource
In most cases, the LocalVectorDataSource function contains all the elements to request the data. It is important that the DataSource displays all elements in a layer, and does not limit it to the current map visualization bbox (bounding box)
ClusterElementBuilder defines a single method buildClusterElement
The Cluster Element Builder takes set of original markers (map objects) as input, and returns one object (or another VectorElement, such as a Point or BalloonPopup) which dynamically replaces the original marker.
Note: It is highly recommended to reuse and cache styles to reduce memory usage. For example, a marker style with a specific number is only created once. Android and iOS samples use platform-specific graphic APIs to generate the bitmap for the marker. .NET example only uses BalloonPopup, which is slower but works the same across all platforms.
Ground overlays projects a bitmap (PNG, JPG) image of a defined coordinate over a basemap. For example, a ground overlay bitmap may be used to show an indoor floorplan over a building map.
Note: Your bitmap must define geographical map coordinates with Ground Control Points. Currently, Mobile SDK supports three or four points on a bitmap image.
Ground Overlay Requirements
The following requirements allow you to ground overlays with the Mobile SDK.
linear affine transformation enables you to set three control points to set the location, size, and rotation of the bitmap
perspective transformation enables you to control four control points for the bitmap
If you have more control points in your data, it is suggested to choose three or four of your best ones, and select those as your ground control settings
Control points must be defined in the app code. Mobile SDK does not automatically gather control points from the source file metadata
For example, if you need GeoTIFF, ESRI World File, MapInfo TAB, Geospatial PDF, or other referenced data, you will get this from the GIS Extension (see below).
The entire bitmap must fit to device memory (RAM). Depending on the target device, the maximum size could vary. For example, the target device maximum size might be 2000x2000 pixels.
Tip: For larger rasters, the SDK Extensions allow you to display any size bitmap, up to hundreds of megabytes. These bitmaps are read directly from common GIS raster formats (such as GeoTIFF, BSB, ECW, MrSID, JPEG2000, and so on). Additionally, the source data can be entered using different coordinate systems. Please contact us if you are interested in enabling SDK Extensions as part of your account.
This example uses only one geographical coordinate. The building size is known, and the building direction is facing north. This allows us to calculate other ground points with the code. Four ground control points are set to the corners of the bitmap, which typically returns the most accurate result.
Tip: The following sample code assumes that you have the jefferson-building-ground-floor.jpg bitmap file as part of your application project.
For Android, this image is located under assets
In iOS, it can be located anywhere in your project
When you create a basemap, the Mobile SDK package enables you to select one of our pre-defined, built-in basemap styles:
CARTO_BASEMAP_STYLE_VOYAGER - Light style, used as a general map where you need to distinguish forests, rivers, streets etc.
CARTO_BASEMAP_STYLE_DARKMATTER - Dark style, best when displaying light-styled data
CARTO_BASEMAP_STYLE_POSITRON - Gray style, used when displaying dark-styled data
You can customize basemap styling by setting the colors, transparency, line styles (width, patterns, casings, endings), polygon patterns, icons, text placements, fonts, and other vector data parameters.
CARTO uses Mapnik XML style description language for customizing the visual style of vector tiles. Our styling is optimized for mobile and contain some unique style parameters. In general, you can reuse your existing Mapnik XML, or CartoCSS, styling files and tools (such as TileMill/Mapbox Studio).
Vector styling is applied in the mobile client, where the style files are bundled with the application installer. The application can change the styling anytime, without reloading vector map data. This enables you to download map data once, and change styling from “day mode” to “night mode” with no new downloads.
CARTO map rendering implementation is intended for real-time rendering. As a result, several limitations apply.
Mapnik Style Format
Mapnik style definitions are a common file format for map styles, based on XML. It was originally created for Mapnik, but is used by other software, such as our Mobile SDK. The file format specifications are located in this XMLConfigReference document. There are several ways you can apply these styles:
Use CARTO provided styles
Modify the style.xml, located inside the sample style, with your own edits
Create your own styles using a Mapnik editor tool
Note: It is recommended to use the free MapBox Studio tool, which uses CartoCSS for primary style definitions. While the Mobile SDK does not use CartoCSS styles, you can modify and export Mapnik XML styles to be compatible with the Mobile SDK.
Please note the following limitations with Mapnik style formats.
There are no built-in fonts, fonts must be explicitly added to the project
Loading SVG icons is not supported, such icons should be converted to PNG format (Mapnik provides a svg2png utility)
Original layer ordering is not always preserved, texts are always drawn on top of 2D geometry. 3D buildings are drawn on top of texts
Layer opacity works per element, not per layer as in Mapnik. For non-overlapping elements, the result will be same. For overlapping elements, there are likely artifacts
comp-op feature is not supported (neither is layer/symbolizer)
line-join parameter is ignored, only miter line join is used
GroupSymbolizer and RasterSymbolizer are currently not supported
Text characters are rendered individually. If characters overlap, the halo of one character may cover glyph of another character. The suggested workaround is to increase spacing, or decrease the halo radius
Note: The Mobile SDK does not implement 100% of the tags and features of Mapnik. This lists just a few of the Mapnik limitations, there are additional Mapnik XML features that are not standard. If you need some an unimplemented styling option, please contact us.
Creating Vector Style Packages
CARTO vector styles are distributed as zip-archives. All style-related files and folders must be placed into a single zip file.
The most important part of the style is the style definition file, typically named project.xml. This file contains style descriptions for all layers, and usually references other files, such as fonts, icons, and pattern bitmaps (which should be placed in various subfolders).
Vector Style Performance
When using vector styles, the following recommendations are suggested for optimal performance:
Multiple symbolizers per layer may have very large performance hits. If possible, move each symbolizer into separate layer
BuildingSymbolizer requires an expensive OpenGL frame buffer read-back operation, and may perform very poorly on some devices (such as the original iPad Retina)
To increase performance, it is suggested to use power-of-two dimensions for bitmaps
SDK Extensions for Mapnik XML style files
The following CARTO specific extensions are specific to Mapnik XML style files.
NutiParameters describe additional parameters that can be used in styles and controlled in the code (from MBVectorTileDecoder).
Parameters are typed, have default values and can be used as variables within nuti namespace in the style (for example, [nuti::lang])
Some parameters may have _ prefix in their name. Such variables are reserved and should not be updated directly by the application
The following is a simple example of NutiParameters section, located in the style xml file:
Metavariables add support for dynamic variable look-up. Variable names may depend on other variables. For example, [name_[nuti::lang]].
If the value of nuti::lang is ‘en’, this metavariable expression would be equal to [name_en] expression.
Conditional operator ?: adds support for simple control flow management. It is similar to C language conditional operator and can be used in all expressions. For example:
[nuti::lang] == 'en' ? 'English' : 'Other'
3D Texts and Markers
Mapnik MarkersSymbolizer and TextSymbolizer support additional values nutibillboard for placement parameter. This enables texts and markers to act as billboards (always facing the viewer), even when screen is tilted. This option can be used to give markers and texts more ‘3D-like’ appearance. For example,