Replacing Cartopy’s Background Image

metadata

Whilst discussing a friend’s summary of 2017 I found it difficult to place parts of Michigan that I had visited as The Great Lakes were missing from the state boundaries. My friend then countered that my own maps did not feature The Great Lakes either. Disbelieving, I went away and checked; he was correct - Cartopy’s default background image does not show The Great Lakes (shown below).

Download:
  1. 256 px × 128 px (0.0 Mpx; 46.5 KiB)
  2. 512 px × 256 px (0.1 Mpx; 171.7 KiB)
  3. 720 px × 360 px (0.3 Mpx; 320.5 KiB)

If you would like to check for yourself then the following Python code will show you where the default image is located for your installation of Cartopy.

1
2
3
4
5
6
7
8
9
 

.editorconfig
.gitignore
.mypy.ini
.pylint.ini
.shellcheckrc
git-files.txt
LICENCE.txt
README.md
replacing-cartopy-background-image-location.py
You may also download “git-files.txt” directly or view “git-files.txt” on GitHub Gist (you may need to manually checkout the “main” branch).

As of January 2018, that folder only contains one image, called 50-natural-earth-1-downsampled.png, which has dimensions 720 px × 360 px and size 327 KiB. The sidecar JSON file (shown below) describes the contents of the folder.

1
2
3
4
5
6
7
8
 

.editorconfig
.gitignore
.mypy.ini
.pylint.ini
.shellcheckrc
git-files.txt
README.md
replacing-cartopy-background-image-images1.json
You may also download “git-files.txt” directly or view “git-files.txt” on GitHub Gist (you may need to manually checkout the “main” branch).

I decided to create my own folder of background images, using the same specification that Cartopy uses, so that I could have both higher resolution background images and ones that contained large inland bodies of water. The script that I wrote to download the ZIP archives from Natural Earth, extract the TIFFs, create the PNGs and create the JSON is shown below. It runs both convert and optipng during its execution.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 

.editorconfig
.gitignore
.mypy.ini
.pylint.ini
.shellcheckrc
git-files.txt
images.json
LICENCE.txt
README.md
replacing-cartopy-background-image-process.py
You may also download “git-files.txt” directly or view “git-files.txt” on GitHub Gist (you may need to manually checkout the “main” branch).

The JSON file that it creates is shown below for comparison with the original one.

1
2
3
4
5
6
7
8
 

.editorconfig
.gitignore
.mypy.ini
.pylint.ini
.shellcheckrc
git-files.txt
README.md
replacing-cartopy-background-image-images2.json
You may also download “git-files.txt” directly or view “git-files.txt” on GitHub Gist (you may need to manually checkout the “main” branch).

The PNG files that it creates are shown below for comparison with the original one too. Note that The Great Lakes and Lake Victoria are easily visible (to name a few).

Download:
  1. 256 px × 128 px (0.0 Mpx; 46.1 KiB)
  2. 512 px × 256 px (0.1 Mpx; 167.3 KiB)
  3. 1,024 px × 512 px (0.5 Mpx; 649.4 KiB)
  4. 2,048 px × 1,024 px (2.1 Mpx; 2.6 MiB)
  5. 4,096 px × 2,048 px (8.4 Mpx; 11.0 MiB)
  6. 8,192 px × 4,096 px (33.6 Mpx; 41.2 MiB)
  7. 21,600 px × 10,800 px (233.3 Mpx; 222.6 MiB)

Great - but how am I going to use this new folder that has the same organisation as Cartopy’s folder? I have written a replacement function, called pyguymer3.geo.add_map_background(), that I can use so that my scripts use this new folder. Now all that I need to do is set the environment variable $CARTOPY_USER_BACKGROUNDS to the path that my new images are in and then replace all instances of ax.stock_img() in all of my Python scripts with either pyguymer3.geo.add_map_background(ax) (for a low-resolution background image for testing purposes) or pyguymer3.geo.add_map_background(ax, resolution = "large4096px") (for a high-resolution background image for publishing purposes) for example.

You can see the fruits of this work by looking at the example image in my Flight Map Creator project on GitHub. The following webpages have been useful during this project: