Classes for Working with Geo-Data

There are several classes that provide the following functions for working with geography data (geo-data):

• Setting a coordinate system (creating a geo-data entity).
• Updating a coordinate system.
• Creating a geo-map entity.
• Saving a geo-map into a drawing database.
• Changing the geo-map type and resolution, etc.

The following picture demonstrates a diagram with Geo-related classes.

This class diagram consists of core Geo-related classes and the classes of four Geo-related modules.

The main Geo-related class is OdDbGeoData. This class defines an active coordinate system (CS) and other global database Geo-related properties. It provides functions for adding a geolocation marker (one per drawing) and a background map to a drawing.

Note: A geolocation marker is drawn on each viewport if the GEOMARKERVISIBILITY system variable is set to 1.

To get the OdDbGeoData object ID, use the global oddbGetGeoDataObjId() method.

The OdDbGeoPositionMarker class represents a marker at a position with comments (not the same as a geolocation marker which is one per drawing; geoposition markers can be multiple per drawing). Geoposition markers can be moved around a geo-map.

OdDbGeoCoordinateSystem is an abstract class that represents a coordinate reference system (CRS) definition.

OdDbGeoCoordinateSystemCategory is an abstract class used for representing a category which holds string identifiers referring to a group of coordinate reference systems.

OdDbGeoCoordinateSystemTransformer is an abstract class that represents a transformer object which is used to transform points from the source CRS to the target CRS.

Protocol Extensions

For working with abstract classes, there is a set of protocol extension classes:

• OdDbGeoDataPE is an abstract class for geo-data needs. Sample implementation is in the OdGeoData module.
• OdDbGeoCoordinateSystemCategoryPE is an abstract class that contains interfaces of virtual methods used for creating coordinate system categories. Sample implementation is in the OdGeoData module in the OdDbGeoCoordinateSystemCategoryPEImpl class.
• OdDbGeoCoordinateSystemPE is an abstract class that contains interfaces of virtual methods used for creating objects that are an OdDbGeoCoordinateSystem class's inheritors. Sample implementation is in the OdGeoData module in the OdDbGeoCoordinateSystemPeImpl class.
• OdDbGeoCoordinateSystemTransformerPE is an abstract class that represents a protocol extension for a transformer object used to transform points from the source coordinate reference system to the target coordinate reference system. Sample implementation is in the OdGeoData module.
• OdDbGeoMapPE is a class for geo-map needs. Sample implementation is in the OdDbGeoMapPE module.

Modules for Working with Geo-Data

The following modules demonstrate how to work with geo-data.

OdGeoData Module

OdGeoData module implements OdDbGeoCoordinateSystemCategoryPE, OdDbGeoCoordinateSystemPE, OdDbGeoCoordinateSystemTransformerPE, and OdDbGeoDataPE classes and is located in Drawing/Extensions/OdGeoData. This module uses csmap and tinyxml libraries.

GeolocationObj Module

GeolocationObj module provides the following functions for working with geo-maps:

• Creating geo-map objects and adding them to a database.
• Rendering a drawing that contains geo-map objects.
• Changing geo-map object properties.

GeolocationObj module is located in Drawing/Examples/GeolocationObj and consists of several classes:

• OdDbGeoMap — A piece of the global map (as an image).
• OdDbGeoMapDef — OdDbGeoMap object definition.
• OdDbGeoMapPE — Protocol extensions for working with geo-map objects.
• OdDbGeoMapFieldsPE — Set/get methods for OdDbGeoMap object properties. This class is used in classes that inherit the OdDbGeoMapPE class.

GeolocationObj module implements all OdDbGeoMap methods except the updateMapImage() method because it depends on whether the OdDbGeoMapPE module is loaded.

OdDbGeoMapPE Module

OdDbGeoMapPE module implements the OdDbGeoMapPE class functionality. It is located in Drawing/Examples/OdDbGeoMapPE. The main purpose of the OdDbGeoMapPE module is implementing the updateMapImage() method for updating geo-map objects.

OdDbGeoMapPE module uses curl and tinyxml third-party libraries. The curl library is used for getting map images from the Internet (uses BING online service). To access the BING service, set your own BING-map key as a value of the sBingMapsKey global variable.

Note: The geo-data protocol extension object should be loaded for the OdDbGeoMapPE module work.

GeoCommands Module

GeoCommands module implements commands for working with geo-data listed below:

• Geo command creates geo-data by specified coordinate system.
• GeoRemove command removes geo-data from file.
• GeoReorientMarker command reorients geo-data marker.
• GeoMap command changes the geo-map type for the current viewport (defined by GEOMAP variable).
• GeoMapImage command creates the geo-map.
• GeoMapImageSetMapType command changes the geo-map type of the created geo-map.
• GeoMapImageSetResolution command changes the geo-map resolution.
• GeoMapImageUpdate command updates the geo-map.

The GeoCommands module is located in Drawing/Examples/GeoCommands.

Third-Party Libraries for Working with Geo-Data

The third-party libraries, used in the OdGeoData and OdDbGeoMapPE modules, are located in the ThirdParty folder:

• The csmap library implements coordinate system support and calculations.
• The curl library implements geo-map image updating.
• The tinyxml library is used for working with .xml-files.

A drawing that represents the results of GeolocationObj, OdGeoData, and OdDbGeoMapPE modules is below.

The background map comes from geo-data (geo-data drawing not implemented yet). The white border map is the OdDbGeoMap object. The red marker is a geolocation marker. The yellow marker is a geo-position marker.

Coordinate System Dictionaries

The csmap library should have access to a folder with the required dictionaries. The dictionaries are available for downloading from https://www.opendesign.com/odoutgoing/LatestRelease/. The dictionaries from the most recent release work with any Drawings SDK version.

To download and set up the dictionaries, follow the steps below:

1. Navigate to the most recent release folder in the ODA Downloads area: https://www.opendesign.com/odoutgoing/LatestRelease/.
2. Open the Thirdparty folder and download CSDicts_<release_version>.zip archive.
3. Unzip the archive.
4. Set the MENTOR_DICTIONARY_PATH or CS_MAP_DIR environment variables pointing to the CSDicts folder. On Windows, you can alternatively create the CSDicts folder in the application directory (for example, exe\vc9dlldbg\CSDicts) and copy the dictionary files to it.
5. If you want to use user dictionaries, set the MENTOR_USER_DICTIONARY_PATH variable pointing to the user dictionary directory. On Windows, you can alternatively create the CSUserDicts folder in the application directory (for example, exe\vc9dlldbg\CSUserDicts).

For ODA members who have access to the Drawings Git repository, the dictionary files are also available in the main/ThirdParty/csmap/Dictionaries directory.

Sample code of working with geo-data

Sample code that illustrates how to work with geo-data can be found in:

• DbFiller::addGeoStuff() method of the OdWriteEx example
• GeoMarkPosition command in the ExCommands module.