From OpenStreetMap Wiki
Jump to navigation Jump to search

COSMCtrl is an freeware MFC GUI control class which implements display of OpenStreeMap tiles. It is developed by PJ Naughter pjna


This is a freeware, meaning that it can be freely copied and redistributed as is (without any support or warranty offered). But it is not open source: source code of this control (for Microsoft Visual C++) is provided along with the binary form, and modifications of the source code are permitted... but all copyright and author attributions must be preserved, even though you cannot redistribute modified sources, only modified binaries; so there's no public repository or open source project hosted on a community platform. The copyright and usage rules say:

  • You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
  • You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
  • If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.


COSMCtrl was first released in November 2009 and the current released version as of December 2021 is 1.36. It has the following features:

  • Provides a standard MFC CStatic derived class which can be used just like the CStatic class.
  • Supports Mapnik, Cyclemap, Mapquest OSM and Mapquest Open Aerial tile providers.
  • Supports downloading via WinHTTP to a configurable local file system cache to improve performance.
  • Supports zooming via keyboard keys and the wheel mouse. It uses the keys '+' and '-' and a mouse left double click.
  • Supports scrolling via the keyboard as well as mouse dragging. It uses the keys "Left", "Back", "Right", "End", "Up", "Prior", "Down" and "Next".
  • Implements asynchronous download of visible tiles.
  • Supports a scroll rose and zoom bar based on the same controls on the OpenStreeMap web site.
  • Supports displaying a simple legend which indicates scale.
  • Supports automatically displaying correct OpenStreetMap copyright attribution on the control. This is achieved through the use of a child control SysLink control with hyperlinks to the OpenStreetMap web site and the license it uses.
  • All of the control parts which the COSMCtrl class supports namely scroll rose, zoom bar, legend and the copyright items can be attached to specific client locations on the map.
  • Tiles from the previous and next zoom level can be used in a stretched and squeezed fashion if not available at the current zoom level.
  • Supports used defined markers, polylines, polygons and circles being overlaid on the map. In addition to just allowing static markers, polylines, polygons and circles to be added, the code has comprehensive support for interactively editing, dragging, moving and deleted these items. Please note that these items cannot be correctly displayed if they cross the international date line or if they traverse extreme polar latitudes which the slippy map tiles of OpenStreetMap do not cover.
  • Tiles outside the visible edge can be pre-cached for improved performance.
  • Provides helper methods to allow download of specific tiles.
  • Supports a full set of methods to calculate the distance between two points as well as calculate the end location from a start position given a certain distance and bearing. These methods implement C++ versions of Vincenty's Direct and Inverse algorithms. These methods are required for calculation of the scale bar as well as supporting dragging polygons and polylines. The sample app now uses these features to show the distance and bearing for the first polyline or polygon which is selected in the status bar.
  • The class supports a Rectangular selection mode. When this mode is activated, you can select specific markers, polylines and polygons on the map and in conjunction with support for the "Delete" button you can interactively edit the items on the map
  • A complete sample app which exercises all the classes functionality including print preview and printing support.
  • Supports a comprehensive "Map Operations" dialog. This in conjunction with the rectangular selection mechanism allows you to delete specific tiles, download specific tiles (optionally skipping files which have already been downloaded) as well as support Mapnik re-render requests. This dialog uses a worker thread to remain responsive while these potentially lengthy operations are taking place. In addition this dialog provides feedback via a progress control and a static text notification area as the operation is taking place as well as cancelation support. This dialog on its own provides a good example on how to implement a responsive user interface while a lengthy operation is happening.
  • Supports "decimation" of polylines and polygons. This feature adds new nodes between all the existing nodes of a polyline or polygon. This can prove useful where you have a feature where the curvature of the earth can cause distortion of the displayed object. By default this feature is provided for by double clicking on an editable polyline or polygon.
  • Support for drawing crosshairs at the center of the map.
  • Supports a ZoomToBounds method. This method takes two positions which the method will ensure will be shown on the map at the highest possible zoom level. In conjunction with various "GetBoundingRect*" methods you can now add your various items to the map and then zoom to those items. This avoids client code needing to explicitly handle zoom levels of center positions.
  • Provides a comprehensive API via the public methods of the class. In addition numerous virtual functions are provided to further customize the behaviour of the class.
  • Provides support for GPS devices via the authors GPSCom2 library.
  • As of v1.09, the control now uses the Windows 7 Animation API's if available for zoom level and position changes.
  • As of v1.10, the sample app now supports collecting track logs to GPX files and importing GPX files for display on the map.
  • As of v1.12, the sample app now supports Nominatim Search and reverse geocoding via the authors CNominatim library.
  • As of v1.14, the sample app now includes support for using GPS devices which support the Windows 7 Sensors API in addition to the author's own GPSCom2 library. This functionality is provided using the author's MfcSensor library.
  • As of v1.15, the control now supports drawing with Direct2D as well as the older GDI+ graphics API. This new code provides a very good sample to developers who are looking to migrate their large GDI/GDI+ code bases to D2D as the before and after code in COSMCtrl can be compared to each other.