This release, 8.6, was made on 8th August 2023 and is based on commit 8.6-1-gc0939f76f in the Git repository.
The previous release, 8.4, was made on 20th February 2023 and was based on commit 8.4-1-gcb08c572d in the Git repository.
Online Map Data Access
New functionality allows CartoType to support both the client and server roles in using CTM1 files online. The Framework function
std::string HandleQuery(const std::string& aQuery,const std::string& aData)
can be used by servers to handle queries sent from client programs. A client program opens a map file using a URL instead of a filename. Any string starting with http: or https: is treated as a URL. Internally, requests for map data are passed to the server as HTTP requests which must be fulfilled using Framework::HandleQuery. The HandleQuery function is implemented in the C++ and .NET APIs, allowing servers to be written using C++, C#, or another .NET language. The client program can run on any CartoType platform. This allows CartoType applications to use very large maps without the need to install the map data on a device.
This release, 8.4, was made on 20th February 2023 and is based on commit 8.4-1-gcb08c572d in the Git repository.
The previous release, 8.2, was made on 9th December 2022 and was based on commit 8.2-57-g51a9fa561 in the Git repository.
mapinfo is the new name for ctm1_info
The tool to describe the contents of a CartoType map file (a CTM1 file) is now called mapinfo, not ctm1_info. The new name is more descriptive and easier to type.
mapinfo usage and command line options are now:
usage :mapinfo { -option1 ... -optionN } <CartoType map file (CTM1 file) name>
options:
-d<layer>{,<condition>}: dumps all map objects in a layer,
optionally using a condition to select objects
-D<layer>{,<condition>}: like -d but also dumps coordinates
-a<layer>{,<condition>}: like -d but gives combined area and length of objects only
-e<W,S,E,N> or <zoom,X,Y>: applies an extent to following -d or -D options
-f<building>,<street>,<city>{,<postcode>}: finds addresses
-i: uses imperial units (miles, yards, acres) instead of metric units (kilometres, metres, hectares)
-n: no info (for use with -d, etc.) does not list global information, tables or layers
-v: verbose: lists layers
-V: more verbose: lists layers and low-res layers
This release was made on 9th December 2022 and is based on commit 8.2-57-g51a9fa561 in the new Git repository.
The previous release was made on 5th July 2022 and was based on CartoType-mainline revision 10787 in the Mercurial repository.
Fast street address searching
The makemap tool now creates a street index table. Street address searching is now faster and more accurate when using map files containing the new table. Fast street address searching is used automatically for searches with a street name, a city name or postal code,and an optional building name or number. Abbreviations, omitted words and fuzzy matching are supported.
Mutual accessibility checking for the time/distance matrix function
The TimeAndDistanceMatrix function can run slowly if not all the points supplied are connected together by the network of routable roads. A new Framework function, MutuallyAccessible, checks at high speed whether any group of points is mutually connected, and optionally returns the IDs of the connectivity groups to which the points belong; group 1 is the largest group, so in practice any point not belonging to group 1 is inaccessible. A group ID of zero means that a point is not connected to any other points.
This release was made on 5th July 2022 and is based on mainline revision 10787.
The previous release, 7.8, was made on 28th March 2022 and was based on mainline revision 10409.
This is a major release which introduces many source code incompatibilities. They fall into two categories: renaming of public identifiers, and the introduction of simpler and consistent feature types for map objects. The aim is to make CartoType applications easier to write, read and debug.
The previous release will continue to be supported until 31st July 2024 and will receive bug fixes but no new features.
Renaming
Classes, functions and other identifiers have been systematically renamed, with the aim of improving consistency and removing outdated and unnecessary conventions.
This release was made on 29th March 2022 and is based on mainline revision 10409.
The previous release, 7.6, was made on 18th October 2021 and was based on mainline revision 10121.
Added time/distance matrix function
There is now a function to return a time/distance matrix giving the route time and distance for all combinations of a set of start points and a set of end points. It is implemented for the turn-expanded contraction hierarchy /route=tech), turn-expanded (/route=t), and a-star (/route=a) routers. The fastest implementation by far is that for the TECH router, but that implementation does not support arbitrary run-time route profiles or dynamic road closures. The fastest flexible implementation, which does support those features, is that for the turn-expanded router.
There is a new makemap option, /hublabels=yes, which can be used in conjunction with /route=tech to add hub label data to the TECH route data to enable ultra-fast calculation of time/distance matrices.
This release was made on 18th October 2021 and is based on mainline revision 10121.
The previous release, 7.4, was made on 27th July 2021 and was based on mainline revision 9961.
A new routing system with compact data
There is a new routing system, Turn-Expanded Compact. Use the option /route=tc in makemap. It requires much less run-time memory, but, unlike the contraction hierarchy systems, allows arbitrary route profiles to be set at run time. It is suitable for large areas such as the whole of the UK on mobile platforms like iOS and Android.
This release was made on 27th July 2021 and is based on mainline revision 9961.
The previous release, 7.2, was made on 13th May 2021 and was based on mainline revision 9870.
Setting colors of map objects individually
It is now possible to give every map object that is a line or a polygon its own main color and border color, overriding any colors set in the style sheet. Formerly that was possible only for
icons. The new feature is principally useful when inserting map objects at run time ('dynamic map objects') but can be used when building the CTM1 file by inserting appropriate logic in the .makemap rules.
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:
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.
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.
Release date: 27th July 2017
Previous release: 4.3, 21st April 2017
Summary of changes
You can use any shape to clip the results of searches for map objects, by providing a geometry object as the clip region. Geometry objects can be created from map objects and rectangles.
The route and route segment classes no longer contain route instructions. You can create them easily from any route object using a new function. This makes route calculation much faster; sometimes you want to create a route and show it on the map, but not create the instructions, and the last step is rather expensive.
There is now a function to get all the string attributes of a map object as a suitable aggregate such as a std::map (C++) or a sorted dictionary (.NET).
You can set the colors of icons and label text using map object attributes, and you can create icons consisting of a character or characters from an
icon font; such a font is provided: MapkeyIcons.ttf. The new style sheet attributes are:
- In <label> or <extraLabel>, the attribute colorAttrib names a map object attribute providing the label text color as a standard color specification as used in style sheets: a name, hex number starting with #, etc. If present, this color overrides the normal label color.
- In <icon>, font attributes can be used, like font-size and font-style, to set the font of a text icon.
- In <icon>, the attribute 'color' sets the icon color, colorizing it if it is normally a multi-color SVG icon, or setting its color if it is a text icon.
- In <icon>, the attribute 'colorAttrib' names a map object attribute providing the icon color. It overrides 'color'.
- In <icon>, the attribute 'text' provides a character or characters to be used as a text icon. For example, the character ''
(using the XML representation of the Unicode private-use codepoint U+E054) is
a camp-site icon in the MapkeyIcons font which is now supplied with CartoType. - In <icon>, the attribute 'textAttrib' names a map object attribute providing the character or characters to be used as a text icon. It overrides 'text'.
Changes to the C++ API
Nearly all plain enum types are now enum class, and have shorter names. For example, EFollowModeNone is now TFollowMode::None. However, in the most common cases, backward-compatible definitions have been provided, as for example 'constexpr TFollowMode EFollowModeNone = TFollowMode::None;' .
Some functions which in practice always returned KErrorNone now do not return an error code and are of 'void' return type. For example, CFramework::EnableMapByHandle.
The bit values TNavigationData::ETimeValid, etc., now start with K and are TNavigationData::KTimeValid, etc. The E prefix for enumerated values is being phased out, and these values are in any case constants, which by convention take the prefix K.
TFindParam::iClipCoordType has been abolished, and iClip is now of type CGeometry; CGeometry has a coordinate type. This means that all searches can now use a non-rectangular clip area. You can create CGeometry objects from TRectFP and CMapObject, or create them by adding points manually.
The new function 'std::map<CString,CString> CMapObject::GetStringAttributes() const' returns all the string attributes of a map object.
The CRoute class no longer contains route instructions. Use this function to get route instructions for the current locale: 'CString CFramework::RouteInstructions(const CRoute& aRoute) const' .
Changes to the .NET API
FindParam.m_clip_coord_type has been abolished, and m_clip is now a reference to Geometry; Geometry has a coordinate type. This means that all searches can now use a non-rectangular clip area. You can create Geometry objects from Rect and MapObject, or create them by adding points manually.
MapObject.GetStringAttributes() now returns a sorted dictionary mapping keys to values. It formerly returned a list of strings, implicitly treated as key-value pairs.
The Route class no longer contains route instructions. Use Framework.GetRouteInstructions instead. It gets instructions for the current locale.
Some functions which in practice always returned ErrorNone now do not return an error code and are of 'void' return type. For example, Framework.EnableMapByHandle.
Changes to the Android API
FindParam.iClipCoordType has been abolished, and iClip is now a reference to Geometry; Geometry has a coordinate type. This means that all searches can now use a non-rectangular clip area. You can create Geometry objects from Rect and MapObject, or create them by adding points manually. The multi-argument find() function has changed in the same way: its aClipCoordType argument has been abolished, and aClip is now a reference to Geometry.
MapObject.getStringAttributes() now returns a TreeMap mapping keys to values. It formerly returned a list of strings, implicitly treated as key-value pairs. The former functionality is still available as getStringAttributesArray().
The Route class no longer contains route instructions. Use Framework.getRouteInstructions instead. It gets instructions for the current locale.
Some functions which in practice always returned no error (0) now do not return an error code and are of 'void' return type. For example, Framework.enableMap.
Changes to the iOS API
CartoTypeFindParam.clipCoordType has been abolished, and clip is now a reference to CartoTypeGeometry; CartoTypeGeometry has a coordinate type. This means that all searches can now use a non-rectangular clip area. You can create CartoTypeGeometry objects from CartoTypeRect and CartoTypeMapObject, or create them by adding points manually.
The new getStringAttributes method of CartoTypeMapObject returns an NSMutableDictionary mapping keys to values.
The CartoTypeRoute route class no longer has a getInstructions method. Use the getRouteInstructions method of CartoTypeFramework instead.
Some functions which in practice always returned CTErrorNone now do not return an error code and are of 'void' return type. For example, setStyleSheetVariable.
Changes to the Maps App
The Maps App now allows you to set the colors of icons, and optionally choose a custom icon from the supplied icon font, MapkeyIcons.ttf.
Release date: 21st April 2017
Previous release: 4.2, 12th December 2016
Major changes since the previous release
Added a new routing system, turn-expanded A-star, which allows routes to pass through the same junction or road segment twice.
Added functions to set and get the preferred routing system and find out what the actual current routing system is.
Improved the system for allowing routes to pass along private highways at start and end, which was formerly unreliable and could cause slow route calculation.
The CFramework functions GeoCodeSummary and GetAddress no longer take a locale parameter. They use the locale set by CFramework::SetLocale; analogous changes have been made to the Android, .NET, and iOS SDKs.
Changes affecting the C++ API only
Abolished the CartoType-specific array classes CArray, CPointerArray, CNonOwningPointerArray, TFixedSizeArray. Standard library std::vector and std::array classes are now used instead of them.
Added functions CFramework::AbbreviatePlacename and ExpandStreetName.
Added the string class TWritableText, mostly for internal use.
The TTextLiteral macro now causes no code to be executed at run-time.
Changes affecting the .NET API only
The Geometry class now has functions to get the number of contours, number of points in any contour, the coordinates of a point, and whether the object is empty.
Changes affecting the IOS API only
The CartoTypeGeometry class now has functions to get the number of contours, number of points in any contour, and the coordinates of a point.
Changes to makemap
Many more projections are supported by the /project option, allowing you to use (for example) Lambert Equal Area with default parameters by simply using /project=laea instead of having to supply the full set of proj.4 options. The names are the same as those used in proj.4. The following projections are now supported: merc, cea, eqc, tmerc, tcea, cass, sinu, moll, eck1...eck6, goode, hatano, mbtfpp, mbtfpq, mbtfps, putp2, putp5, quau, winkl, boggs, collg, dense, parab, poly, hammer, wag7, aitoff, wintri, loxim, bonne, lcc, eqdc, pconic, aea, leac, rpoly, stere, sterea, gnom, ortho, airy, laea, aeqd.
A better memory allocation system gives about a 13% speed improvement when creating a CTM1 file from OSM data.
Some parallellization gives a further small speed improvement on multi-core computers; e.g., 3% on four physical cores.
Release 4.2 makes relatively few API changes. Its purpose is mainly to merge in a large number of internal changes from the main development branch.
Changes affecting all platforms
ReverseRoutes function
The new ReverseRoutes or reverseRoutes function reverses current routes, replacing them with new routes from the former end to the former start.
Changes to the C++ API
CMapObject
The CBaseMapObject class has been abolished. The public map object class is now CMapObject.
CMapObjectArray
There is a convenience declaration, CMapObjectArray, defined as std::vector<std::unique_ptr<CMapObject>> CMapObjectArray, which is used when returning map objects from Find functions. It replaces all former uses of CPointerArray<CBaseMapObject>. The use of unique pointers clarifies ownership and makes the objects easier to manage.
CBitmap
CBitmap functions which create modified bitmaps now return CBitmap objects, not std::unique_ptr<CBitmap>. There is no loss of performance because move operations are used internally.
Indication of turn-off
The TTurn class now has a member iTurnOff indicating whether is a turn off, defined as a turn on to a lower-status road.
Changes to the .NET API
MapObjectList
There is a new class, MapObjectList, defined as System.Collections.Generic.List<CartoType.MapObject>, which is used when returning map objects from Find functions. It replaces all former uses of List<MapObject>. One advantage of this change is that it allows documentation for Find functions to be shown in the Visual Studio Object Browser. Formerly, the presence of < and > signs in the C++/CLI type List<MapObject^>^ prevented in-source documentation for the Find functions from being created during compilation.
Changes to the Android API
Licensing functions
Two new functions, Framework.license and Framework.licensee, allow you to supply a license key and get the licensee name respectively.
deleteRoutes
The new deleteRoutes function deletes all current routes.
Changes affecting all APIs
Gradients can be used in routing
You can add gradients to route data using the makemap command-line options /route=ag (A-star routing with gradients) or /route=cg (contraction hierarchy routing with gradients). For this to work you have to load the elevation data from USGS .hgt files using the /usgs option. For more details about the /usgs option see the main article about creating maps.
If you add gradients, one of eight gradients (flat or slight, gentle, steep and very steep, each in an uphill or downhill varient) is stored for every route segment. You can add speed weightings and bonuses to the route profile for the gradients, and specify which road types the gradient weightings apply to.
Loading and saving routes
Route objects now contain the route profile used to create them, which means you no longer have to specify a profile when saving a route. You can now load or save routes in files or strings, and you can load routes from GPX files, in which case the GPX track is converted to a legal route. All route loading and saving functions allow you to use either .ctroute or GPX format.
Layer names
You can get all the layer names in a single array using a new LayerNames or layerNames function.
Changes to the C++ API
Smart pointers
Functions creating objects (e.g., New functions, LoadMapObject) now return std::unique_ptr, not a raw pointer. This makes it much easier to manage their lifetimes.
String properties
String properties like Name, Locale and Proj4Param that were formerly returned as const char* are now returned as std::string, making it easier to write safe code.
Setting camera parameters in perspective view
The new SetPerspective overload takes a TPerspectiveParam object which allows you to set camera height, angle, rotation, field of view and other parameters.
Framework observers
Framework observers are now supported, primarily for use by CartoType GL.
Multiple framework observers are now supported: AddObserver and RemoveObserver replace SetObserver.
Changes to the Android Java API
Framework observers
Framework observers are now supported, primarily for use by CartoType GL.
CartoType release 4.0
and how it differs from release 3
Changes affecting all APIs
The Legend API
The new Legend API allows you to create consistent, good-looking and flexible legends (scale bars and keys to symbols) as separate images which can be overlaid on the map or drawn elsewhere.
Consistent argument order for the Find functions
The many Find functions now order their arguments consistently. The destination array always comes first, followed by the maximum object count if applicable, and so on. These changes also affect the non-C++ APIs.
C++
Moving to C++11
The main theme of the changes is a move to modern C++. C++11 is supported on all major platforms, including Windows (VS2015), iOS (Xcode), the Android NDK (gcc), and Linux (gcc).
Memory allocation failure throws an exception
CartoType's builds formerly disabled exceptions and handled out-of-memory conditions by using a memory allocator which returned null when out of memory. The error KErrorNoMemory was then propagated back up the stack. CartoType 4.0 uses exceptions, and throws std::bad_alloc when an allocation fails. Other errors like failing to open a file are still handled using error codes.
Arrays are std::vector objects
CartoType's main two array classes are now publicly derived from std::vector:
template<class T> class CArray: public std::vector<T>
template<class T> class CPointerArray: public std::vector<T*>
That means you can now use all the std::vector functions and algorithms. Of course, because memory allocation failure now throws an exception, array functions no longer return error codes.
Sample code showing the use of range for with a CartoType array:
CPointerArray<CBaseMapObject> found_objects;
my_framework->Find(found_objects,find_param);
for (const auto p : found_objects)
{
size_t everywhere
Many argument and return types have changed from int32 to size_t to avoid warnings when using the new array classes based on std::vector.
CString
CartoType::CString now has value semantics, which means you can assign strings to each other, pass them as function arguments, return them from functions, and create arrays of them. A CString still holds UTF-16 text, but can now be constructed from null-terminated 8-bit strings, and also from std::string. You can even construct a string from nullptr, which makes it easy to have default CString arguments: void myfunc(CString aText = nullptr). All this means that…
String arguments are simpler
Most functions taking string arguments now take CString or const CString&. Overloads taking const char* no longer exist. But thanks to the new CString constructors you can pass 8-bit string literals or std::string objects if you like.
So you can call CFramework::LoadMap in these different ways:
my_framework->LoadMap("england.ctm1");
std::string map_name1("wales.ctm1");
my_framework->LoadMap(map_name1);
CString map_name2("scotland.ctm1");
my_framework->LoadMap(map_name2);
Observer interface: MFrameworkObserver
The new observer interface allows you to provide an observer object to a CartoType::CFramework object. The observer receives notifications of changes to the framework state. It is intended for the use of higher-level GUI objects which need to update their display after framework state has been changed programmatically. For example, if a route is created, dynamic map objects need to be redrawn.
British national grid functions
There are some new functions to convert back and forth between British national grid references and other position formats. They are useful when comparing CartoType maps of Great Britain with Ordnance Survey maps.
CT_IMPORT and CT_EXPORT have gone
The macros CT_IMPORT and CT_EXPORT were used in older versions of CartoType to declare functions as exported from DLLs. The C++ SDK is no longer built or shipped as a DLL, therefore these macros have been abolished.
Simpler functions to set and get string attributes
The functions to set and get string attributes have been simplified. For example, where you formerly wrote:
CString key; key.Set("addr:street");
TText street;
my_map_object->GetStringAttribute(&key,street);
you can now write
CString street = my_map_object->GetStringAttribute("addr:street");
The makemap tool
No more support for old-style import scripts
Two obsolete import script formats are no longer supported. They are the old OSM rule format with the extension .osm_to_ctm1_rules, and the old shapefile rule format with the extension xml. The new .makemap format replaces them both.
In particular, when you import coastlines from shapefile data you should use a coastlines.makemap file with this content (adjusting the filename as necessary):
<?xml version="1.0" encoding="UTF-8"?>
<CartoTypeImportRules>
<file name='\coastlines-complete\land_polygons.shp'>
<commit layer='outline'/>
</file>
</CartoTypeImportRules>
The .makemap import rules format is described here: http://www.cartotype.com/import-rules-used-by-makemap.html .
Release date: 9th September 2015
Previous release: 3.4, 26th June 2015
Release date: 26th June 2015
Previous release: 3.3, 13th May 2015
