CartoGo: Artistic City Map Poster Generator

Generate beautiful, minimalist map posters for any city in the world. CartoGo is a high-performance Go implementation of the original City Map Poster Generator, designed for speed, reliability, and 1-to-1 aesthetic parity.

Credits & Attribution

This project is a high-performance Go port of the City Map Poster Generator (Python) by Ankur Gupta.

The Go implementation aims to preserve the artistic vision and functionality of the original while providing the speed and safety of the Go language. All themes and artistic design choices are credited to the original author.

Overview

CartoGo leverages OpenStreetMap data to create high-resolution (300 DPI) artistic posters. It fetches geographic features like roads, water bodies, and parks, then renders them using a custom engine built on the gg library to match the sophisticated look of the original Matplotlib-based project.

Features

• Blazing Fast Rendering: Go's concurrency and the gg library provide significant performance gains for high-resolution output.
• 1-to-1 Parity: Every detail, from road hierarchy to font spacing and gradient fades, has been meticulously ported.
• High-Fidelity Typography:
  • Automatic script detection (Latin vs. Non-Latin).
  • Elegant letter-spacing for Latin scripts.
  • Dynamic font scaling to prevent long city names from truncating.
• Advanced Caching:
  • OSM Data: Cached using Go's binary gob format for near-instant re-renders.
  • Geocoding: Caches Nominatim results to respect rate limits.
• Smart Data Fetching:
  • Bounding-box queries with automatic radius compensation for different aspect ratios.
  • Robust retry logic for Overpass API server timeouts.

Installation

Prerequisites

• Go 1.21+

Setup

git clone <repository-url>cd CartoGo
go mod tidy
go build -o CartoGo.exe

Usage

Basic Example

./CartoGo.exe -city "Paris" -country "France"

Advanced Multilingual Example

./CartoGo.exe -city "Tokyo" -country "Japan" -display-city "東京" -display-country "日本" -theme japanese_ink

CLI Reference

Required Flags

Flag	Short	Description
-city	-c	City name for geocoding.
-country	-C	Country name for geocoding.

Optional Flags

Flag	Description	Default
-theme	Theme name (matches JSON file in themes/).	terracotta
-distance	Map radius in meters from center.	18000
-latitude	Manual latitude override.	0
-longitude	Manual longitude override.	0
-display-city	Custom city name to display on poster.
-display-country	Custom country name to display on poster.
-country-label	Alias for -display-country.
-width	Physical width in inches.	12
-height	Physical height in inches.	16
-all-themes	Generate a poster for every theme in themes/.	false
-list-themes	List available themes with descriptions.	false

---

Guides

Resolution & Print Guide (300 DPI)

Use these values for -width and -height to target specific outputs:

Target	Inches (-width / -height)	Resolution (px)
Instagram Post	3.6 x 3.6	1080 x 1080
Mobile Wallpaper	3.6 x 6.4	1080 x 1920
A4 Print	8.3 x 11.7	2490 x 3510
A3 Print	11.7 x 16.5	3510 x 4950
Large Poster	18.0 x 24.0	5400 x 7200

Distance Selection

Radius (-distance)	Best for...
4,000 - 6,000m	Small/dense centers (Venice, Amsterdam, Old Town Prague)
8,000 - 12,000m	Medium cities or focused downtowns (Barcelona, SF, Paris)
15,000 - 20,000m	Large metropolises and ring roads (Tokyo, London, NYC)

---

Themes

The generator comes with 17 built-in themes in the themes/ directory, each carefully designed for a specific aesthetic:

Theme	Name	Aesthetic
autumn	Autumn	Burnt oranges, deep reds, golden yellows - seasonal warmth
blueprint	Blueprint	Classic architectural blueprint - technical drawing aesthetic
contrast_zones	Contrast Zones	Strong contrast showing urban density - darker in center, lighter at edges
copper_patina	Copper Patina	Oxidized copper aesthetic - teal-green patina with copper accents
emerald	Emerald City	Lush dark green aesthetic with mint accents
forest	Forest	Deep greens and sage tones - organic botanical aesthetic
gradient_roads	Gradient Roads	Smooth gradient from dark center to light edges with subtle features
japanese_ink	Japanese Ink	Traditional ink wash inspired - minimalist with subtle red accent
midnight_blue	Midnight Blue	Deep navy background with gold/copper roads - luxury atlas aesthetic
monochrome_blue	Monochrome Blue	Single blue color family with varying saturation - clean and cohesive
neon_cyberpunk	Neon Cyberpunk	Dark background with electric pink/cyan - bold night city vibes
noir	Noir	Pure black background with white/gray roads - modern gallery aesthetic
ocean	Ocean	Various blues and teals - perfect for coastal cities
pastel_dream	Pastel Dream	Soft muted pastels with dusty blues and mauves - dreamy artistic aesthetic
sunset	Sunset	Warm oranges and pinks on soft peach - dreamy golden hour aesthetic
terracotta	Terracotta	Mediterranean warmth - burnt orange and clay tones on cream
warm_beige	Warm Beige	Earthy warm neutrals with sepia tones - vintage map aesthetic

---

Technical Architecture

1. Data Pipeline

1. Geocoding: Uses geocoding.go to hit Nominatim API. Results are cached locally.
2. Radius Compensation: Calculates compensatedDist = distance * (maxDim / minDim) / 4.0 to ensure the map fills the frame regardless of orientation.
3. Data Fetching: osm.go builds a complex Overpass QL query to fetch ways and relations (multipolygons) for water and parks.
4. Caching: Uses cache.go to store OverpassResponse structs in GOB format, reducing subsequent render times from minutes to milliseconds.

2. Rendering Engine (rendering.go)

• Projection: Converts Lat/Lon to a local meter-based coordinate system using the Haversine-adjacent projection.
• Z-Order Management:
  1. Background Fill
  2. Water Polygons
  3. Park Polygons
  4. Roads (Sorted by Priority: Motorway > Primary > Secondary > Residential)
  5. Top/Bottom Gradient Fades (NRGBA for pure transparency)
  6. Typography Layers
• Typography Logic:
  • Script Detection: Uses unicode package to detect Latin script prevalence.
  • Points-to-Pixels: Multiplies point sizes by DPI / 72.0 to ensure physical sizes match Python's Matplotlib output.

---

Hacker's Guide

Adding a Custom Theme

Create a .json file in themes/:

{
"name": "My Custom Theme",
"description": "Subtle description",
"bg": "#FFFFFF",
"text": "#000000",
"gradient_color": "#FFFFFF",
"water": "#D5D5D5",
"parks": "#EFEFEF",
"road_motorway": "#000000",
"road_primary": "#222222",
"road_secondary": "#444444",
"road_tertiary": "#666666",
"road_residential": "#888888",
"road_default": "#666666"
}

Modifying Road Hierarchy

Adjust getRoadPriority and getRoadStyle in rendering.go to change how different OSM highway tags are weighted and colored.

Extending the Map

To add new features (e.g., railways, buildings):

1. Update the Overpass query in osm.go.
2. Add a rendering loop in renderPoster (before roads).
3. Define a new color field in the Theme struct in themes.go.

---

License

This project is licensed under the MIT License. See the LICENSE file for the full text.