Apple introduced the Swift programming language in 2014. It has now largely replaced Objective C to become the language of choice for iOS applications. However, CartoType's iOS API is written in Objective C. This article explains how to use the CartoType iOS SDK in a Swift project. You can use CartoType completely from Swift. There is no need to write any Objective C.
There are several platform SDKS. This page tells you what languages they support and the files they consist of.
Documentation for the current CartoType version
C++ API for Windows, Linux, mac OS, Qt and other platforms supporting C++ development
.NET API for C#, VB.NET and other .NET languages
Swift and Objective C API for iOS and mac OS
UWP API for C#, VB.NET and C++
Documentation for the last major version: CartoType 7.8
The documentation for this older version is supplied because of the major changes between CartoType 7.8 and CartoType 8.0. Many public identifiers (classes, functions, properties and data members) were renamed and the integer attribute of map objects was replaced by the new feature info class.
CartoType 7.8 C++ API for Windows, Linux, mac OS, Qt and other platforms supporting C++ development
CartoType 7.8 Java API for Android
CartoType 7.8 .NET API for C#, Visual Basic and other .NET languages
CartoType 7.8 Swift and Objective C API for iOS and mac OS
CartoType uses XML style sheets to control the appearance of maps. Features that can be controlled include the following:
- selection of layers
- colors
- transparency
- size of features
- SVG icons
- lettering style and positioning
- scales at which features appear
Style Sheets Directory
You can create CartoType maps (CTM1 files) from OpenStreetMap data, ESRI shapefiles, SRTM elevation data and other sources using the makemap tool.
fast offline routing
The standard routing system, suitable for any maps on desktop platforms and servers, and city maps on mobile devices, is flexible and fast.
route profiles
Route profiles tell CartoType how fast you expect to travel on different types of road, and also allow you to add weightings to indicate your preference. The free Maps app, available for Windows, Mac OS X and Linux, provides an easy way to try out different route profiles. You can choose from four standard profiles, and an editable custom profile, using the Route menu (first image below). The command 'Edit Custom Route Profile...' brings up the Route Profile Editor dialog (second image below).
CartoType can show terrain on a map in various different ways:
height coloring: using different colors for different heights. Colors can be blended or drawn as distinct steps. All this is controlled using a height ramp in the style sheet.
We supply a full Android Java API for CartoType which provides the same functionality as the C++ API. It contains the CartoType Java SDK as an AAR file that you can add to your project as a module (download an evaluation version).
You can also download a sample CartoType Android project, which contains the source code and project files for the CartoType Maps App, a program that displays a map using hardware graphics acceleration and allows user interaction including panning, pinch zooming, and rotation. It's provided as an Android Studio project, and also includes routing using different profiles, turn by turn navigation, finding placenames and addresses, night mode, and perspective mode. Everything's reasonably obvious except for setting the start or end of a route. To do that, use a long press on the position, then choose 'SET START OF ROUTE' or 'SET END OF ROUTE' from the alert that appears. The demo is ready to run. Just download the code or use git to clone the repository (git clone https://github.com/CartoType/CartoType-Public.git). Then load the project src/demo/android_demo/CartoTypeMaps into Android Studio, connect an Android device or simulator, and select Run 'app' from the Run menu.
Use the free Android Studio IDE for developing Android applications.
The CartoType Maps App on Android as an APK
If you'd like to try CartoType on Android without building an app, try the CartoType Maps App for Android (235Mb download). It's a pre-built version of the sample project, supplied as an APK file for you to install on your Android phone or tablet, with a map of London and the surrounding area. You can load other maps into it if you like.
By clicking on any of the links on this page or elsewhere on this web site, or by using the SDK material or demonstration programs, or source code, however acquired, you accept the terms of the CartoType Evaluation License and you also accept that neither CartoType Ltd, nor any owners, shareholders or officers of CartoType Ltd, or any other contributors to, authors of or maintainers of the CartoType system, are liable for any damage, direct or consequential, caused by downloading, installing or using the SDK, or by any programs built using the SDK, and that the SDK is not warranted fit for any particular use and is for evaluation use only and may not be used for any commercial purpose.
The iOS SDK for CartoType allows you to use Swift or Objective C to create applications using CartoType.
A Swift-based sample CartoType project
The iOS sample project includes source code, project files, and data files including a map, style sheet and fonts. This Xcode project allows you to build a full-featured app with fast hardware-accelerated rendering, handling of user gestures for panning, zooming and rotation, routing using different profiles, turn by turn navigation, finding placenames and addresses, night mode, and perspective mode. You can set the start or end of a route using a long press. Other features are available from toolbar buttons.
To build and run the app, open the project in Xcode on a Macintosh and add the CartoType iOS SDK to it. If you are a licensee you can use your licensed CartoType SDK instead of the evaluation version; change the call to the license() function in AppDelegate.swift so that it supplies your license key. You will need to sign the app using your Apple developer certificate.
You can then run it in the simulator or on an iOS device.
Basics
The CartoType core library is written in C++. To use it to draw maps you need to create various class objects. All CartoType functionality is accessed by calling member functions of those objects.
C++ programming conventions
Names
In the CartoType C++ API, nearly all public identifiers use Pascal Case, which means that each word of a compound name starts with a capital letter. Examples: Framework, BitmapView (classes), Rotation, DisplayRoute (functions), X, Y (data members). Everything is in the CartoType namespace, which you can use either by putting the 'CartoType::' qualifier before the names, or putting 'using namespace CartoType;' at the start of your source files.
Expressions are used in import rules and style sheets.
Use in style sheets
They are used in <if> and <condition> elements. You write them using the exp attribute. For example:
<if exp='scale > 50000'> <condition exp='$="Italy"'>
You can use the following special variables in style sheet expressions:
$ = the object's label
- @ = map object type: 0=point, 1=line, 2=polygon, 3=array (texture)
- @type is the same as @
- @layer = style sheet layer the object belongs to
- @id = the object's ID within the CTM1 file; equal to its byte offset in the file
- @feature_type, @feature_type_name, @sub_type, @level, @speed_limit, @bridge, @tunnel, @one_way, @one_way_forward, @one_way_backward, @drive_on_left, @roundabout, @toll, @gradient, @private, @pedestrian_access, @cycle_access, @motor_vehicle_access, @emergency_vehicle_access, @other_access and @wrong_way give access to the feature info attributes.
For example:
<condition exp='@feature_type== "cit"'>
Building CartoType for Linux
CartoType is written in standard C++ and will compile using CLANG and GCC. Its output is a bitmap in memory, which you can display on any device if you know how your proposed device handles bitmaps. The license allows you to distribute it as part of a binary package, not as source for on-platform compilation. Linux users tend to expect binary packages, so this should not be a problem.
To obtain a Linux library you can simply take the source code, which is supplied to Cartotype licensees, and compile it (using a script provided as part of the CartoType distribution) on the target you need. If you need the library pre-compiled for any reason please
Using the FreeBSD operating system, a version of Unix, you can create larger CTM1 files than is usually possible under Windows, depending on how much RAM you have.
Installing FreeBSD
Basic Installation
It's assumed you know how to install an operating system, so this part will be brief. You can download the latest version of FreeBSD from freebsd.org, burn it on a CD and boot from it. Make sure you download the AMD64 version, not the Intel386 as the latter is only 32-bit. The AMD64 instruction set appeared before Intel's own 64-bit processors so the 64-bit version is named for them (which must annoy Intel).
Different versions of FreeBSD ask different install questions but you can leave it to the default options selected most of the time.
Note the type of License Licensee has agreed to will determine the number of Integrated Products in which the Licensed Software can be used and the duration of the License; see clause 2.4
In this License "You" means the individual who has downloaded the Software and/or the organisation he or she represents ("Your" and "Yours" shall be construed accordingly); "Software" means the software downloaded by You from Our website and for which you have not entered into a full SDK License with Us; and "We" are CartoType Limited. (Registered Number 7021509), registered office: at Park House, Brampton Bryan, SY7 0DH, U.K. ("Us" and "Our" shall be construed accordingly). Other defined terms are set out below.
You can display a list of places on the map as the user enters the name, using CartoType's incremental searching support.
Create a full-text index
The first step is to create your CTM1 (map data) file using the makemap command-line option /textindex=full. That way, all phrases within text attributes are indexed, as well as the whole string.
Searching as the user types
Here's what you need to do in your find dialog.
CartoType has functions to find addresses and perform geocoding, which is converting a position to an address. You can try out these functions using the Windows demo. Use the 'Find address' menu item in the 'Find' menu to find an address. You can fill in any of the fields. Just leave fields blank if they are not needed or the information is unknown. Searching is faster if you provide the city, state, county, or province when searching for a street address.
MapPoint has gone. Why not use CartoType instead?
According to Microsoft, "MapPoint will no longer be sold after December 31, 2014. Technical support will be available until July 14, 2015."
The makemap tool uses rules written in a small XML-based language to control the import of data from OSM and other sources. The idea is that an input data set is supplied containing a set of attributes and values (a row in the map database), and a program made up from a series of statements uses it to create one or more output map objects.
makemap uses a standard set of rules. You can write them out using makemap (see makemap's usage message for details) and edit them to create your own rules.
Thus a single input data set (database row) can create more than one map object, but the converse is not true.
The program is executed in its entirety once for each input data set.