Metadata

name: historical-map
description: 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.
metadata: {"openclaw":{"emoji":"🗺️","requires":{"pip":["geopandas>=0.14","matplotlib>=3.8","numpy>=1.24","Pillow>=10.0","pyproj>=3.6","shapely>=2.0"]},"install":[{"id":"pip-install","kind":"pip","packages":["geopandas>=0.14","matplotlib>=3.8","numpy>=1.24","Pillow>=10.0","pyproj>=3.6","shapely>=2.0"],"label":"Install map generation dependencies"}]}}
keywords: ["map","historical","geography","geojson","visualization","cartography"]

Historical Map Generator

Generate beautiful vintage-style historical maps from GeoJSON data.

Quick Start

# 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:

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

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

World map with custom palette

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

China with custom colors

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

Custom region (Balkans)

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

With custom events timeline

Create my_events.json:

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

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

Custom country colors

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

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

Python API

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)

Historical Map

安装技能