Have you ever tried to save or send a position on the map with your addon? You might have noticed that this is not as easy as it sounds.
This library efficiently converts a position on any map into a global position that you can save or share. This is made possible by measuring maps once when they are encountered for the first time during a play session and only doing simple calculations afterwards.

Dependencies
Make sure to install the following required libraries in order to use LibGPS.

• LibMapPing - Simplifies creating waypoints for measuring maps
• LibDebugLogger - Extensive logging for debug purposes
• LibChatMessage - Simplifies displaying chat messages

Quick Start
Add the necessary statements in your addon manifest to load the files:
NOTE: The >=30 tells the game to require AddOnVersion 30 or greater, which happens to be the first version with the 3.0 API and has nothing to do with the semantic version. It is simply a build number provided by the build script used to package the library.

In order to use the library you have to get an instance from the global variable:
Next you can convert a position on the currently active map into a global position on the Tamriel map by calling LocalToGlobal.
For example you can convert the local player position into a global position with the following line of code:
The resulting x and y can be saved, sent or whatever else you want to do with it.
NOTE: For some locations the global coordinates can be outside the bounds for normalized coordinates, for example Coldharbour has negative x coordinates as it is to the left of Tamriel in the global coordinate space.

After you have loaded or received a global position you just need to call GlobalToLocal to get the position on the current map.


Migrating from LibGPS2
LibGPS3 offers full backwards compatibility to LibGPS2 (see compatibility.lua), but it's still highly recommended to migrate to the new API.
In order to use the new API, simply access the library via the "LibGPS3" global variable instead of "LibGPS2" or LibStub.
Most functions stayed the same between v2 and v3, but there are a few breaking changes. The following list shows how to migrate those cases.

Renamed functions
Some function names have been changed to better reflect the return value.

• ClearCurrentMapMeasurements -> ClearCurrentMapMeasurement
• GetCurrentMapMeasurements -> GetCurrentMapMeasurement
• CalculateMapMeasurements -> CalculateMapMeasurement

Measurement object
GetCurrentMapMeasurement now returns an object with some convenience methods instead of a plain table. See the description below in the API reference for details on what it can do.

LocalToGlobal
The mapIndex return value has been removed as our understanding of what a map is has changed and it was deemed unnecessary for most use cases.
If you still need it, you can use GetCurrentMapMeasurement() to fetch the measurement object and retrieve it from there.

ZoneToGlobal
This method was used a long time ago to offer a way to migrate LibGPS1 coordinates. Since then it has become effectivly unnecessary and only causes confusion. As such it has been removed without replacement.

PanToMapPosition
This has become easily possible via ingame functionality since the time it was initially added to the library. Simply use "ZO_WorldMap_GetPanAndZoom():PanToNormalizedPosition(x, y)" instead.

OnLibGPS2MeasurementChanged callback
There is now a constant LIB_EVENT_STATE_CHANGED for the callback name, which should be used instead of the plain string.



API Reference
Here is a complete list of the functionality that is provided by LibGPS:

IsReady
Returns true as long as the player exists.
IsMeasuring
Returns true if the library is currently doing any measurements.
ClearMapMeasurements
Removes all cached measurement values.
ClearCurrentMapMeasurement
Removes the cached measurement for the map that is currently active.
GetCurrentMapMeasurement
Returns a measurement object for the active map or nil if the measurement could not be calculated for some reason.
See the description of the Measurement object for details.
GetMapMeasurementByMapId
Returns a measurement object for the requested map id or nil if the measurement could not be calculated for some reason.
See the description of the Measurement object for details.
GetCurrentMapParentZoneIndices
Returns the mapIndex, zoneIndex and zoneId of the parent zone for the currently set map.
CalculateMapMeasurement
Calculates the measurement for the current map and all parent maps.
This method does nothing if there is already a cached measurement for the active map.
Returns a boolean to indicate if the measurement was successful and a SetMapResultCode indicating if the map has changed independently of the actual result of the measurement.
LocalToGlobal
Converts the given map coordinates on the current map into coordinates on the Tamriel map.
Returns x and y on the world map or nil if the measurements of the active map are not available.
GlobalToLocal
Converts the given global coordinates into a position on the active map.
Returns x and y on the current map or nil if the measurements of the active map are not available.
SetPlayerChoseCurrentMap
This function sets the current map as player chosen so it won't snap back to the previous map.
SetMapToRootMap
Sets the best matching root map on the given global position: Tamriel, Cold Harbour or Clockwork City and what ever will come.
Returns SET_MAP_RESULT_FAILED, SET_MAP_RESULT_MAP_CHANGED depending on the result of the API calls.
MapZoomInMax
Repeatedly calls ProcessMapClick on the given global position starting on the root map (using the function above) until nothing more would happen.
Returns SET_MAP_RESULT_FAILED, SET_MAP_RESULT_MAP_CHANGED or SET_MAP_RESULT_CURRENT_MAP_UNCHANGED depending on the result of the API calls.
PushCurrentMap
This function stores information about how to return to the current map on a stack.
PopCurrentMap
Switches to the last map that was put on the stack.
Returns SET_MAP_RESULT_FAILED, SET_MAP_RESULT_MAP_CHANGED or SET_MAP_RESULT_CURRENT_MAP_UNCHANGED depending on the result of the API calls.
GetCurrentWorldSize
Returns the current size of Tamriel in world-units.
GetLocalDistanceInMeters
Returns the distance in meters of given local coords.
GetGlobalDistanceInMeters
Returns the distance in meters of given global coords.
GetWorldGlobalRatio
Returns how much greater the level is compared to its size on the map.
GetGlobalWorldRatio
Returns how much smaller global scaled values must be to fit the current level.
lib.LIB_EVENT_STATE_CHANGED
This callback is fired on the global CALLBACK_MANAGER when a map measurement begins or ends and passes the same value as lib:IsMeasuring().
If you have a custom handler for player waypoints in EVENT_MAP_PING you may want to ignore these events while a measurement is active.


Measurement
This object returned by GetCurrentMapMeasurement() contains all the data about a map measurement and offers some convenience functions to interact with them.

GetId
Returns a unique id for the measurement which is used to store it in the saved variables. Details are implementation specific and may change between versions.
GetMapIndex
Returns the mapIndex or nil if the measured map doesn't have one.
GetZoneId
Returns the zoneId for the measurement. Keep in mind that a map can have multiple zoneIds within its borders and a zoneId can also span multiple maps.
GetScale
Returns the scale in the global coordinate space for the current map.
GetOffset
Returns the offset in the global coordinate space for the current map.
IsValid
Returns true if the measurement contains valid data.
ToGlobal
Converts and returns global coordinates for a given local coordinate pair. Used by LocalToGlobal.
ToLocal
Converts and returns local coordinates for a given global coordinate pair. Used by GlobalToLocal.
GetCenter
Returns the center of the measured map as global coordinates.
Contains
Returns true if the given global coordinates are inside the measured map.