Category: programming

Note: This is the first release of TopoLib using V9.0.0 of Proj, accessed via SharpProj 9.0.157

Topographical MS Excel extension library (*.xll) with routines for Coordinate Conversion and Transformation, built using Proj, SharpProj and Excel-DNA.

TopoLib contains a number of User Defined Functions (UDFs) for Coordinate Conversion and Transformation, supported by Ribbon commands and dialogs, made available as an Excel extension. The code is based on a number of open source libraries, that are all available for download on GitHub. The source code is made available under the ZLib license.

---

TopoLib is based on PROJ, which is generic coordinate transformation software that transforms geospatial coordinates from one coordinate reference system (CRS) to another. This includes cartographic projections as well as geodetic transformations.

PROJ started purely as a cartography application letting users convert geodetic coordinates into projected coordinates using a number of different cartographic projections. Over the years, as the need has become apparent, support for datum shifts has slowly worked its way into PROJ as well. Today PROJ supports more than a hundred different map projections and can transform coordinates between datums using all but the most obscure geodetic techniques.

PROJ is widely used in the industry, for instance QGIS, depends on it. QGIS is a very well established Open Source Geographic Information System.

PROJ is written in (unmanaged) C++ code, whereas Excel-DNA that provides the interface with Excel is written in (managed) C#.

To bring the two together, an intermediate layer (interface) is provided by SharpProj, which is written in C++/CLI. As Proj has been statically linked to SharpProj, only one additional DLL (SharpProj.dll) is required next to the TopoLib XLL file.

---

The library now contains the following function categories:

CCT – Coordinate Conversion and Transformation Functions
CFG – Configuration Functions
CRS – Coordinate Reference System Functions
DEG – Angle related Functions
ENV – Environment Functions
GPS – GPS String Export Functions
LIB – Library Functions
LOG – Logging Functions
Add-In commands (from the TopoLib Ribbon interface)

An example of a function name is: TL.lib.VersionInfo()

See below for a complete function listing. All functions are equipped with context sensitive help, which is contained in the compiled help file TopoLib.chm.

---

CCT – Coordinate Conversion and Transformation Functions

TL.cct.Accuracy
TL.cct.ApplyForward
TL.cct.ApplyInverse
TL.cct.AsJsonString
TL.cct.AsProjString
TL.cct.AsWktString
TL.cct.CreateForward
TL.cct.CreateInverse
TL.cct.Grids.Count
TL.cct.Grids.FullName
TL.cct.Grids.IsAvailable
TL.cct.Grids.Name
TL.cct.HasBallParkTransformation
TL.cct.HasInverse
TL.cct.Identifiers.Authority
TL.cct.Identifiers.Code
TL.cct.Identifiers.Count
TL.cct.IsAvailable
TL.cct.MethodName
TL.cct.Name
TL.cct.Remarks
TL.cct.RoundTrip
TL.cct.Scope
TL.cct.SourceCRS
TL.cct.Steps.Count
TL.cct.Steps.CreateForward
TL.cct.Steps.CreateInverse
TL.cct.Steps.MethodName
TL.cct.Steps.Name
TL.cct.TargetCRS
TL.cct.Transforms.Count
TL.cct.Transforms.CreateForward
TL.cct.Transforms.CreateInverse
TL.cct.Transforms.ListAll
TL.cct.Type
TL.cct.UsageArea.Center
TL.cct.UsageArea.Center.X
TL.cct.UsageArea.Center.Y
TL.cct.UsageArea.EastLongitude
TL.cct.UsageArea.MaxX
TL.cct.UsageArea.MaxY
TL.cct.UsageArea.MinX
TL.cct.UsageArea.MinY
TL.cct.UsageArea.Name
TL.cct.UsageArea.NorthLatitude
TL.cct.UsageArea.SouthLatitude
TL.cct.UsageArea.WestLongitude

CFG – Configuration Functions

TL.cfg.AddOrUpdateKey
TL.cfg.ClearAllKeys
TL.cfg.GetKeyValue
TL.cfg.ReadAllKeys
TL.cfg.ReadKey
TL.cfg.RemoveKey

CRS – Coordinate Reference System Functions

TL.crs.AsJsonString
TL.crs.AsProjString
TL.crs.AsWktString
TL.crs.Axis.Abbreviation
TL.crs.Axis.Count
TL.crs.Axis.Direction
TL.crs.Axis.Name
TL.crs.Axis.UnitAuthName
TL.crs.Axis.UnitCode
TL.crs.Axis.UnitConversionFactor
TL.crs.Axis.UnitName
TL.crs.CelestialBodyName
TL.crs.CoordinateSystem.Axis.Abbreviation
TL.crs.CoordinateSystem.Axis.Count
TL.crs.CoordinateSystem.Axis.Direction
TL.crs.CoordinateSystem.Axis.Name
TL.crs.CoordinateSystem.Axis.UnitAuthName
TL.crs.CoordinateSystem.Axis.UnitCode
TL.crs.CoordinateSystem.Axis.UnitConversionFactor
TL.crs.CoordinateSystem.Axis.UnitName
TL.crs.CoordinateSystem.CoordinateSystemType
TL.crs.CoordinateSystem.Name
TL.crs.CoordinateSystem.Type
TL.crs.Datum.Name
TL.crs.Datum.Type
TL.crs.Ellipsoid.InverseFlattening
TL.crs.Ellipsoid.IsSemiMinorComputed
TL.crs.Ellipsoid.Name
TL.crs.Ellipsoid.SemiMajorMetre
TL.crs.Ellipsoid.SemiMinorMetre
TL.crs.Ellipsoid.Type
TL.crs.EuclideanArea
TL.crs.EuclideanDistance
TL.crs.EuclideanDistanceZ
TL.crs.GeodesicArea
TL.crs.GeodesicDistance
TL.crs.GeodesicDistanceZ
TL.crs.GeodeticCRS.Name
TL.crs.GeodeticCRS.Type
TL.crs.Identifiers.Authority
TL.crs.Identifiers.Code
TL.crs.Identifiers.Count
TL.crs.IsDeprecated
TL.crs.IsEquivalentTo
TL.crs.IsEquivalentToRelaxed
TL.crs.Name
TL.crs.PrimeMeridian.Longitude
TL.crs.PrimeMeridian.Name
TL.crs.PrimeMeridian.UnitConversionFactor
TL.crs.PrimeMeridian.UnitName
TL.crs.Remarks
TL.crs.Scope
TL.crs.Type
TL.crs.UsageArea.Center
TL.crs.UsageArea.Center.HasValues
TL.crs.UsageArea.Center.X
TL.crs.UsageArea.Center.Y
TL.crs.UsageArea.EastLongitude
TL.crs.UsageArea.MaxX
TL.crs.UsageArea.MaxY
TL.crs.UsageArea.MinX
TL.crs.UsageArea.MinY
TL.crs.UsageArea.Name
TL.crs.UsageArea.NorthLatitude
TL.crs.UsageArea.SouthLatitude
TL.crs.UsageArea.WestLongitude

DEG – Angle related Functions

TL.deg.AsString
TL.deg.FromDmsValues
TL.deg.FromDmValues
TL.deg.FromRadians
TL.deg.FromString
TL.deg.GetDecimalMinutes
TL.deg.GetHours
TL.deg.GetMinutes
TL.deg.GetSeconds
TL.deg.IsWithin0to360
TL.deg.IsWithin180to180
TL.deg.IsWithin90to90
TL.deg.Normalize0to360
TL.deg.Normalize180to180
TL.deg.ToRadians

ENV – Environment Functions

TL.env.GetEnvironmentVariable
TL.env.GetEnvironmentVariableValue
TL.env.SetEnvironmentVariable

GPS – GPS String Export Functions

TL.gps.AsGpxTracks
TL.gps.AsKmlTracks

LIB – Library Functions

TL.lib.DynamicArraysSupported
TL.lib.GridCacheLocation
TL.lib.InstallationPath
TL.lib.LoggingLevel
TL.lib.OperatingSystem
TL.lib.VersionInfo
TL.lib.Volatile

LOG – Logging Functions

TL.log.Debug
TL.log.Error
TL.log.Verbose

TopoLib Add-In Commands (accessible from the Ribbon)

Command_Recalculate_Transforms
Command_Show_HelpFile
Dialog_About_TopoLib
Dialog_Cache_Settings
Dialog_Export_GPX_data
Dialog_Export_KML_data
Dialog_Export_Wizard
Dialog_Log_Settings
Dialog_Resource_Settings
Dialog_TopoLib_Version
Dialog_Transform_Settings