From 467f13e34742591cec964d5c660fa5ad98c4d835 Mon Sep 17 00:00:00 2001 From: SentientTurtle <3841257+SentientTurtle@users.noreply.github.com> Date: Mon, 29 Sep 2025 02:32:46 +0200 Subject: [PATCH 1/6] UPDATE: Map data guide now matches new SDE format & added route section --- docs/guides/map-data/index.md | 86 +++++++++++++++++++++++++---------- 1 file changed, 62 insertions(+), 24 deletions(-) diff --git a/docs/guides/map-data/index.md b/docs/guides/map-data/index.md index 2290b75..0538c94 100644 --- a/docs/guides/map-data/index.md +++ b/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,74 @@ 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. For A\*, the distance between solarsystems can be used as a heuristic, but this may yield different or suboptimal results. + +Wormhole connections or player-constructed 'Ansiblex' jump gates can be added to this graph the same as stargates. Information about both of these connections is not available through the API. + +!!! 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 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 system1 and system2 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 +92,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 +105,18 @@ x = xsystem - xplanet y = ysystem + yplanet z = zsystem + zplanet -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 + + 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 using 64-bit floating point numbers in rendering or using "Floating Origin" techniques if your graphics API only supports 32-bit rendering. ## 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 * Ximg = -Xeve * Yimg = -Zeve -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. From 692897ecbb8c61a54b67c20b64d76a8638c28df1 Mon Sep 17 00:00:00 2001 From: SentientTurtle <3841257+SentientTurtle@users.noreply.github.com> Date: Mon, 29 Sep 2025 03:02:58 +0200 Subject: [PATCH 2/6] Fix: Thousands separator in formula on 'map data' guide --- docs/guides/map-data/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/map-data/index.md b/docs/guides/map-data/index.md index 0538c94..c701025 100644 --- a/docs/guides/map-data/index.md +++ b/docs/guides/map-data/index.md @@ -72,7 +72,7 @@ Jump drive range is determined by the ship the player is piloting and their 'Jum A graph can be built by linking each solarsystem to every other solar system that may be jumped to. For a given system1 and system2 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})$ +$\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" From b7720dd33b7088ca0fece6108c8fb613d2912546 Mon Sep 17 00:00:00 2001 From: SentientTurtle <3841257+SentientTurtle@users.noreply.github.com> Date: Mon, 29 Sep 2025 11:51:18 +0200 Subject: [PATCH 3/6] Update docs/guides/map-data/index.md Co-authored-by: Patric Stout (CCP Games) --- docs/guides/map-data/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/map-data/index.md b/docs/guides/map-data/index.md index c701025..697d0fb 100644 --- a/docs/guides/map-data/index.md +++ b/docs/guides/map-data/index.md @@ -62,7 +62,7 @@ Wormhole connections or player-constructed 'Ansiblex' jump gates can be added to !!! 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 jump gates. + Routes may be also differ depending on avoidance lists, security preference, and the use of wormhole connections or player-constructed 'Ansiblex'. #### Jump drives From 4d9b2f88173464ae27ddee382752b56840f5d0d5 Mon Sep 17 00:00:00 2001 From: SentientTurtle <3841257+SentientTurtle@users.noreply.github.com> Date: Mon, 29 Sep 2025 12:44:02 +0200 Subject: [PATCH 4/6] Applied suggestions from https://github.com/esi/esi-docs/pull/227 --- docs/guides/map-data/index.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/guides/map-data/index.md b/docs/guides/map-data/index.md index 697d0fb..1f4f848 100644 --- a/docs/guides/map-data/index.md +++ b/docs/guides/map-data/index.md @@ -55,14 +55,12 @@ In ESI each solarsystem has a list of stargates (if present), whose destination 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. For A\*, the distance between solarsystems can be used as a heuristic, but this may yield different or suboptimal results. - -Wormhole connections or player-constructed 'Ansiblex' jump gates can be added to this graph the same as stargates. Information about both of these connections is not available through the API. +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'. + 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 From e0aa2729af9530cadf3e9516847117e1833dc62c Mon Sep 17 00:00:00 2001 From: SentientTurtle <3841257+SentientTurtle@users.noreply.github.com> Date: Mon, 29 Sep 2025 14:11:52 +0200 Subject: [PATCH 5/6] Tweaked phrasing of 32-bit float warning --- docs/guides/map-data/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/guides/map-data/index.md b/docs/guides/map-data/index.md index 1f4f848..ee4e40a 100644 --- a/docs/guides/map-data/index.md +++ b/docs/guides/map-data/index.md @@ -103,11 +103,13 @@ x = xsystem - xplanet y = ysystem + yplanet z = zsystem + zplanet -!!! note - - 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. +!!! note "Note: Floating point precision" - This problem can be mitigated by using 64-bit floating point numbers in rendering or using "Floating Origin" techniques if your graphics API only supports 32-bit rendering. + 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 From 83e3344d60ba78685cc49f31b1384834981c5772 Mon Sep 17 00:00:00 2001 From: SentientTurtle <3841257+SentientTurtle@users.noreply.github.com> Date: Mon, 29 Sep 2025 19:32:43 +0200 Subject: [PATCH 6/6] Update index.md --- docs/guides/map-data/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/map-data/index.md b/docs/guides/map-data/index.md index ee4e40a..0d2e123 100644 --- a/docs/guides/map-data/index.md +++ b/docs/guides/map-data/index.md @@ -109,7 +109,7 @@ z = zsystem + zplanet 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. + In 3D rendering or other situations where 64-bit numbers are unavailable, "Floating Origin" techniques can also mitigate this problem. ## Example: 2D map