jkunimune / map-projections

A suite of programs to create custom maps of the Earth's surface.

Map-Projections

A class to create custom maps of the Earth's surface. There are thousands of combinations of color-schemes, projections, and aspects. Includes Mercator, Gall-Peters, Orthographic, Peirce Quincuncial, and More!

Running the programs

There are three main programs here:

• MapDesignerRaster.jar – The original program. Create custom oblique raster images of the Earth's surface using a variety of algorithms called projections.
• MapDesignerVector.jar – The same idea, but working in vector images instead in case you want to cut a vinyl sticker or something.
• MapAnalyzer.jar – See graphs and figures quantifying the amount of scale and angular distortion present in each map projection.

They all have similar layouts that let you select an input equirectangular map, a projection, an aspect (where the North Pole is situated with respect to the map), and parameters if applicable. Go crazy! There are a practically unlimited number of combinations.

I will note that while I think the interface is mostly intuitive, there are a couple of things where I never got around to making the proper GUI elements, so you won't be able to figure out on your own. The first is the fact that the graticule checkbox, available on Map Designer Raster, draws its formatting information from a file called graticule.txt in the input folder. If you're fine with the default styling, or if you don't use that checkbox, don't worry about it. But if you do use that checkbox, know that you can alter the color and width of the lines by editing that file.

The twoth is the existence of truncated inputs. If you load an input map with the word "octant" in the filename (all lowercase), then the program will load it into the octant bounded by 0°N, 90°N, 0°E, and 90°E. This is useful if you have very large inputs and/or memory constraints. The output will still be sized as though the entire map were there, unless it's a projection that doesn't show the entire globe ("Cahill–Keyes (single octant)" does not show the entire globe and is in fact specifically designed to work with this feature.)

Running by double-clicking

If you are a fancy Windows user, I recommend the convenient fancy Windows binaries. Download the EXE files, find them in your downloads folder, double-click to install, and then keep pressing buttons until something good happens. If you see a map, you're in the right place.

Running from the command line

If you are not on Windows or are otherwise not fancy enough to deserve such binaries, there are also equivalent .jar files in the main directory. For that, you'll need to download and install Java. You can use any version 8 or higher. Once you've installed it, you can download the source code, unzip it, and navigate to the resulting directory in a command line window. If the Java you installed is Java 8, you can run the programs with the following command:

java -jar MapDesignerRaster.jar

Change the filename at the end accordingly, of course.

If you have Java 9 or higher, that's fine too, but you'll need to also install JavaFX. Make sure you get the SDK JavaFX, not the Jmods JavaFX. The version number doesn't matter. Once you've unzipped JavaFX into some directory – let’s say, for example, /home/jkunimune/javafx-sdk-17 – then you can run the programs with the following command:

java --module-path '/home/jkunimune/javafx-sdk-17/lib' --add-modules javafx.controls,javafx.swing -jar MapDesignerRaster.jar

I think this syntax might be somewhat platform dependent, but I can’t really remember. If you’re having problems, try forward slashes instead of backslashes or double quotes instead of single quotes.

Building from source

If you want to edit the code, or use some of the deeper functionality not meant for mass consumption, you can also compile and run the Java source code. In addition to three .java files corresponding to the three executables, there are also these runnable scripts:

• MapPlotter.java – Plot a large group of map projections by the amount of distortion they produce.
• src/app/MapOptimizer.java – Run gradient descent on parametric projections to minimize their distortion.
• src/app/MapExplainer.java – Generate an HTML blurb outlining and displaying every map projection.
• src/app/MapConverter.java – Generate a bunch of maps in one projection from a bunch of input images.

To run these, you’ll need to install some dependencies in addition to JavaFX as mentioned above; you can get them as .jar files:

• Apache Commons Mathematics Library (you can just download and unzip the whole thing)
• Java Tools for Experimental Mathematics "ellipticFunctions" package (you only need "ellipticFunctions.jar" and "mfc.jar")

Once you have those and put them in, for example, /home/jkunimune/apache and /home/jkunimune/jtem, you can compile and run with

javac --module-path '/home/jkunimune/javafx-sdk-17/lib:/home/jkunimune/apache/commons-math3-3.6.1.jar:/home/jkunimune/jtem' --add-modules javafx.controls,javafx.swing,ellipticFunctions --source-path=src src/apps/MapPlotter.java
java --class-path '/home/jkunimune/javafx-sdk-17/lib/javafx.controls.jar:/home/jkunimune/javafx-sdk-17/lib/javafx.swing.jar:/home/jkunimune/apache/commons-math3-3.6.1.jar:/home/jkunimune/jtem/ellipticFunctions.jar:src' apps.MapPlotter

As with running the .jar file, the syntax might be somewhat platform-dependent; the colons might need to be semicolons, for example.

To build the JAR and EXE files, you use the Ant file build.xml. I don't know what commands are used for that; IntelliJ IDEA does it for me. The main trick here is you must use the Java 8 JDK because the tool I use, Javapackager, was dropped in Java 9. If you use Javapackager in conjunction with a newer JDK, it will seem to work at first, but the resulting EXEs won't run. You may have to put javapackager.exe in your path and install the WiX Toolset 4 and Inno Setup 5 (not Inno Setup 6!). Javapackager does often have problems but doesn't have useful error messages (every failure mode appears to be "builder did not produce a bundle"), so I apologize about that. Make sure you set the directories at the top of the file according to your file system, make sure the compiled Java is in the bin/ directory, make sure none of the jar files have restricted read access or are being used by any other programs.

There are also some Python files used to generate SVG inputs for MapDesignerVector in the src/zupplemental directory. To run those, you'll need a few packages from PyPI. Just install Python 3 and pip, and then call the following from a command line (or use Anaconda or something, I don't know. Up to you).

pip3 install numpy pyshp shapely

Note that compose_maps.py requires input data from naturalearthdata.com, which should be downloaded and placed in src/zupplemental/shapefiles/. You can either put the zip file in there or extract the individual files and put them in; it works either way. I don't have a complete list of what data files are needed, so I usually just run it and look at the error message to see what it wants me to download. You can alternatively scroll through compose_maps.py to see what files it references (anything that starts with "ne_" is the name of a Natural Earth dataset).

Wherefore?

While maps of the world are often perceived as authoritative sources of information, in reality, any image that represents the Earth's surface on a plane is inherently wrong. This is because the Earth's surface cannot all be viewed at the same time, either on a sphere or on any isometric transformation of a sphere, unless one is willing to distort the features in the map to make them all lie flat. This is the impetus for the map projection – any technique by which geographic features on the map may be represented on a computer screen or on a piece of paper. For localized maps, it doesn't make much of a difference, but the larger the mapped area the more the distortion will become aparent, depending on which projection you use. Hundreds have been invented over the past two thousand years. Some distort areas, some distort angles, and some distort both. Some are widely used, some are hotly debated, and some are only known to a select few corners of the internet. The goal of this program is to gather and categorize them, not only for the sake of learning about them (the collection at map-projections.net is far more comprehensive than mine if that's your aim) but also for the sake of using to display arbitrary data. And in oblique aspects!

For some examples, check out the output folder (all were created with this program but some also involved some postprocessing in paint.net). For more information, go to jkunimune.github.io/Map-Projections.

Credits

While I wrote all of the code in this repository myself, and I created several of the simpler images from scratch, other people did help. Here's a comprehensive list.

• The NASA for Basic.png, Large.jpg, and Altitude.png,
• Tom Patterson for Clouds.jpg, Rivers.png,
• Natural Earth for Pastel.png and their detailed vector data,
• The Apache Commons for their complex mathematics code,
• Technische Universität Berlin for their complex mathematics code,
• Gene Keyes for his impressively in-depth documentation of his map projection,
• Robert Gray for his research on Buckminster Fuller's map projection,
• AuthaGraph Co., Ltd. for their vague information about their map projection,
• Wikipedia for its substantial collection of map projection information and equations, and
• John P. Snyder for his even more substantial collection of map projection information and equations.

map-projections's Issues

ubiquitous Shapefile or modern geojson support for vector input?

While svg is the vector output of browser rendering, do you plan to support SHP and GeoJSON? they are more prevalent as datasource format.

Can I have the parameters for "The Map to End All Maps" and "Jurusalem" maps?

Please share. They are awesome!

edit: I noticed The Jerusalem is "Perice Quincuncial" with your "Jesuralem" preset.
Could you inform "The Map to End All Maps" one, if you still have it?

Increase the resolution size of outputs images

Hello
a big thank you for this great software

the only annoying thing is the limitation of the size of the generated image... it is limited to 10000x5000 pixels (approx.)

It prevents me from generating very detailed maps... please can you increase the size of the renderings (a size of 30000 pixels would be fine)

Thanks to you

Add country border/names

Add an option to show country borders and names

Java Linux Noob - I am having trouble running the code.

java version: javac 11.0.18

I cloned the master repository and installed java-sdk.

Then in the cloned directory, I ran:

javac MapAnalyzer.jar

and received this error:

Class names, 'MapAnalyzer.jar', are only accepted if annotation processing is explicitly requested

I tested java MapAnalyzer.jar and received another error.

Error: Could not find or load main class MapDesignerRaster.jar

Also, in the instructions, it says there are: (4 py files)

generate_coastlines.py – Generate an SVG string outlining the continents, islands, and major lakes of the world, to be used as vector input.
generate_graticule.py – Generate an SVG string displaying a map graticule, to be used as vector input.
generate_indicatrices.py – Generate an SVG string outlining an array of Tissot's indiatrices of distortion, to be used as vector input.
generate_orthodromes.py – Generate a mesh of orthodromes in an Equirectangular projection, to be used as vector input.

These files do not exist in the most recent release or the master repository.

Equations for AuthaGraph

Hello,
great work. I did not found the equations for the AuthaGraph representation. Could point me out to them? Thanks.

Is it possible to increase count of gores?

Great product, however when I try to make layout for big globe, it looks like 12 gores is not enough. Can you explain please, how to increase count of gores for vector maps?

New Authagraph map works well if all corners are in the ocean

I think you could create an even better map, if you position all the 4 corners of the tetrahedron in water. There is no need to put one corner at the North pole, which distorts Siberia quite strong

Modifying the graticule

Hello,

I think it would be great if you could modify the line color and width of the graticule that MapDesignerRaster is drawing. Depending on the input image you’re projecting, the white lines can be almost invisible – and depending on the size of the exported image, the lines may be too thin (on very large images) or too thick (and small images).

The most convenient thing would be input fields within the applications’ main windows, but I also would be fine with a CSS file (or a JSON file, or a plain text .inf file or whatever) which is parsed when you hit the "Update Map" button and right before rendering the exported image.

Kind regards,
Tobias Jung

one octanct of waterman butterfly includes a rendering error

I use openjdk 22 2024-03-19 on a linux machine, with javafx-sdk-22.0.1 and the recent map-projections release.
All implemented waterman butterfly projections produce rendering errors as marked in the attached image, where a part of the map is repeated with a small offset.

Broken link in README.md

I think there is a broken link in Wherefore? section of the README. I suspect the broken link https://jkunimune15.github.io/Map-Projections should be replaced with https://jkunimune.github.io/Map-Projections - is that right?

Invalid SVG output for non-English localisation settings

Witnessed behaviour:

• If the Windows (11 22H2) Regional format settings (Settings -> Time & Language -> Language & region) are set to a localisation using the comma as decimal separator (as is the case for many languages other than English), MapDesignerVector outputs invalid svg files since the dots in coordinates are replaced by commas. E.g. the coordinate pair 123.456, 987.654 is transformed into the invalid SVG sequence 123,456, 987,654. See attached file for an example output:

Expected behaviour:

• Valid .svg files are output irrespective of the user's localisation settings. In other words, the float(?) to string conversion should be configured to use a dot as the decimal separator in all cases.

Steps to reproduce:

• Set Settings->Time & Language->Language & region->Regional format settings to a language using a comma as decimal separator (tested with Dutch (Netherlands)).
• Start MapDesignerVector.exe and save any .svg file.
• Open the resulting .svg file in any .svg viewer, or a text editor to inspect its code.

Confused about your implementation of Lee's solution to Dixon's elliptic functions

Recently I've become interested in Lee's conformal world in a tetrahedron projection. I've also been wanting to start getting experience with java, so I was drawn to this repo. I noticed that you wrote the wiki article for this projection, so you seem to be the right person to talk to about this.

For several reasons, I can't quite wrap my head around your implementation of Lee's approximation to Dixon's elliptic functions. I was hoping you would help me understand some things.

I've reproduced this projection with MapDesignerRaster.jar and obviously your implementation succeeds. My confusion probably stems from unfamiliarity with Java, or some math misunderstanding.

Things I'm confused about:

coefficients are all positive (not alternating sign)

In Lee's paper, the coefficients to the MacLaurin series alternate in sign like this:

+0.625000
-0.223214
+0.069754
-0.020121
...

but in your implementation, they're all positive. I'm not seeing how negatives could be alternatingly introduced in this line of code:

sum = sum.times(w3).plus(COEF[i]);

w³ taken initially and not updated after each iteration of converging series

In the following block of code:

public static Complex leeFunc(Complex w) {
    Complex w3 = w.pow(3);
    Complex sum = new Complex(0);
    for (int i = COEF.length-1; i >= 0; i --)
        sum = sum.times(w3).plus(COEF[i]);
    return sum.times(w);
}

w³ is computed before the iterative process, but then never updated. Although Lee didn't say this explicitly, he seemed to heavily imply that every iteration should add the coefficient times the current best estimate of w³

Iterative process starts with least significant term and goes backwards.

In Lee's paper, higher order coefficients (further down on the list) accumulate more powers of w, but your process (above code, for loop) seems to start at the end of the coefficients and then tack on powers of w for lower order (higher up on the list) terms. What I mean is that yours will look like this (I'm ignoring powers of 10^-1 for now):

+0.625000 * w¹³
-0.223214 * w¹⁰
+0.069754 * w⁷
-0.020121 * w⁴

when it should look like this:

+0.625000 * w⁴
-0.223214 * w⁷
+0.069754 * w¹⁰
-0.020121 * w¹³

Lee says to multiple by w³ * 10^-1 in each iteration, so the powers of 10^-1 are taken care of. I wrote an implementation in python that should be correct:

import numpy as np
COEF = [
    .625000,
   -.223214,
    .069754,
   -.020121,
    .005539,
   -.001477,
    .000385,
   -.000099,
    .000025
    ]
def leeFunc(alpha, sigma):
    w = 1.791797 * np.tan(sigma/2) * np.exp(alpha * 1j)
    for coef in COEF:
        print(w)
        w = w + coef * w**3 * 1e-1
    print(w)
# or alternatively, take just w as input, but this is where the initial w is supposed to come from

This converges for me for values of w within one spherical triangle.

sigma and alpha description on wikipedia does not match Lee

The Wikipedia article says that α is the longitude and σ is the angular distance from the pole, whereas Lee defines α as the azimuth and σ as the arc length "of a great circle from the centroid to any other point within the spherical triangle." It seems that these only align when a pole is the centroid and a vertex lies on the prime meridian. In Lee's projection, only one triangle has a pole (south) as a centroid, and the vertices are at 20W, 140W, and 100E.

I haven't dug deep enough into this repo to see how you're getting the initial w, but you must be doing a transformation somewhere.

IMAGO/Authagraph power function setting no longer works on Map Analyzer nor on Map Desginer

Hi Justin! I want to report that the latest update (The Background Update), has broken the IMAGO/Authagraph Power Function setting. Changing the Power on either the Map Analyzer or the Map Designer Raster when using this particular projection does not seem to do anything. The rest of the settings (Longitude, Latitude, and Centre Meridian) work correctly.

I am running them using a Fedora Linux 39 Workstation container, with Java OpenJDK Runtime Environment (Red_Hat-17.0.9.0.9-2) (build 17.0.9+9), and libraries from openjfx-17.0.9_linux-x64_bin-sdk.

The older 3.4.6 works correctly using the same system and Java installation.
Let me know if there is anything I can do to help you debug this on my end. I appreciate your work!