Repeated symbols and start and end symbols on lines

You can draw repeated symbols along any linear feature. For example, national frontiers are sometimes emphasized using small crosses, and cross-ties can be drawn along railway lines. The syntax is exactly the same as for the oneWayArrow attribute on roads, except that you use repeatedSymbol instead of oneWayArrow. You cannot use both oneWayArrow and repeatedSymbol for a road.

This feature can be used to place arrows along route lines overlaid on the map by means of of an auxiliary map database.

Using SVG for repeated symbols

You can use SVG to define repeated symbols in exactly the same way as for one-way arrows.

Start and end symbols

Symbols can also be specified for the starts and ends of lines. The startSymbol and endSymbol elements work in the same way as oneWayArrow and repeatedSymbol and allow you to create graphics that is drawn at the start or end of a line only. This can be used for arrow-heads, transverse ticks, and the like.


Dashed, truncated and extended lines

Dashed lines are specified using a syntax similar to that of SVG. Use the attribute dashArray in the <line> or <shape> tag. The value is a comma-separated list of dash and gap sizes, relative to the line width (e.g., the value 2 means a dash or gap twice as long as the line width).

The railway line below is drawn as a dashed line with a border, using this code in the style sheet:

<layer name='railway'>
<line width='12m,2pt' border='grey' borderWidth='10%,0.7,2' fill='white' dashArray='5,5'/>
<label font-size='75%,8pt' glow='white' color='black' case='assume-title'/>

White dashes are drawn over a grey border; when there are dashes, the border is also the colour between the dashes.

dashed railway

Truncating and extending lines

Sometimes lines need to be truncated at the start or end or both. For example, a line indicating an airway may need to be shortened so that it doesn't interfere with symbols for navigation aids or position fixes. You can use the truncationAtStart and truncationAtEnd attributes inside <line> or <highlight> elements to shorten lines. All the normal map-related or display-related dimensions can be used, and you can also use percentages, which refer to the width of the line.

Negative values have the effect of extending lines. This can be used to join disconnected sections of highlights drawn along lines (for example, to show traffic density on roads).


Map objects in a single layer often have different attributes. For instance, roads have a RoadType attribute giving the importance of the road, whether it is one-way, whether it has a central divider, etc. These attributes affect the way the road is drawn.

You use <condition> sections inside <layer> to treat objects with differing attributes in different ways. Each <condition> section is like an embedded <layer> section for only those objects with the specified attributes.

A <condition> section inherits all attributes defined in the containing <layer>, unless it is nested inside another condition, in which case it inherits from the containing condition. Conditions may be nested up to 15 levels deep.

You set the actual condition using a style sheet expression in the exp attribute. Expressions test integer and string attributes of map objects; if the expression is true, the object is drawn using the styles given inside the condition element

This is hard to understand without an example. Here is the road layer from a style sheet formerly used by the CartoType demo programs:

<layer name="road">
   <line width="30m" fill="orange" border="black" borderWidth="5%"/>
   <label font-size="75%,8pt"/>
   <condition exp="RoadType in [#400,#BFF]">
      <scale max="50000"/>
      <line width="18m" fill="yellow" border="black" borderWidth="5%"/>
      <label font-size="75%,8pt" maxScale="15000"/>
      <oneWayArrow path="M 0 50 H 300 L 40 300 H 180 L 505 0 L 180 -300 H 40 L 300 -50 H 0 Z" fill="teal" opacity="0.5"/>
   <condition exp="(RoadType bitand #FF00)==#300">
      <scale max="100000"/>
      <line width="22m,2pt" fill="orange" border="black" borderWidth="5%" centerLine="white" centerLineWidth="5%"/>
      <label font-size="75%,9pt"/>
      <oneWayArrow path="M 0 50 H 300 L 40 300 H 180 L 505 0 L 180 -300 H 40 L 300 -50 H 0 Z" fill="teal" opacity="0.5"/>
   <condition exp="(RoadType bitand #FF00)==#200">
      <line width="30m,2pt" fill="tomato" border="black" borderWidth="5%" centerLine="pink" centerLineWidth="5%"/>
      <label font-size="75%,10pt"/>
      <oneWayArrow path="M 0 50 H 300 L 40 300 H 180 L 505 0 L 180 -300 H 40 L 300 -50 H 0 Z" fill="yellow" opacity="0.5"/>
   <condition test="(RoadType bitand #FF00)==#100">
      <line width="45m,2pt" fill="mediumturquoise" border="black" borderWidth="5%" centerLine="white" centerLineWidth="5%"/>
      <label font-size="75%,10pt"/>
      <oneWayArrow path="M 0 50 H 300 L 40 300 H 180 L 505 0 L 180 -300 H 40 L 300 -50 H 0 Z" fill="yellow" opacity="0.5"/>

The first condition has the test "RoadType in [#400,#BFF]", meaning that only roads with road types in the range 400 (hex) to BFF (hex) inclusive are drawn by the specifications in this condition. These are minor and unclassified roads, and are drawn by this style sheet in yellow and not drawn at smaller scales than 1:15000.

Here is an example showing the inheritance of attributes from the containing layer:

<layer name='waterway'>
<label font-style='italic' color='blue' case='assume-title' glow='white'/>
   <!-- RIVER -->
   <condition exp='(Type bitand #FFFF0000)=="riv"'>
   <line width='20m,1pt' fill='skyblue'/>
   <label font-size='75%,8pt' maxScale='1000000'/>
   <!-- CANAL -->
   <condition test='(Type bitand #FFFF0000)=="can"'>
   <line width='8m,1pt' fill='skyblue'/>
   <label font-size='75%,8pt' maxScale='1000000'/>
   <!-- STREAM -->
   <condition test='(Type bitand #FFFF0000)=="str"'>
   <line width='8m,1pt' fill='skyblue'/>
   <label font-size='75%,8pt' maxScale='250000'/>
   <!-- DRAIN -->
   <condition test='(Type bitand #FFFF0000)=="dra"'>
   <line width='4m,1pt' fill='skyblue'/>
   <label font-size='75%,8pt' maxScale='25000'/>

And here is an example of a nested condition:

<condition test='(RoadType bitand #F00)==#400'>
<scale max='400000'/>
<line width='25m,0.5pt' fill='ivory' border='black' borderWidth='8%,0.7,2'/>
<label font-size='70%,8pt' glow='white' color='black' case='assume-title' maxScale='20000'/>
<oneWayArrow path='#arrow' gap='2500' fill='teal' opacity='0.5' isLabel='yes'/>
<bridge width='38m,2pt' border='black' borderWidth='14%,1' endPath='l 512 512' maxScale='50000'/>
<tunnel dashArray='1,1' fill='grey' mouth='black' mouthWidth='20%,1' mouthPath='m 0 512 a 512 512 0 1 1 0 -1024'/>
   <!-- TERTIARY -->
   <condition test='(RoadType bitand #F80)==#400'>
   <line fill='khaki'/>

Here, tertiary roads are exactly the same as unclassified roads except for their fill color, so a lot of unnecessary repetition is avoided. But note that all the nested tests must succeed for this to work. In this example, the test '(RoadType bitand #F00)==#400' selects both unclassified and tertiary roads, while '(RoadType bitand #F80)==#400' selects tertiary only. When the map is drawn, objects are matched to the innermost test that succeeds.


Road types are as defined in the enumerated type CartoType::TRoadType:


enum TRoadType
/** The major road type is held in the high 8 bits. */
EMajorRoadTypeMask = 0xFF00,
/** The minor road type flags are held in the low 8 bits. */
EMinorRoadTypeMask = 0x00FF,
/** Roads of unknown type. */
EUnknownMajorRoadType = 0,
/** Primary road with limited access (motorway, freeway, etc.). */
EPrimaryLimitedAccessRoadType = 0x100,
/** Primary road without limited access: UK 'A' road. */
EPrimaryUnlimitedAccessRoadType = 0x200,
/** Secondary road: UK 'B' road. */
ESecondaryRoadType = 0x300,
/** Local road or town or city street. */
EMinorRoadType = 0x400,
/** Byway: road or track passable only by 4WD vehicles. */
EBywayRoadType = 0x500,
/** Access ramp to limited access road. */
EAccessRampType = 0x600,
/** Service road or access road. */
EServiceRoadType = 0x700,
/** Vehicular Ferry route. */
EVehicularFerryRoadType = 0x800,
/** Passenger-only Ferry route. */
EPassengerFerryRoadType = 0x900,
/** Path or walkway for pedestrians. */
EPathRoadType = 0xA00,
/** Stairway or escalator for pedestrians. */
EStairwayRoadType = 0xB00,
/** A bit flag for roads separated by a central divider. */
ESeparatedRoadTypeFlag = 1,
/** A bit flag for roads in a tunnel. */
ETunnelRoadTypeFlag = 2,
/** A bit flag for underpassing roads. */
EUnderpassRoadTypeFlag = 4,
/** A bit flag for roads with a central railway or tramway. */
ECentralRailLineRoadTypeFlag = 8,
/** A bit flag indicating that the road is one-way in the direction in which it is defined. */
EOneWayForwardRoadTypeFlag = 16,
/** A bit flag indicating that the road is one-way in the reverse direction to that in which it is defined. */
EOneWayBackwardRoadTypeFlag = 32,
/** A bit flag to allow access ramps (links) to be marked as sub-types of a major road type. */
ELinkRoadTypeFlag = 64,
A bit flag to allow a distinction to be made between grades of road, within the major road type.
It allows OpenStreetMap data to distinguish trunk roads from primary roads in a backward-compatible way.
ELowerGradeRoadTypeFlag = 128,


CTM1 map files created from US Census Dept. TIGER data use the attribute 'CFCC', which gives the feature type. CFCC stands for Census Feature Class Code.

The original CFCC codes are made from an uppercase letter followed by a two-digit number. The codes used in CartoType's CTM1 data format are entirely numeric. The uppercase letter is replaced by one or two digits, using the range 1...26 for the letters A...Z. Thus A08 (road with rail line in center) becomes 108, and X00 (feature not yet classified) becomes 2400.

For roads, CFCC codes are translated into CartoType road types, which are explained in the previous section.

There is a list of CFCC codes at (in Chapter 3).


CTM1 map files created from OpenStreetMap data (OSM files in XML format) use the attribute Type. This 32-bit value contains a value in its upper 15 bits that encodes a three-letter tag that is a mnemonic for one of the tags used in the OSM file. The encoding is done like this: for the purpose of explanation here is a C macro that takes three lower-case letters:

 #define OsmType(A,B,C) ((((A)-'a') << 27) | (((B)-'a') << 22) | (((C)-'a') << 17)) 

However, you don't have to work with the actual numeric values because you can use the three-letter tag on the right hand side of a test in a condition.

Here are the OpenStreetMap types that are currently defined and used by generate_map_data_type1.

EAbandoned = OsmType('a','b','a'),
EAerodrome = OsmType('a','e','r'),
EAirfield = OsmType('a','i','r'),
EAirportGate = OsmType('a','g','t'),
EAirportHoldingPosition = OsmType('a','h','p'),
EAllotments = OsmType('a','l','l'),
EAlpineHut = OsmType('a','l','p'),
EAmbulanceStation = OsmType('a','m','b'),
EApron = OsmType('a','p','r'),
EAerialWayPylon = OsmType('a','p','y'),
EArtwork = OsmType('a','r','t'),
EAerialWayStation = OsmType('a','s','t'),
EAirTerminal = OsmType('a','t','e'),
EAtm = OsmType('a','t','m'),
EAttraction = OsmType('a','t','t'),
EBabyHatch = OsmType('b','a','b'),
EBarracks = OsmType('b','a','r'),
EBasin = OsmType('b','a','s'),
EBay = OsmType('b','a','y'),
EBeach = OsmType('b','e','a'),
EBeacon = OsmType('b','e','c'),
EBedAndBreakfast = OsmType('b','e','d'),
EBench = OsmType('b','e','n'),
EBank = OsmType('b','n','k'),
EBoatyard = OsmType('b','o','a'),
EBoundary = OsmType('b','o','u'),
EBorough = OsmType('b','o','r'),
EBicycleParking = OsmType('b', 'p', 'k'),
EBicycleRental = OsmType('b', 'r', 'e'),
EBridleway = OsmType('b','r','i'),
EBrownField = OsmType('b','r','o'),
EBusStop = OsmType('b','s','p'),
EBusStation = OsmType('b','s','t'),
EBufferStop = OsmType('b','u','f'),
EBuilding = OsmType('b','u','i'),
EBunker = OsmType('b','u','n'),
ECabin = OsmType('c','a','b'),
ECafe = OsmType('c','a','f'),
ECampSite = OsmType('c','a','m'),
ECanal = OsmType('c','a','n'),
ECaveEntrance = OsmType('c','a','v'),
ECableCar = OsmType('c','c','r'),
ECableDistributionCabinet = OsmType('c','d','c'),
ECemetery = OsmType('c','e','m'),
EChairLift = OsmType('c','h','a'),
ECheckPoint = OsmType('c','h','e'),
EChalet = OsmType('c','h','l'),
ECivilBoundary = OsmType('c','i','b'),
ECinema = OsmType('c','i','n'),
ECity = OsmType('c','i','t'),
ECliff = OsmType('c','l','f'),
EClinic = OsmType('c','l','i'),
ECommercial = OsmType('c','m','r'),
ECoastline = OsmType('c','o','a'),
ECollege = OsmType('c','o','l'),
ECommon = OsmType('c','o','m'),
EConstruction = OsmType('c','n','s'),
EConservation = OsmType('c','n','v'),
EContinent = OsmType('c','o','n'),
ECounty = OsmType('c','o','u'),
ECarPark = OsmType('c','p','k'),
ECarRental = OsmType('c','r','e'),
ECrossing = OsmType('c','r','o'),
ECountry = OsmType('c','r','y'),
ECarSharing = OsmType('c','s','h'),
ECarWash = OsmType('c','w','a'),
ECaravanSite = OsmType('c','v','n'),
ECycleway = OsmType('c','y','c'),
EDam = OsmType('d','a','m'),
EDangerArea = OsmType('d','a','n'),
EDentist = OsmType('d','e','n'),
EDisused = OsmType('d','i','s'),
EDitch = OsmType('d','i','t'),
EDock = OsmType('d','o','c'),
EDrain = OsmType('d','r','a'),
EDragLift = OsmType('d','r','g'),
EDoctors = OsmType('d','r','s'),
EDistrict = OsmType('d','s','t'),
EElectricVehicleCharging = OsmType('e','v','c'),
EFarm = OsmType('f','a','r'),
EFarmYard = OsmType('f','a','y'),
EFell = OsmType('f','e','l'),
EFerryTerminal = OsmType('f','e','t'),
EFastFood = OsmType('f','f','d'),
EFireExtinguisher = OsmType('f','i','e'),
EFireFlapper = OsmType('f','i','f'),
EFireHose = OsmType('f','i','h'),
EFireStation = OsmType('f','i','s'),
EFireHydrant = OsmType('f','i','y'),
EFootpath = OsmType('f','o','o'),
EForestry = OsmType('f','o','r'),
EFuel = OsmType('f','u','e'),
EFunicular = OsmType('f','u','n'),
EGarages = OsmType('g','a','r'),
EGate = OsmType('g','a','t'),
EGarden = OsmType('g','d','n'),
EGenerator = OsmType('g','e','n'),
EGreenHouse = OsmType('g','h','o'),
EGlacier = OsmType('g','l','a'),
EGolfCourse = OsmType('g','o','l'),
EGondola = OsmType('g','o','n'),
EGoodsAerialWay = OsmType('g','o','o'),
EGrass = OsmType('g','r','a'),
EGreenField = OsmType('g','r','e'),
EGritBin = OsmType('g','r','b'),
EGraveYard = OsmType('g','r','y'),
EGuestHouse = OsmType('g','u','e'),
EHalt = OsmType('h','a','l'),
EHamlet = OsmType('h','a','m'),
EHangar = OsmType('h','a','n'),
EHeath = OsmType('h','e','a'),
EHelipad = OsmType('h','e','l'),
ERailwayHalt = OsmType('h','l','t'),
EHospital = OsmType('h','o','s'),
EHotel = OsmType('h','o','t'),
EHostel = OsmType('h','s','t'),
EIndustrial = OsmType('i','n','d'),
EInformation = OsmType('i','n','f'),
EIsland = OsmType('i','s','l'),
EIsolatedDwelling = OsmType('i','s','o'),
EKindergarten = OsmType('k','i','n'),
ELandFill = OsmType('l','a','n'),
ELand = OsmType('l','n','d'),
ELevelCrossing = OsmType('l','e','v'),
ELibrary = OsmType('l','i','b'),
ELightRail = OsmType('l','i','r'),
ELocality = OsmType('l','o','c'),
ELockGate = OsmType('l','o','k'),
EMaritimeBoundary = OsmType('m','a','b'),
EMall = OsmType('m','a','l'),
EMarsh = OsmType('m','a','r'),
EMeadow = OsmType('m','e','a'),
EMilitary = OsmType('m','i','l'),
EMixedAerialWay = OsmType('m','i','x'),
EMonorail = OsmType('m','o','n'),
EMotel = OsmType('m','o','t'),
EMinorPowerLine = OsmType('m','p','l'),
EMiniatureRailway = OsmType('m','r','y'),
EMud = OsmType('m','u','d'),
EMunicipality = OsmType('m','u','n'),
EMuseum = OsmType('m','u','s'),
ENarrowGauge = OsmType('n','a','r'),
ENatureReserve = OsmType('n','a','t'),
ENavalBase = OsmType('n','a','v'),
ENationalParkBoundary = OsmType('n','p','b'),
ENeighborhood = OsmType('n','e','i'),
ENursingHome = OsmType('n','u','r'),
EOrchard = OsmType('o','r','c'),
EPrecisionApproachPathIndicator = OsmType('p','a','p'),
EPark = OsmType('p','a','r'),
EPublicBuilding = OsmType('p','b','u'),
EPostBox = OsmType('p','b','x'),
EPeak = OsmType('p','e','a'),
EPharmacy = OsmType('p','h','a'),
EPhone = OsmType('p','h','o'),
EPicnicSite = OsmType('p','i','c'),
EParkingEntrance = OsmType('p','k','e'),
EParking = OsmType('p','k','g'),
EParkingSpace = OsmType('p','k','s'),
EPlantNursery = OsmType('p','l','a'),
EPlatform = OsmType('p','l','f'),
EPlaceOfWorship = OsmType('p','l','w'),
EPlayground = OsmType('p','l','y'),
EPoliticalBoundary = OsmType('p','o','b'),
EPostOffice = OsmType('p','o','f'),
EPolice = OsmType('p','o','l'),
EProtectedArea = OsmType('p','r','a'),
EPreservedRailway = OsmType('p','r','y'),
EPowerSubStation = OsmType('p','s','s'),
EPub = OsmType('p','u','b'),
EPowerLine = OsmType('p','w','l'),
EPowerStation = OsmType('p','w','s'),
EQuarry = OsmType('q','a','r'),
ERail = OsmType('r','a','i'),
ERange = OsmType('r','a','n'),
ERapids = OsmType('r','a','p'),
ERecycling = OsmType('r','c','y'),
ERecreationGround = OsmType('r','e','c'),
ERegion = OsmType('r','e','g'),
ERetail = OsmType('r','e','t'),
ERiver = OsmType('r','i','v'),
ERailway = OsmType('r','l','y'),
ERoundHouse = OsmType('r','o','u'),
EResidential = OsmType('r','s','d'),
ERestaurant = OsmType('r','s','t'),
EReservoir = OsmType('r','s','v'),
ERunway = OsmType('r','u','n'),
ERiverBank = OsmType('r','v','b'),
ESaltPond = OsmType('s','a','l'),
ESand = OsmType('s','a','n'),
ESchool = OsmType('s','c','h'),
EScree = OsmType('s','c','r'),
EScrub = OsmType('s','c','b'),
ESea = OsmType('s','e','a'),
EStateEmergencyServiceStation = OsmType('s','e','s'),
ESportsCenter = OsmType('s','p','o'),
ESportsPitch = OsmType('s','p','p'),
ESpring = OsmType('s','p','r'),
ESportsTrack = OsmType('s','p','t'),
EState = OsmType('s','t','a'),
ESteps = OsmType('s','t','e'),
EStadium = OsmType('s','t','m'),
ERailwayStation = OsmType('s','t','n'),
EStation = OsmType('s','t','n'), // deliberate duplicate
EStone = OsmType('s','t','o'),
EStopPosition = OsmType('s','t','p'),
EStream = OsmType('s','t','r'),
ESuburb = OsmType('s','u','b'),
ESubwayEntrance = OsmType('s','w','e'),
ESwimmingPool = OsmType('s','w','i'),
ESubway = OsmType('s','w','y'),
ETaxi = OsmType('t','a','x'),
ETheatre = OsmType('t','h','e'),
EThemePark = OsmType('t','h','p'),
EToilet = OsmType('t','o','i'),
ETown = OsmType('t','o','w'),
ETurningCircle = OsmType('t','c','i'),
ETurningPoint = OsmType('t','p','t'),
ETram = OsmType('t','r','a'),
ETree = OsmType('t','r','e'),
ETrafficSignals = OsmType('t','r','f'),
ETramStop = OsmType('t','r','s'),
ETurnTable = OsmType('t','u','r'),
ETower = OsmType('t','w','r'),
ETaxiway = OsmType('t','w','y'),
EUniversity = OsmType('u','n','i'),
EVisualApproachSlopeIndicator = OsmType('v','a','s'),
EVillageGreen = OsmType('v','i','g'),
EVillage = OsmType('v','i','l'),
EVineyard = OsmType('v','i','n'),
EViewPoint = OsmType('v','i','w'),
EVolcano = OsmType('v','o','l'),
EWater = OsmType('w','a','t'),
EWeir = OsmType('w','e','r'),
EWetland = OsmType('w','e','t'),
EWindsock = OsmType('w','i','s'),
EWood = OsmType('w','o','o'),
EZoo = OsmType('z','o','o')


This release was made on 5th March 2021 and is based on mainline revision 9722. It is a major release with incompatible changes to APIs, which are detailed below.

The previous release, 6.2, was made on 5th September 2020 and was based on mainline revision 9241.

Tiled route data

The makemap tool can now split contraction hierarchy route data into tiles. Any subset of the tiled maps from a particular makemap run can be used together, and routing will work using the tiles that are present. You can load and unload maps at any time. Routing will use the tiles that are available. If you load extra tiles and recreate a route, the new route may be different because of the added route data. If CartoType can't create a route because of missing tiles you will get the 'no route connectivity' error.

To create a set of tiled maps, use the makemap option /route=ct{N} for ordinary contraction hierarchy (the same system as /route=cs), or /route=tt for turn-expanded contraction hierarchy (the same system as /route=tech). The optional value N is the tile size in degrees, the default value being 1. Legal values are 1, 2, 4, 8 and 16. 4 is recommended for most purposes.

Removal of home-grown integer types

The integer types CartoType::int32, CartoType::uint16, etc., have been removed from the C++ API because they are no longer needed. The standard integer types int32_t, uint16_t are used instead.

Internal use of exception-based error handling

Nearly all internal functions now use exceptions of type TResult instead of error codes. This does not affect the public APIs, which still use error codes. The move to exceptions makes the code more reliable, less prone to memory leaks, and easier to maintain and debug. The error codes KErrorOverlap, KErrorPathLengthExceeded, KErrorMaxTurnExceeded, and KErrorCentralPath are no longer used, and a new error code KErrorXmlFeatureNotSupported (value = 62) has been added. No existing error codes have changed.

Removal of obsolete features

  • The ability to draw maps from a tile source has been removed.
  • The image server, which was a system to draw maps using cached tile bitmaps, has been removed.
  • Support for the web map service (WMS) system has been removed.

C++ API changes

  • CBitmap has a new constructor: explicit CBitmap(MInputStream& aInputStream)
  • The result constants KErrorNone, etc., now have type TResult, not int32_t, so that when they are thrown as exceptions the type is distinct.
  • The result constants KErrorOverlap, KErrorPathLengthExceeded, KErrorMaxTurnExceeded, KErrorCentralPath, have been removed.
  • Graphics operations now return TDrawResult, not TResult.
  • CFrameworkEngine::CancelDrawing has been removed.
  • TViewState has a new constructor: explicit TViewState(const char* aXmlText)
  • The CFramework::AppendStyleSheet functions now return TResult instead of being void.
  • A new function 'TFileLocation StyleSheetErrorLocation() const' returns error location information set by the last style sheet load operation.
  • CFramework::GetHeights now returns a vector of integers instead of writing to pointers supplied by the caller.
  • CFramework::SetNearbyObjectWarning now takes an extra parameter, a reference to TResult.
  • CFramework::SetVehicleTypeWarning now takes an extra parameter, a reference to TResult.
  • CFramework::SetVehiclePosOffset is now void instead of returning TResult.
  • There is a new function 'bool CFramework::TrackIsDisplayed'.
  • The deprecated overload of CFramework::InsertMapObject taking an object type has been removed.
  • The obsolete CFindFramework class has been removed.
  • Clipping and envelope functions have been added to CGeometry, allowing geometry objects to be built from operations on map objects.

The following functions now return TResult instead of being void:

  • CFramework::License
  • CFramework::SetTurnInstructions
  • CFramework::Resize
  • CFramework::SetScaleDenominator
  • CFramework::SetScaleDenominatorInView
  • CFramework::Zoom
  • CFramework::Rotate
  • CFramework::SetRotation
  • CFramework::SetViewLimits
  • CFramework::SetMainProfile
  • CFramework::AddProfile
  • CFramework::GetNavigationData
  • CFramework::DisplayTrack

.NET API changes

  • Clipping and envelope functions have been added to Geometry, allowing geometry objects to be built from operations on map objects. They use the new ClipOperation enum class.
  • There is a new GeometryList class which is a list of Geometry objects.
  • The function Framework.SetCase has been added to provide letter-case operations in a consistent way. It uses the new LetterCase enum class.

The following functions now return Result instead of being void:

  • Framework.License
  • Framework.SetTurnInstructions
  • Framework.SetScaleDenominator
  • Framework.SetScaleDenominatorInView
  • Framework.Zoom
  • Framework.Rotate
  • Framework.SetRotation
  • Framework.SetMainProfile
  • Framework.AddProfile

Android API changes

  • Clipping and envelope functions have been added to Geometry, allowing geometry objects to be built from operations on map objects. They use the new ClipOperation enum class.
  • The deprecated functions Framework.version, and Framework.setAttribute have been removed. Use Util.version, and Util.setAttribute instead.
  • The deprecated version of Framework.insertMapObject that took a map object type parameter has been removed. Use the new version which
    deduces the map object type from the gemoetry object passed in.
  • The function Framework.getPolygonArea has been removed. Use the new function getArea, which takes a Geometry object. There is also
    a new function GetLengthOrPerimeter which takes a Geometry object.
  • The deprecated route creation functions taking coordinate arrays have been removed. Use the versions taking a RouteCoordSet object.
  • The function Framework.profile has been added to return one of the currently active route profiles.
  • The function Framework.getHeightProfile has been removed.
  • The function Framework.useImageServer has been removed because the image server system is no longer supported.
  • There is a new function Framework.setCase to set the letter case of a string. It uses the new LetterCase enum class.

The following functions now return an integer error code instead of being void:

  • Framework.license
  • Framework.setTurnInstructions
  • Framework.resize
  • Framework.setScale
  • Framework.setScaleDenominatorInView
  • Framework.zoom
  • Framework.zoomIn
  • Framework.zoomOut
  • Framework.rotate
  • Framework.setRotation
  • Framework.setRotationAt
  • Framework.setMainProfile
  • Framework.addProfile

iOS API changes

All methods taking 'const char *' in the Objective C interface now take 'NSString*'.

Structures called CartoTypePointAndResult, CartoTypeIdAndResult, and CartoTypeAreaLengthAndResult have been added to make it possible
to return multiple results without using unsafe pointers.

  • The CartoTypeCoordSet struct has been removed.
  • The CartoTypePath protocol's point method now returns a CartoTypePathPoint directly instead of taking a pointer to CartoTypePathPoint.
  • CartoTypeMapObject now implements the CartoTypePath protocol.
  • Clipping and envelope functions have been added to CartoTypeGeometry, allowing geometry objects to be built from operations on map objects. They use a new enum, CartoTypeClipOperation.
  • There is a new method in CartoTypeFramework called setCase to set the letter case of a string. It uses the new CartoTypeLetterCase enum.
  • The CartoTypeFramework method loadMapWithTileParam has been removed because tiled map data sources are no longer supported.
  • The CartoTypeFramework methods insertPushPin and insertCopyOfMapObject now return CartoTypeIdAndResult so as to return the new object's ID without having to use an unsafe pointer.
  • The CartoTypeFramework method deleteObjectsFromMap now returns the number of objects deleted, not a CTResult.
  • The CartoTypeFramework method convertCoords now takes a CartoTypeGeometry object instead of a CartoTypeCoordSet.
  • The CartoTypeFramework method convertPoint now returns CartoTypePointAndResult so as to return the converted point without having to use an unsafe pointer.
  • The CartoTypeFramework method getHeights now takes a CartoTypeGeometry and returns an array of NSNumber.
  • The CartoTypeFramework method getHeightProfile has been removed.
  • The deprecated route creation methods taking CartoTypeCoordSet have been removed. Use the versions taking a CartoTypeRouteCoordSet object.
  • The CartoTypeFramework method getProfile has been added to return one of the currently active route profiles.
  • The CartoTypeFramework method getBuiltInProfile now returns a CartoTypeRouteProfile object instead of a CTResult.

The following CartoTypeFramework methods now return CTResult instead of being void:

  • license
  • setTurnInstructions
  • setMapWidth:andHeight
  • setScaleDenominator
  • setScaleDenominatorInView
  • zoom
  • rotate
  • setRotation
  • setMainProfile
  • setMainProfileType
  • addProfile



This release was made on 13th May 2021 and is based on mainline revision 9870.

The previous release, 7.0, was made on 5th March 2021 and was based on mainline revision 9722.

Map object editing functions

There are new functions to make it easier to add interactive editing to a CartoType application. They manage the creation and editing of linear and polygonal objects by means of pointer presses and movements and allow the new objects to be added to any layer of the map.

The Maps App demonstrates some of the new functions using these actions:

  • Double-click starts a new linear object OR select an existing object; when selecting an object the action selects an existing point if near enough, otherwise creates a new point.
  • Shift-double-click starts a new polygonal object OR selects an existing object if near enough in the same way as plain double-click.
  • Escape terminates editing the current object.
  • Backspace deletes the last point if there are more than two (for a line) or more than three (for a polygon). It then terminates editing the current object.
  • Delete removes the current object, asking for confirmation first.

During editing, the length or area of the current object is shown in the status bar at the bottom of the window.

The map editing functions are as follows in the C++ API. They have similar names in the other APIs.

Sets the map used to store editable objects. Does not affect objects already created.
If this function is not called, editable objects are stored in the map used for
route objects.
TResult CFramework::EditSetWritableMap(uint32_t aMapHandle);
 /** Creates a new editable line object starting at the specified point. */
TResult CFramework::EditNewLineObject(const TPointFP& aDisplayPoint);

/** Creates a new editable polygon object starting at the specified point. */
TResult CFramework::EditNewPolygonObject(const TPointFP& aDisplayPoint);

/** Moves the editable object's current point if any. */
TResult CFramework::EditMoveCurrentPoint(const TPointFP& aDisplayPoint);

/** Adds a new point to the editable object by copying the current point. */
TResult CFramework::EditAddCurrentPoint();
 /** Deletes the editable object's current point unless that would result in a line object of fewer than 2 points, or a polygon object of fewer than 3. */
TResult CFramework::EditDeleteCurrentPoint();

/** Deletes the current editable object. */
TResult CFramework::EditDeleteCurrentObject();

Selects an editable object by selecting the nearest point of any editable object within a given radius.
If the point is not within the given radius of an existing point, creates a new point.
TResult CFramework::EditSelectNearestPoint(const TPointFP& aDisplayPoint,double aRadiusInMillimeters);
Inserts the currently edited object into a chosen layer, converting it from an edited object into an ordinary object.
If aId is non-zero and aReplace is true, replaces any existing object with that ID, otherwise creates a new object.
The ID of the new object is returned in aId.
TResult CFramework::EditInsertCurrentObject(const CString& aLayer,uint64_t& aId,bool aReplace);
 /** Sets a string attribute in the currently edited object. If aKey is empty, sets the label. If aValue is empty, deletes the attribute. */
TResult CFramework::EditSetCurrentObjectStringAttribute(const CString& aKey,const CString& aValue);

/** Sets the integer attribute of the currently edited object. */
TResult CFramework::EditSetCurrentObjectIntAttribute(uint32_t aValue);

Returns the area and length of the currently edited object.
For line objects returns 0 and the length in meters.
For polygon objects returns the area in square meters and the perimeter in meters.
TResult CFramework::EditGetCurrentObjectAreaAndLength(double& aArea,double& aLength) const;

Saving and loading maps to and from memory

There are new functions to save maps to memory and load them from data stored in memory. They are intended to allow applications to save small numbers of user-added objects, such as pushpins and objects added using the new editing functions, to serialised strings that can be stored in an application data system such as UserDefaults on iOS.

The new functions are as follows in the C++ API. They have similar names in the other APIs.

Saves selected objects to a map identified by its handle by writing them as an array of bytes in CTMS format.
aFindParam can be used to select the objects to be saved.
If aMapHandle is zero it means the in-memory map used for routing.
TResult CFramework::SaveMap(uint32_t aHandle,std::vector<uint8_t>& aData,const TFindParam& aFindParam);
Reads map data from aData in CTMS format and merges it into the map identified by aHandle,
which must refer to a writable map database.
If aMapHandle is zero it means the in-memory map used for routing.
TResult CFramework::ReadMap(uint32_t aHandle,const std::vector<uint8_t>& aData)

Map object convenience functions returning points in lat/long

There are new convenience functions in CMapObject or MapObject to return points in degrees of latitude and longitude.

The new functions are as follows in the C++ API. They have similar names in the other APIs.

Returns the center of a map object in degrees.
The center is defined as the center of gravity for polygons and arrays,
a point half way along the path for lines, and the point itself for points.
Because the center is calculated using map coordinates then converted to degrees,
it depends on the map projection used by the map object.
TPointFP CMapObject::CenterInDegrees(TResult& aError) const;
 /** Returns the bounding box of a map object in degrees. */
TRectFP CMapObject::BoundsInDegrees(TResult& aError) const;
 /** Returns the geometry of a map object in degrees. */
CGeometry CMapObject::GeometryInDegrees(TResult& aError) const;

Finding the route taking the shortest time

The normal function of the 'shortest' flag in the route profile object (iShortest in C++) is to make routing provide the shortest route by distance. It is now possible to change that behaviour so that the shortest route by time, not distance, is found. To do that, set the new flag iShortestByTime to true It has an effect only when iShortest is also set; that is, it modifies the behaviour of iShortest.

Enable and disable hardware-accelerated drawing by a separate thread (Windows and .NET only)

A function has been added to enable and disable hardware-accelerated drawing by a separate thread:

Enables or disables drawing by a separate thread. Returns the previous state.
This function is intended for users who need the full capacity of the GPU
for a period when drawing is unnecessary.
When drawing is disabled, draw events can be handled by calls to Draw, but it is also necessary
to create a timer to redraw occasionally (e.g., once per second) to allow missing tiles to be
created and drawn after pans, zooms and other changes affecting the display.
bool CMapRenderer::Enable(bool aEnable);

iOS-only changes

In anticipation of Apple removing support for GLKit, which provides an OpenGL ES 2.0 API, CartoType's iOS SDK now uses the open-source MetalANGLE framework instead of GLKit.

The iOS SDK is now supplied as a zip file, not a DMG file. It contains SDKs for both iOS on a device and iOS on a simulator. Note that when you create an app using this new SDK you have to add both the iOS and the MetalANGLE SDKs to your app. Select your app, then select your build under TARGETS, then Build Phases -> Embed Frameworks, then add both CartoType.framework and MetalANGLE.framework, and tick 'Code Sign On Copy'.

Added missing functions:

CartoTypeFramework.getHeight to get the heights above sea level of the points in a Geometry object

.NET-only changes

Removed deprecated functions and other obsolete functions:

MapObject.GetIntegerAttribute(int aIndex)
Framework.InsertMapObject(int aMapHandle,MapObjectType aType,String^ aLayerName,Geometry^ aGeometry,
String^ aStringAttributes,int aIntAttribute,Int64% aId,bool aReplace)

For the last function, use the new version without aType. The type is now deduced from the type of the
geometry object.

Android-only changes

Added missing functions:


Removed obsolete functions:


Release date: 7th February 2018

Previous release: 4.4, 27th July 2017

Summary of changes

The graphics acceleration system known as CartoType GL is now incorporated into the standard version of CartoType. To use it, you create a CFramework object in the normal way, loading the map, style sheet and fonts, then create a CMapRenderer object referencing your framework. You can then draw the map at, for example, thirty frames per second, in response to a timer event.

The CMapRenderer class is a C++ class. For Android there is the Java class MapRenderer, and for iOS there is the Objective C class CartoTypeMapRenderer.

Graphics acceleration is available for iOS, Android, Windows (desktop), OS X (Macintosh), and Linux. It is available on the Qt framework for Windows (desktop), OS X (Macintosh) and Linux.

Evaluation SDKs (software development kits) allow you to try out CartoType before you buy a license. You will be able to create a test application and  find out whether CartoType is the right solution for you. The evaluation SDKs have a few restrictions, including placing a watermark on every map, but provide access to the complete API (application programming interface) and all features including graphics-accelerated rendering.

The CartoType evaluation SDKs (software development kits) are provided for evaluation only, excluding any commercial use. For commercial licensing please contact us.

By clicking on any of the links on this page, 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.

To uninstall any of these SDKs, all you need to do is delete the files from your computer.

Sample Maps

To save download time, the SDKs contain only a single sample map. It is of the Isle of Wight, an island off the southern coast of England, chosen because of its good mix of features: urban, rural, and coastal. Please contact us if you need a map of any particular area for evaluation purposes.

Sample Code

The source code for most of our demonstration programs is available in public GitHub repositories in the account code for the current release is here: The code is supplied under the permissive MIT license.

Release notes

The current version of the CartoType SDK is release 7.2. It was released on 13th May 2021.

The current build is 7.2.16, uploaded on 9th June 2021.

recent changes
fixed regression preventing anti-aliased polygon edges from being drawn
fixed case 4876: place names should have higher style sheet priority than railway stations
fixed case 4878: the maps app crashes with old .ctm1 files
fixed case 4884: maps app style editor displays lines in the wrong style
--- 7.2.16 ---

The Android SDK

The Android SDK allows you to use CartoType with the Android operating system. You use the CartoType Android API, which gives you access to all the features of CartoType: loading maps, adding your own objects to the map, panning, zooming, address searching, routing and navigation.

Download link: Android SDK

The SDK is a ZIP file of about 22Mb. It contains a folder called cartotype_android_sdk_evaluation containing the following folders:

libs: an .AAR (Android archive) called cartotype.aar, which is the CartoType library. Add it to your Android Studio project as a dependency.

font: standard fonts; for simple CartoType use you need load only DejaVuSans.ttf

map: sample maps

style: the standard style sheets; you should load standard.ctstyle with the sample map

doc: licenses and acknowledgments for third-party libraries

Android demo program with source code

CartoTypeMaps is a full-featured sample program for CartoType on Android. It's provided as an Android Studio project, and includes the 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 the menus. CartoTypeMaps is ready to run. Just download the code or use git to clone the repository (git clone 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.

You can also download a prebuilt version: CartoTypeMaps as an APK file (235Mb download). You can install it on your Android phone or tablet. It comes with a map of London and the surrounding area. You can easily load other maps if you prefer.


The iOS SDK allows you to build CartoType apps for the iPhone and iPad. It is supplied as a .dmg file (Apple Disk Image) containing the file CartoType.framework. You use the CartoType iOS API, written in Objective C, which gives you access to all functionality.

Note: in order to avoid linker errors when using the -ObjC flag, you need to have at least one ".cpp" (C++) or ".mm" (Objective C++) source file in your own project, even if it's an empty one. If your project has ".m" (Objective C) and ".h" files only you will get linker errors because Xcode won't know that there is both C++ and Objective C code in the project.

Download link: iOS SDK

This is a 42Mb download containing the header files and compiled libraries for the simulator and device targets as a zip file. A sample map, style sheets, fonts and tools including makemap, the map building program, are also included. It contains SDKs for both iOS on a device and and iOS on a simulator. Note that when you create an app using this new SDK you have to add both the iOS and the MetalANGLE SDKs to your app. Select your app, then select your build under TARGETS, then Build Phases -> Embed Frameworks, then add both CartoType.framework and MetalANGLE.framework, and tick 'Code Sign On Copy'.

(If you are upgrading to a new version of the CartoType iOS SDK, you may sometimes find that Xcode does not recognize new Objective C headers or classes. You can usually fix this problem by closing your project, opening the organizer from the Xcode Window menu, select your project, then click on 'delete' opposite 'derived data'. Then close Xcode, reopen your project, clean it and rebuild. Thanks to TigerCoding for this tip from StackOverflow.)

iOS demo program with source code

You can also download the source code and project files for a full-featured sample 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.

iOS sample project

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.

The C# (.NET) SDK

This SDK allows you to use CartoType with the .NET framework. You can use any .NET language, such as C#, VB.NET or C++/CLI. You can build a complete application using CartoType in just a few lines of code, as shown in the C# demo program included with the SDK. The .NET SDK (documented here) gives you access to all CartoType features, including map, style sheet and font loading, route calculation, navigation and address searching. It also gives access to graphics acceleration using OpenGL ES 2.0.

Download link: .NET SDK

This is a 38Mb zipped file containing a .NET DLL built for the Intel x64 platform and a C# demonstration program that uses the CartoType DLL, with its source code and data files. An XML documentation file is also supplied. As long as it is kept in the same place as the DLL it will provide tool-tip help for some of the functions.

Note: if you have trouble adding the DLL to your project, in particular if you get a message starting "could not load file or assembly ... CartoTypeWrapper.DLL", please try the following fixes: (i) right-click on CartoTypeWrapper.dll in Windows Explorer and click on 'Properties' in the context menu, then, if you see the text 'This file came from another computer and might be blocked to help protect this computer', click 'Unblock' to the right of that text; (ii) if that doesn't work try installing, or re-installing, the Visual C++ Redistributable for Visual Studio 2017 (please google that phrase to find the current download link).


cartotype dot net development screen shot

The zip file creates a single directory called CartoTypeDemo when unzipped.

Useful locations

The CartoType .NET DLL

  • release version: CartoTypeDemo\vs2019\bin\x64\Release\CartoTypeWrapper.dll
  • debug version: CartoTypeDemo\vs2019\bin\x64\Debug\CartoTypeWrapper.dll

Visual Studio solution and project files:

  • CartoTypeDemo\vs2019\CartoTypeDemo.sln
  • CartoTypeDemo\vs2019\CartoTypeDemo.csproj

Data files

  • sample map: map\isle_of_wight.ctm1
  • standard style sheet: style\standard.ctstyle
  • standard font: font\DejaVuSans.ttf

The DLLs used for graphics acceleration, libEGL.dll and libGLESvs.dll, are in the same locations as the .NET DLLs. They need to be accessible to any application using the CartoType .NET SDK.

Another style sheet and extra fonts are also to be found in the style and font folders. It's always a good idea to load DroidSansFallback as well as any other fonts, because it provides characters for many non-Latin scripts.

The CartoType .NET DLL will not run on non-Intel platforms because the CartoType library is compiled into native code from C++.

The Windows SDK

This SDK (documented here) supports CartoType development for desktop versions of Windows from Windows XP through Windows 8.
The CartoType Windows SDK supports development using standard Windows, or using the Qt framework.

Download link: Windows SDK

This is a 107Mb zipped file containing the CartoType header files and debug and release mode libraries for desktop Windows, built using Microsoft Visual Studio 2019 for the x64 platform.

The zip file creates a single directory called CartoType when unzipped.

Useful locations

Libraries and executables

  • release version: CartoType\bin\16.0\x64\Release\cartotype.lib
  • debug version: CartoType\bin\16.0\x64\Debug\cartotype.lib
  • tools to build maps, etc. (makemap, ctm1_info, encrypt_file): CartoType\bin\16.0\x64\Release

There are also directories with the same names but with DLL appended: CartoType\bin\16.0\x64\ReleaseDLL, etc. They contain libraries linked to the C++ runtime library as a DLL, not statically. These libraries can be used with Qt. To build for Qt you will also need to link to CartoTypeQtMapRenderer.lib, which is also supplied. Qt is supported for the x64 builds only. See CartoType and Qt for detailed instructions on using Qt to build and run the sample Maps App.


  • CartoType\src\main\base; you need include only one header file, cartotype_framework.h, to use the CartoType C++ API

Visual Studio solution and project files for the demonstration program

  • CartoType\src\demo\windows_demo\vs2019\CartoTypeDemo.sln

Data files

  • sample map: CartoType\map\isle_of_wight.ctm1
  • standard style sheet: CartoType\style\standard.ctstyle
  • standard font: CartoType\font\DejaVuSans.ttf

Another style sheet and extra fonts are also to be found in the style and font folders.

The Linux SDK

The C++ SDK (documented here) supports development for Linux (Ubuntu and other x11 versions) on 64-bit Intel platforms.
The Linux SDK supports developments using various GUI frameworks including Qt.

Download link: Linux SDK

This is a 20Mb zip file containing a folder called cartotype-linux-sdk, which contains the following folders:

bin: the release-mode evaluation CartoType library, and the makemap tool for creating maps, and the other tools ctm1_info and encrypt_file, and (for Qt builds) the Qt map graphics-accelerated map renderer library libCartoTypeQtMapRenderer.a and other libraries needed for Qt builds.

font: standard fonts; for simple CartoType use you need load only DejaVuSans.ttf

header: the C++ header files; you need to include only one of the header files, cartotype_framework.h, to use CartoType

map: a sample map

style: the standard style sheets; you should load standard.ctstyle with the sample map

Linux SDK notes

  • The CartoType Linux library is built for 64-bit Intel platforms.
  • You may need to add the option -pthread to both compiler and linker options, otherwise you might get a linker error for pthread_create.
  • Set the compiler option +std=c++14, because CartoType uses C++14.
  • If you get linker errors mentioning types in the std namespace, the cause is probably that the CartoType Linux Library is compiled using GCC 5.1 or later, and you are using GCC 4.9 or earlier.

CartoType demonstration applications

These programs are intended to show off the features of CartoType and help you decide whether the CartoType library could be a useful part of your software application.

By using the CartoType demonstration programs, maps or style sheets, 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 demonstration programs, maps or style sheets, and that the demonstration programs, maps or style sheets are not warranted fit for any particular use and are for evaluation use only and may not be used for any commercial purpose.