Update: 'Map Data' guide to new SDE format & add route calculation section

docs/guides/map-data/index.md

@@ -2,7 +2,7 @@
 
 ## General Information
 
-Map data is available in the [SDE](../../services/static-data/index.md) or through [ESI](../../services/esi/overview/).
+Map data is available in the [SDE](../../services/static-data/index.md) or through [ESI](../../services/esi/overview.md).
 Objects like regions, constellations, solarsystems, planets, moons, and other celestial bodies have a position.
 
 There are two kinds of position, each using their own coordinate system:
@@ -11,43 +11,72 @@ There are two kinds of position, each using their own coordinate system:
   The center of the cluster lies near Zarzakh, labelled "Point of No Return" on the in-game map. (See the red dot on the cluster map below)
 
 * Relative to the center of a solarsystem. (used by planets, moons, stars, as well as other positions within a solarsystem such as killmails)
-  The center of a solarsystem is it's star. Not every solarsystem has a star object; for abyssal deadspace systems with neither star nor planet, the origin is an arbitrary point.
-  Note: The star objects themselves do not have an explicit position in the SDE or ESI, as their position is always `[0.0, 0.0, 0.0]`.
+  The center of a solarsystem is it's star. The star objects themselves do not have an explicit position in the SDE or ESI, as their position is always `[0.0, 0.0, 0.0]`  
+  Not every solarsystem has a star object; for abyssal deadspace systems with neither star nor planet, the origin is an arbitrary point.
 
 These coordinate systems have the same scale (1.0 = 1 meter), but different directions.
 
 ## Universe
 
-All region (& constellations, solarsystems) share a single coordinate system. This includes the data for abyssal, wormhole-space, and void regions, though only the 'New Eden' solarsystems (`SolarSystemID` in the range `30,000,000 to 30,999,999`) are included on the in-game map.
+All regions, constellations, and solarsystems share a single coordinate system.
 
-The SDE organizes regions into folders by kind:
+The SDE contains map data in the `map`-prefixed files, such as `mapRegions`, `mapConstellations`, and `mapSolarSystems`.  
+ESI provides this data through endpoints under the `/universe/` such as [`/universe/regions/`](/api-explorer#/operations/GetUniverseRegions).
 
-* `/abyssal/`: Abyssal Deadspace, entered through abyssal filaments. (Not to be confused with Pochven)
-* `/eve/`: The New Eden Cluster, the main space of the game; Highsec, Lowsec, Nullsec. (Including Pochven)
-* `/void/`: Void Regions. Used for the tutorial & certain events.
-* `/wormhole/`: Wormhole Space.
-(The SDE also contains a `/landmarks/` folder, which contains landmark information but not regions)
-
-In ESI, the endpoints return data for all regions/constellations/systems.
-For both SDE and ESI, different kinds of space can be identified through [ID ranges](../../guides/id-ranges.md).
+For both SDE and ESI, data is provided for all kinds ('known space', 'wormhole space', 'abyssal space') of space. Different kinds of space can be identified by the [ID ranges](../../guides/id-ranges.md) for the regionID, constellationID or solarSystemID.  
+Only the 'New Eden' solarsystems (`SolarSystemID` in the range `30,000,000 to 30,999,999`) are included on the in-game map.
 
 ### Map
 
-When displayed by the in-game map & most community maps, the mapping convention is to look "top down" oriented with the region of 'Venal' at the top as a fake "Space North". In this orientation, the coordinates have the following directions:
+When displayed by the in-game map & most community maps, the mapping convention is to look "top down" oriented with the region of 'Venal' at the top as a "Space North". In this orientation, the coordinates have the following directions:
 
 * `+X` is East/Right, `-X` is West/Left.
 * `+Y` is Up, `-Y` is Down.
 * `+Z` is North/Forward, `-Z` is South/Backward
 
-Note: This forms a **Left**-Handed coordinate system. If you are using a 3D graphics or geometry library, it may expect either Left- or Right-Handed coordinates. Using incorrect handedness results in a 'mirrored' image. You can convert handedness by negating a single axis. (e.g. `[X, Y, -Z]`)
+!!! note
+
+    This forms a **Left**-Handed coordinate system. If you are using a 3D graphics or geometry library, it may expect either Left- or Right-Handed coordinates. Using incorrect handedness results in a 'mirrored' image which rotations alone cannot correct. You can convert handedness by negating a single axis. (e.g. `[X, Y, -Z]`)
 
 ![New Eden map](./cluster_map.png)
 
-Note on SDE data:
-Regions, constellations, and solarsystems each have  `max` and `min` fields denoting approximate bounding-boxes. These use a different coordinate system to the position field: The minimum and maximum `Z` values are negated. As-is the values are incorrect, and in most cases the `Z` position will not be in the range `Z_min to Z_max`, there are two workarounds:
+### Route calculation
+
+ESI provides two routes for in-game navigation. The [`/route/`](/api-explorer#/operations/GetRouteOriginDestination) endpoint generates routes closely matching the ingame route planner.
+And the [`/ui/autopilot/waypoint/`](/api-explorer#/operations/PostUiAutopilotWaypoint) endpoint enables setting the in-game autopilot destination without needing to calculate a route.
+
+When not using ESI or more fine-grained control is desired, routes can be calculated manually from map data.
+
+#### Stargate to stargate
+
+Information about how systems are connected by stargates is available through both the SDE and ESI.  
+In the SDE this data can be found in `mapStargates`.  
+In ESI each solarsystem has a list of stargates (if present), whose destination may be retrieved from the [`/universe/stargates/` endpoint](/api-explorer#/operations/GetUniverseStargatesStargateId).
+
+A graph can be constructed by taking each solarsystem as a node, and each stargate link as an edge. Each stargate of a pair linking two systems has a data entry in the SDE/ESI. These can be modelled as either a pair of edges in a directed graph, or merged into a single edge in an undirected graph.
+
+With a graph, pathfinding algorithms like Dijkstra's Algorithm can be used. Wormhole connections or player-constructed 'Ansiblex' jump gates can be added to this graph the same as stargates. While 'Ansiblex' jump gates are constructed in pairs, their access lists can be configured differently in each direction to make them one-way gates.
+
+!!! note
+
+    Route calculation may yield several alternative routes of the same (shortest) length. Some algorithms may inconsistently select between these and give different results for the same start and destination. The in-game route planner has no specific behaviour defined for this case.  
+    Routes may be also differ depending on avoidance lists, security preference, and the use of wormhole connections or player-constructed 'Ansiblex' jump gates.
+
+#### Jump drives
+
+Unlike stargate connections, jump drives can reach any valid system within range in a single jump. Jump drives allow jumping *to* any low- and nullsec system, with the exclusion of Pochven and the Jove regions. Ships can also jump *from* high-sec space into low- or nullsec.
+Jump drive range is determined by the ship the player is piloting and their 'Jump Drive Calibration' skill.
+
+A graph can be built by linking each solarsystem to every other solar system that may be jumped to.  
+For a given system<sub>1</sub> and system<sub>2</sub> and their positions (x, y, z), the systems are in jump range if:
+
+$\sqrt{\left(x_1-x_2\right)^2+\left(y_1-y_2\right)^2+\left(z_1-z_2\right)^2}\le\ (Jump\ range\ in\ LY\ \ast\ {9\,460\,000\,000\,000\,000.0})$
+
+!!! warning "Caution"
+
+    For the purposes of jump drive range calculation, a single lightyear is exactly `9,460,000,000,000,000.0` (9.46 × 10^15) meters, slightly less than the real world scientific definition of a lightyear.  
+    Using the incorrect value may cause routes to include impossible jumps.
 
-* Negate and swap z-axis `min` and `max` values; `Z_min, Z_max = -Z_max, -Z_min`
-* Negate z coordinate in positions; `Z_min < -z < Z_max` (This changes the coordinate system described above, resulting in '+Z' pointing southwards)
 
 ## Solarsystem
 
@@ -61,7 +90,9 @@ In this orientation, the coordinates have the following directions:
 * `+Y` is Up, `-Y` is Down.
 * `+Z` is North/Forward, `-Z` is South/Backward.
 
-Note: This is different with the Universe's coordinate system, and is **Right**-Handed.
+!!! note
+
+    This is different to the Universe's coordinate system, and is **Right**-Handed.
 
 ![Jita System map](./system_map.png)
 
@@ -72,15 +103,20 @@ x = x<sub>system</sub> - x<sub>planet</sub>
 y = y<sub>system</sub> + y<sub>planet</sub>
 z = z<sub>system</sub> + z<sub>planet</sub>
 
-Caution: 32-bit floating point numbers do not have enough precision to handle both the 'large' scale of the interstellar distances and the 'small' scale of interplanetary distances. This results in a loss of precision and graphical glitches on objects distant from the origin.
-This problem can be mitigated by either using 64-bit floating point numbers or by using "Floating Origin" techniques.
+!!! note "Note: Floating point precision"
+
+    32-bit floating point numbers do not have enough precision to handle both the 'large' scale of the interstellar distances and the 'small' scale of interplanetary distances when combining the position of stars and the celestial bodies orbiting them as described above.
+
+    This problem can be mitigated by using 64-bit "double precision" floating point numbers.
+
+    In in 3D rendering or other situations where 64-bit numbers are unavailable, "Floating Origin" techniques can also avoid this problem.
 
 
 ## Example: 2D map
 
 To draw a 2D map of the universe, the 3D coordinates need to be transformed into 2D positions on an image. The transformation required varies depending on the coordinate system used by the image.
 
-This example uses the common "top-left origin" coordinate system widely used in images & 2D graphics. Here the `(0,0)` origin lies in the top-left corner of the image, the X axis points right and the Y axis points **down**.
+This example uses the common "top-left origin" coordinate system widely used in images & 2D graphics. Here the `(0,0)` origin lies in the top-left corner of the image, the X axis points **right** and the Y axis points **down**.
 
 ![](./image-coordinate-system.svg)
 
@@ -99,4 +135,6 @@ A 2D solarsystem map can be drawn through the same approach, but as the X-axis p
 * X<sub>img</sub> = -X<sub>eve</sub>
 * Y<sub>img</sub> = -Z<sub>eve</sub>
 
-Tip: Use logarithmic scaling for image maps of solarsystems, as the distances between objects span several orders of magnitude.
+!!! tip
+
+    Use logarithmic scaling for maps of solarsystems, as the distances between objects span several orders of magnitude.