historical-map

# Historical Map Skill Generate interactive historical maps as self-contained HTML files powered by Leaflet.js. ## Critical: Things Claude Won't Know Without This Skill ### The output is a standalone HTML file The Python script generates a complete HTML file that loads Leaflet.js from CDN. No server, no build step, no pip install — just open in a browser. Zero external Python dependencies. ### Pre-configured basemaps are available ```python from scripts.map_builder import BASEMAPS # Keys: "osm", "watercolor", "toner_lite", "carto_light", "carto_dark" ``` `carto_light` (CartoDB Positron) is the default — a clean, muted basemap ideal for historical data overlays. ### Historical world boundaries are one method call away 36 pre-configured GeoJSON boundary files (2000 BCE – 1994 CE) from `aourednik/historical-basemaps` (keys in `HISTORICAL_BOUNDARIES`): ```python m.add_historical_boundaries("200_bce") # World c. 200 BCE m.add_historical_boundaries("100_ce") # World c. 100 CE m.add_historical_boundaries("1400_ce") # World c. 1400 CE ``` These are fetched at runtime from GitHub by the browser. Each polygon has a `NAME` property for popups/tooltips. ### Available boundary periods BCE: `2000_bce`, `1000_bce`, `500_bce`, `323_bce`, `200_bce`, `100_bce`, `1_bce` CE: `100_ce` through `1994_ce` in ~100-year increments, plus special years: `1279_ce`, `1492_ce`, `1783_ce`, `1815_ce`, `1880_ce`, `1920_ce`, `1938_ce`, `1945_ce`, `1960_ce` ### What is HTML and what is plain text `popup` and `attribution` strings are inserted as **HTML** (so `<b>`, `<br>`, links work). Only pass trusted HTML there; escape any text that comes from outside data. Everything else is treated as plain text and escaped for you: `label`, `tooltip`, layer and group names, and GeoJSON property values shown by `popup_property` / `tooltip_property`. ### Colored marker icons are loaded from GitHub Marker colors: `blue`, `gold`, `red`, `green`, `orange`, `yellow`, `violet`, `grey`, `black`. These use the `pointhi/leaflet-color-markers` CDN icons. ### Academia Sinica provides Chinese historical map tiles WMTS tiles based on Tan Qixiang's Historical Atlas of China (谭其骧《中国历史地图集》), covering 222 BCE – 1911 CE. The server is WMTS only (it does not answer WMS `GetMap`), so do **not** use `add_wms_layer`. Its tiles use the Google/XYZ grid, so load them with `add_tile_layer`: ```python m.add_tile_layer( "https://gis.sinica.edu.tw/ccts/file-exists.php?img=LAYER_ID-png-{z}-{x}-{y}", name="Beijing 1928", attribution='<a href="https://gis.sinica.edu.tw/">Academia Sinica</a>', ) ``` Find `LAYER_ID` and its image format (`png` or `jpg`) in the capabilities file: `https://gis.sinica.edu.tw/ccts/wmts?SERVICE=WMTS&REQUEST=GetCapabilities` (each layer's `ResourceURL template`, e.g. `Beijing_50K_1928b-png-...`). ### MapWarper provides crowdsourced georeferenced historical maps ```python m.add_mapwarper_layer(14781, name="1860 Beijing") ``` Find map IDs by browsing https://mapwarper.net/ ## Workflow ### 1. Build a map with the Python builder ```python from scripts.map_builder import HistoricalMapBuilder m = HistoricalMapBuilder( title="Tang Dynasty China", center=(35.0, 108.0), zoom=5, basemap="carto_light", # or "osm", "watercolor", "toner_lite", "carto_dark" ) # Add historical boundaries m.add_historical_boundaries("700_ce", name="World c. 700 CE") # Add markers m.add_marker(34.26, 108.94, "Chang'an (長安)", popup="<b>Chang'an</b><br>Capital of the Tang Dynasty", color="red", group="Capitals") m.add_marker(34.75, 113.65, "Luoyang (洛陽)", popup="<b>Luoyang</b><br>Eastern capital", color="red", group="Capitals") m.add_marker(31.23, 121.47, "Huating (華亭)", popup="<b>Huating</b><br>Modern-day Shanghai area", color="blue", group="Cities") # Add GeoJSON data (inline) m.add_geojson( geojson_data, # Any GeoJSON dict name="Grand Canal", style={"color": "#0077b6", "weight": 3}, popup_property="name", # Show feature.properties.name on click tooltip_property="name", # Show on hover ) # Add GeoJSON from URL (fetched by browser at runtime) m.add_geojson_url( "https://example.com/data.geojson", name="Trade Routes", style={"color": "#e63946", "weight": 2, "dashArray": "5 3"}, ) # Add a scanned historical map as image overlay m.add_image_overlay( "https://example.com/old_map.jpg", bounds=((30.0, 100.0), (42.0, 120.0)), # (SW corner, NE corner) name="Historical Map", opacity=0.6, ) # Add custom tile layer m.add_tile_layer( "https://tiles.example.com/{z}/{x}/{y}.png", name="Custom Tiles", opacity=0.7, ) # Save m.save_html("tang_dynasty.html") ``` ### 2. Open the HTML file ```bash open tang_dynasty.html ``` Interactive features: pan, zoom, click markers for popups, hover for tooltips, toggle layers on/off via the layer control panel. ### 3. Combine with other skills ```python # Use CBDB data to place historical figures on the map # Use CHGIS/TGAZ data for accurate historical coordinates # Use CJK Calendar to annotate dates ``` ## Builder API Reference ### Constructor ```python HistoricalMapBuilder( title="Map Title", center=(lat, lng), # Default: (35.0, 105.0) zoom=5, # Default: 5, range 0-18 basemap="carto_light", # Key from BASEMAPS or "none" ) ``` ### Methods | Method | Description | |--------|-------------| | `add_marker(lat, lng, label, *, popup, tooltip, color, group)` | Colored marker with popup/tooltip | | `add_geojson(data, name, *, style, popup_property, tooltip_property)` | Inline GeoJSON overlay | | `add_geojson_url(url, name, *, style, popup_property, tooltip_property)` | Remote GeoJSON (fetched by browser) | | `add_historical_boundaries(period, *, name, style)` | World boundaries from historical-basemaps | | `add_tile_layer(url, name, *, attribution, max_zoom, opacity, overlay)` | XYZ tile layer | | `add_mapwarper_layer(map_id, name, *, opacity)` | MapWarper georeferenced map | | `add_wms_layer(url, layers, name, *, fmt, transparent, opacity, attribution)` | WMS tile layer (real WMS servers only) | | `add_image_overlay(url, bounds, name, *, opacity)` | Georeferenced image overlay | | `save_html(path)` | Write standalone HTML file | ### Leaflet Style Options ```python style = { "color": "#e63946", # Stroke color (hex or CSS name) "weight": 2, # Stroke width in pixels "opacity": 1, # Stroke opacity (0-1) "fillColor": "#f1faee", # Fill color (defaults to color) "fillOpacity": 0.2, # Fill opacity (0-1) "dashArray": "5 3", # Dash pattern } ``` ## API Etiquette - **Historical boundaries**: Fetched from GitHub raw URLs — no rate limit, but cache results for repeated use - **MapWarper**: Public tile service — use reasonably - **Academia Sinica**: Public WMTS — use for academic purposes - **Leaflet CDN**: No rate limits on `unpkg.com` ## Related Skills - **cbdb-api** / **cbdb-local**: Retrieve biographical data with geographic coordinates to place historical figures on maps - **chgis-tgaz** / **tgaz-sqlite**: Look up historical place names with coordinates for accurate marker placement - **cjk-calendar**: Convert lunisolar dates for timeline annotations - **historical-timeline**: Create a companion timeline visualization alongside the map - **wikidata-search**: Retrieve coordinates and geographic identifiers for historical places ## Resources - `references/map_reference.md` — Complete reference for basemaps, tile servers, boundary datasets, and Leaflet configuration - `scripts/map_builder.py` — Python builder with zero dependencies for generating standalone HTML maps