Release Notes for CartoType 7.2

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()

CartoType Release Notes