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.