Ticket #43665

Torus colatitude formula documentation

Open Date: 2022-01-21 00:18 Last Update: 2022-02-01 12:17

1 - Lowest


The map_colatitude() function in server/generator/mapgen_topology.c contains a formula for torus topologies (permalink) documented only with the comment

  1. /* This projection makes poles with a shape of a quarter-circle along
  2. * "P" and the equator as a straight line along "/".
  3. *
  4. * This is explained more fully in RT 8624; the discussion can be found at
  5. * http://thread.gmane.org/gmane.games.freeciv.devel/42648 */
  6. return MAX_COLATITUDE * (1.5 * (x * x * y + x * y * y)
  7. - 0.5 * (x * x * x + y * y * y)
  8. + 1.5 * (x * x + y * y));
Since the referenced bug tracker is long dead (and not in the Wayback Machine), the Gmane link out of date (and the HTTP frontend doesn't seem to exist anymore), and – as far as I can discern – there's no actual explanation of the formula in what's left of the original discussion (at least none that I could find), this comment needs an update. For the sake of future-proofing, it would probably be prudent to put the explanation directly into a comment next to the formula this time (or at least somewhere within the repository itself).

I was able to reverse engineer the formula (with a bit of luck and a lot of trial and error):

  • The formula is lerp(1.5 (x2 + y2), (x+y)2, (x+y)), where lerp(a,b,t) = a * (1-t) + b * t is the linear interpolation function.
  • The first interpoland is 1.5 times the squared pythagorean distance from the pole
    • This gives circular lines of latitude
    • I don't know where the factor of 1.5 comes from / what it's for – I'm assuming it's compensating for something
  • The second interpoland is the squared manhattan distance from the pole
    • This gives straight lines of latitude parallel to the equator
  • The interpolation factor is the manhattan distance from the pole
    • This goes from 0 at the pole, where the pythagorean distance wins out and we get a circular polar region...
    • ...to 1 at the equator, where the manhattan distance wins out and we get straight tropics
  • The colatitude grows with the square of the distance to the poles (rather than linearly, as it does for other topologies)
    • The area within a certain distance of a pole also grows with the square of that distance (on torus maps), so the colatitude grows with the area
    • This keeps areas within a given range of colatitudes (i.e. with a given climate) relatively consistent with non-torus maps, where both colatitude and area grow linearly with distance to the pole

This leaves open two questions:

  • Do we know where exactly the formula, in particular the factor 1.5, comes from? The only thing I found in the original discussion was a text document in a weird encoding that looked promising, but didn't lead anywhere.
  • Where should we best put this documentation? I'm gravitating toward "comment in the code right next to the formula".

Ticket History (3/5 Histories)

2022-01-21 00:18 Updated by: alienvalkyrie
  • New Ticket "Torus colatitude formula documentation" created
2022-01-30 19:02 Updated by: alienvalkyrie
  • Resolution Update from None to Fixed
2022-01-30 20:03 Updated by: cazfi
  • Resolution Update from Fixed to Accepted
  • Milestone Update from (None) to 3.0.0 (closed)

It's a comment-only change, so there's no real reason not to accept it even during S3_0 code freeze, especially before RC1.

(Given the available Resolution values in osdn, we use "Accepted" to mark that the review period begins)

2022-02-01 12:17 Updated by: cazfi
  • Status Update from Open to Closed
  • Owner Update from (None) to cazfi
  • Resolution Update from Accepted to Fixed

Attachment File List


You are not logged in. I you are not logged in, your comment will be treated as an anonymous post. » Login