We supply a full Android Java API for CartoType which provides the same functionality as the C++ API. It contains the CartoType Java API as a .jar file called cartotype.jar, and four versions (debug and release for both ARM and x86 platforms) of the CartoType shared library, libcartotype.so. You can also download sample CartoType Java source code, which contains the source code and project files for a simple demonstration program that draws a map using hardware graphics acceleration and allows user interaction including panning, pinch zooming, and rotation.
Use the free Android Studio IDE for developing Android applications.
Your app will need to use the cartotype.jar and libcartotype.so libraries....
The usual way to develop apps for iOS, the operating system used on Apple's iPhone and iPad devices, is by means of XCode, a free development environment which runs on Mac OS. We provide an iOS framework for CartoType. It allows you to use both Swift and Objective C to create CartoType apps.
A simple test app
You can download the source code of a simple test app which uses the CartoType evaluation library.
Open the project in Xcode on a Macintosh.
Add the CartoType evaluation framework to the project.
You can then run it in the simulator or on an iOS device. The CartoType evaluation library is built for, and works on, both the 32-bit (Arm7) and 64-bit (Arm64) iOS environments.
The code is largely self-explanatory. It loads and displays a map, and allows the user to pan, zoom and rotate the map using gestures. You can create a route by clicking successively on two points It is designed as a minimal app, and therefore is deliberately very simple....
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
CartoType class names nearly all start with C or T. C stands for 'class' or 'complicated' and is for large classes which allocate memory on the heap, and which are usually created on the heap. T stands for 'type' and is for smaller, simpler classes which are usually created on the stack. Examples: CEngine, TResult....
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 special variables Type, OsmType and RoadType in style sheet expressions. Type is the integer type, OsmType is the same as (Type bitand #FFFE0000), and RoadType is the same as (Type bitand #FC0). For example,
<condition exp='OsmType == "cit"'><condition exp='OsmType == "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.
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.
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.
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....
Structure of a CartoType style sheet
<?xml version="1.0" encoding="UTF-8"?> <CartoTypeStyleSheet name="mystylesheet" background="ivory" labelAttrib="name:en"> <defs> ... </defs> <layer name="park"> ... </layer> <layer name="river"> ... </layer> <layer name="road"> ... </layer> <layer name="other-layer"> ... </layer> ... <labelLayer/> </CartoTypeStyleSheet>...
Style sheet macros and variables
Style sheets can get very big. Two ways to save space are described here.
Macros are predefined pieces of the style sheet which can be referenced by name. You define macros in the <defs> section like this:
<defs> <macro id='minor-road-label'> <label font-size='75%,8pt' glow='white' color='black' case='assume-title' maxScale='20000'/> </macro> <macro id='standard-tunnel'> <tunnel dashArray='1,1' fade='0.3' mouth='dimgrey' mouthWidth='20%,1' mouthPath='m 0 512 a 512 512 0 1 1 0 -1024'/> </macro> </defs>...
It is often necessary to enable or disable parts of a style sheet, or make them dependent on run-time parameters. While it's possible to solve the problem using several different style sheets, it is much easier to put everything into one style sheet and select different features at run-time using conditional compilation controlled by parameters set by the application.
You can select any part of a style sheet (that is, any balanced XML) using
<if exp="expression"> ... </if>...
Dimensions are specified using numbers followed by optional units. A number without a unit refers to pixels. Sometimes units are not allowed, as for example in opacity levels, which are dimensionless. Where units are allowed, you can use any of the following:
- pt: printer's points of exactly 1/72in (sometimes called PostScript points).
- pc: printer's picas of 12pt.
- cm: centimeters.
- mm: millimeters.
- in: inches.
- m: map meters; that is, meters at the scale of the map, converted to pixels using the current map projection.
- %: a percentage of some value depending on context; for example, in the context of a road, percentages refer to the width of the road, allowing you to specify that a road name is 75% of the width of the road.
Dimensions can optionally be followed by limits: minimum and maximum values. For example, it is useful to specify a label size in map meters, but clamp it to a certain range of sizes, avoiding lettering that is too small to read, or so large as to be ugly and obtrusive. For example:
sets a label size to 300 map meters but clamps it to the range 8pt...24pt. It is legal to omit the third (upper) limit, as in:
Colors are RGBA (red, green and blue components plus an 'alpha' or opacity level), and can be specified in these ways:
- Hexadecimal 24-bit RGB, in the form #RRGGBB, where each group of two hex digits is an 8-bit intensity value. An opacity value of 255 (fully opaque) is used.
- Hexadecial 24-bit RGB using three digits only: #RGB; the digits are treated as #RRGGBB
- Hexadecimal 32-bit RGBA, in the form #RRGGBBAA, where the first three groups of two hex digits are the red, green and blue intensity levels and the last (AA) is the alpha or opacity value, where 0 = transparent and 255 = opaque.
- Hexadecimal 32-bit RGBA using four digits only: #RGBA; the digits are treated as #RRGGBBAA
- As an SVG color keyword. SVG (the W3 Scalable Vector Graphics standard) defines over a hundred keywords for colors, including all the common names and many unusual ones like 'khaki' and 'teal'.