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.

The colors are set using the map object attributes _color and _border_color. They can use any color expression that is valid in a style sheet. For example: 'blue', 'orange+0.25white', '#A00', '#08123456'. Formally, a color expression consists of one or more sections separated by plus signs. The format of a section is

{ '+' { blend-ratio } } hex-color | color-name

where blend-ratio is an optional number; if it's between 0 and 1 inclusive it's treated as a fraction, otherwise as a number of 255ths; and hex-color is either #RGB, #RGBA, #RRGGBB or #RRGGBBAA. The plus sign and blend-ratio are legal only if there is a previous color to blend with.

Applying color effects to the entire style sheet: generalising night mode

Previous versions allowed a 'night mode' to be set, in which roads were made brighter and other layers were blended with a dark color to make them less prominent.

It is now possible to apply color changes to any layer or layers in the style sheet using a blend style set (TBlendStyleSet in the C++ API), which is a vector of blend styles. A blend style is a list of style names, which may include names with wild cards, and a series of colors to be blended with the main color, border color, text color, text glow color, and icon color for those styles. The blend styles are applied in order.

This generalisation of the idea of night mode allows, for example, all map objects to be drawn in a faint version of their usual colors, by blending with white, except for layers of interest, which can be drawn in brighter colors.

The colors in a blend style are treated as RGB colors. The alpha value is used as the blend ratio. The alpha value of the target color is preserved during blending, to maintain the overall visual intent of the style sheet.

New error codes to diagnose missing files and style sheet errors

There are three new error codes, KErrorMapNotFound (63), KErrorFontNotFound (64) and KErrorStyleSheetNotFound (65) to help identify the reason for a failure to create a Framework object.

In addition, style sheet errors can be located by line and column number. The error codes returned by XML parsing have been redesigned to hold the Expat parser error code, the line number, and the column number of the error. XML errors are now in the range KErrorXmlRangeStart (0x10000000) to  ErrorXmlRangeEnd (0x2AFFFFFF) inclusive. The high byte is 0x10 for errors specific to CartoType's style sheet system (e.g., nested <layer> sections), or is in the range 0x11 to 0x2A for Expat XML parser error codes. The low three bytes give the error location: one byte for the column number and the two low bytes for the line number.

The ErrorString function, which now exists on all platforms, unpacks this and other error codes into a readable string, which is supplied when an exception is thrown on the .NET, Android and iOS SDKs. In the C++ SDK the exception type remains TResult, but the user can easily call ErrorString to obtain the string version of the error.

Inserted objects are drawn in order of insertion

Map objects inserted at run-time are now drawn, if they are in the same layer and the same <condition> within the layer, in order of their map object IDs, which by default is the order in which they are inserted. Thus newer objects are consistently drawn over older objects so that user supplied graphics can be used to build up a picture.

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, Framework.build and Framework.setAttribute have been removed. Use Util.version, Util.build 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
CartoTypeFramework.pixelsToMeters
CartoTypeFramework.metersToPixels

.NET-only changes

Removed deprecated functions and other obsolete functions:

MapObject.GetIntegerAttribute(int aIndex)
MapObject.GetIntegerAttributeCount()
MapObject.GetDistanceToRoute()
MapObject.GetDistanceAlongRoute()
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:

Framework.pixelsToMeters
Framework.metersToPixels
Framework.dataSetName

Removed obsolete functions:

MapObject.getDistanceToRoute()
MapObject.getDistanceAlongRoute()

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.