Historical Map

Generate beautiful vintage-style historical maps from GeoJSON data. Supports multiple projections, color palettes, timelines, compass roses, parchment overlays, and vignette effects. Perfect for history blogs, videos, articles, and educational content.

Historical Map Generator

Generate beautiful vintage-style historical maps from GeoJSON data.

Quick Start

bash

# Install dependencies
pip install geopandas matplotlib numpy Pillow pyproj shapely

# Download historical GeoJSON data
git clone https://github.com/aourednik/historical-basemaps.git
# Copy world_YYYY.geojson files to ./data/

# Generate a map
python generate.py --year 1914 --region europe --output europe_1914.png

What It Does

• Historical boundaries from 10,000 BC to 2010 AD (50+ time slices)
• Multiple projections: Lambert Azimuthal, Lambert Conformal Conic, Mollweide, Plate Carrée
• 4 color palettes: Vintage (HOI4-inspired), Pastel, Dark, Satellite
• Decorative elements: Compass rose, scale bar, timeline, legend, ocean labels
• Post-processing: Parchment overlay, vignette darkening, paper grain noise
• Customizable: Override any country color, add custom events, swap basemap textures

Available Time Slices

Commonly used years from historical-basemaps:

text

world_bc3000.geojson, world_bc1500.geojson, world_100.geojson
world_500.geojson, world_1000.geojson, world_1200.geojson
world_1400.geojson, world_1492.geojson, world_1600.geojson
world_1700.geojson, world_1783.geojson, world_1815.geojson
world_1880.geojson, world_1900.geojson, world_1914.geojson
world_1920.geojson, world_1930.geojson, world_1938.geojson
world_1945.geojson, world_1960.geojson, world_2000.geojson

Usage Examples

Basic: Europe 1914

bash

python generate.py --year 1914 --region europe --output europe_1914.png

World map with custom palette

bash

python generate.py --year 1600 --region world --projection mollweide --palette dark --output world_1600.png

China with custom colors

bash

python generate.py --year 1400 --region china --palette pastel \
  --title "MING DYNASTY" --title-cn "明朝疆域" --output ming.png

Custom region (Balkans)

bash

python generate.py --year 1815 --region 18,34,32,48 --output balkans_1815.png

With custom events timeline

Create my_events.json:

json

[
  {"year": "1789", "label": "Revolution", "cn": "法国大革命", "color": "#4169E1"},
  {"year": "1804", "label": "Empire", "cn": "拿破仑称帝", "color": "#2E5E2E"},
  {"year": "1815", "label": "Fall", "cn": "滑铁卢", "color": "#8B0000"}
]

bash

python generate.py --year 1815 --events my_events.json --output napoleon.png

Custom country colors

bash

python generate.py --year 1945 --region world \
  --title "POST-WAR WORLD" --title-cn "二战后的世界" \
  --palette vintage --output postwar.png

Parameters

Parameter	Default	Description
--year	required	Historical year (must match a GeoJSON file)
--region	europe	Region preset or lon_min,lat_min,lon_max,lat_max
--projection	laea	laea, lcc, mollweide, platecarree
--palette	vintage	vintage, pastel, dark, satellite
--title	auto	Main title (Latin/English)
--title-cn	auto	Chinese subtitle
--data	auto-detect	Path to GeoJSON file
--basemap	none	Path to satellite basemap image
--parchment	none	Path to parchment texture image
--events	auto-preset	Path to events JSON file
--dpi	300	Output resolution
--no-timeline	false	Disable bottom timeline
--no-compass	false	Disable compass rose
--no-postprocess	false	Skip vignette/noise effects
--output	historical_map.png	Output file path

Region Presets

Key	Coverage
europe	Full European continent
balkans	Balkan Peninsula
world	Global view
asia	Asian continent
china	China and surroundings
mediterranean	Mediterranean basin
middle_east	Middle East
americas	North + South America

Color Palettes

Vintage (Default)

HOI4-inspired desaturated military colors. Ocean: dark teal. Perfect for war maps.

Pastel

Light, soft colors on off-white background. Great for educational content.

Dark

Deep navy background with gold accents. Dramatic, cinematic feel.

Satellite

Modern cartography style with clean lines. Professional and neutral.

Post-Processing Pipeline

1. Parchment overlay — Semi-transparent parchment texture (alpha=18/255)
2. Vignette — Edge darkening for focal point emphasis
3. Paper grain — Subtle noise for aged paper texture
4. Desaturation — 14% color reduction for vintage feel

Python API

python

from generate import HistoricalMapGenerator

gen = HistoricalMapGenerator(
    data_path='data/world_1914.geojson',
    basemap_path='textures/satellite.jpg',
    parchment_path='textures/parchment.jpg',
)

gen.generate(
    year=1914,
    region='europe',
    projection='laea',
    title='EUROPA ANNO DOMINI MCMXIV',
    title_cn='第一次世界大战前夜的欧洲',
    color_palette='vintage',
    dpi=300,
    output_path='my_map.png',
)

Data Source

historical-basemaps by @aourednik. 50+ GeoJSON time slices covering 10,000 BC to 2010 AD.

Note: Border precision varies. The BORDERPRECISION field indicates accuracy (1=high, 3=approximate). Some regions (especially Balkans) may have minor gaps between neighboring territories. For publication-quality maps, consider manually editing the GeoJSON or using commercial data.

Requirements

• Python 3.9+
• geopandas >= 0.14
• matplotlib >= 3.8
• numpy >= 1.24
• Pillow >= 10.0
• pyproj >= 3.6
• shapely >= 2.0

License

MIT

Credits

Developed by Lumielle / OpenClaw Agent Data: historical-basemaps (CC BY 4.0)