Creating custom basemap styles

About

CARTO Mobile SDK includes 3 built-in styles (Voyager, Positron and Darkmatter) that should cover common needs. If a custom style is needed, then there are two general approaches: modify or tweak an existing basemap style or create a new style from scratch.

Modifying an existing style is the recommended option, as creating a new style is much more difficult than it may seem:

• Cartographic decisions require experience and lots of trial and error as the style has to work with highly variant map data
• Style rendering performance may require internal knowledge of the OpenGL rendering engine inside the SDK

Modifying a built-in style

The following instructions can get you started:

• Start by studying built-in basemap styles. Simply get the latest built-in style asset from the SDK from here and unpack it.
• The style archive contains all 3 built-in styles and related assets (images and fonts). Each style has associated .json file that contains layer order, references to CartoCSS files and so on. The specification for the .json file can be found here.
• Use the closest style as a base, remove other .json files and other assets not used by the style.
• Simple modifications like changing a color, street line width or a font can be done by modifying CartoCSS variables. For example, water color is specified using @water variable.
• Once the changes are completed, you can create a new style asset by zipping the files together with subfolders.

Creating a new style from scratch

The recommended way to build a new style from scratch is to use Mapbox Studio Classic for style editing. Sample projects using OpenMapTiles (the tile source SDK uses) can be found here. Sample styles usually need some cleanup, as there are some differences in CartoCSS interpretation between Mapnik and CARTO Mobile SDK. Also note that Mobile SDK contains several important CartoCSS extensions that are not available in Mapnik. These extensions allow for more compact styles are better user experience, but must be applied AFTER the style is finalized in Mapbox Studio Classic.

Once the style is finalized, the following steps are needed to create a working style asset:

• Create a style.json file. A recommended way is to use an existing .json file from built-in styles are described in the previous section as a base.
• Copy all fonts, images to your project folder and check that all url directives in CartoCSS files refer properly to the local files.
• Be sure to remove 'project.xml' file, this is a compiled Mapnik style and may interfere with the CartoCSS description.
• Create the style asset by zipping the files together with subfolders.

Using the custom style

The following Java snippet can be used to create a layer with the custom style:

BinaryData styleAsset = AssetUtils.loadAsset("<CUSTOM_STYLE_ASSET_NAME>");
ZippedAssetPackage assetPackage = new ZippedAssetPackage(styleAsset);
CompiledStyleSet styleSet = new CompiledStyleSet(assetPackage);
MBVectorTileDecoder tileDecoder = new MBVectorTileDecoder(styleSet);

CartoOnlineTileDataSource dataSource = new CartoLineTileDataSource("carto.streets");

VectorTileLayer baseLayer = new VectorTileLayer(dataSource, tileDecoder);

The same snippet for Objective C:

NTBinaryData* styleAsset = [NTAssetUtils loadAsset: @"<CUSTOM_STYLE_ASSET_NAME>"];
NTZippedAssetPackage* assetPackage = [[NTZippedAssetPackage alloc] initWithZipData: styleAsset];
NTCompiledStyleSet* styleSet = [[NTCompiledStyleSet alloc] initWithAssetPackage: assetPackage];
NTMBVectorTileDecoder* tileDecoder = [[NTMBVectorTileDecoder alloc] initWithCompiledStyleSet: styleSet];

NTCartoOnlineTileDataSource* dataSource = [[NTCartoLineTileDataSource alloc] initWithSource: @"carto.streets"];

NTVectorTileLayer* baseLayer = [[NTVectorTileLayer alloc] initWithDataSource: dataSource decoder: tileDecoder];