Skip to main content
This guide will walk you through creating your first map poster with MapToPoster. You’ll learn the basic workflow and explore some of the customization options.
Make sure you’ve completed the installation before starting this tutorial.

​
Your First Poster

Let’s create a simple poster of Paris with the default terracotta theme.
1

Basic command

Run the following command to generate a Paris poster:
uv run ./create_map_poster.py --city "Paris" --country "France"
The first run may take 30-60 seconds as it downloads map data from OpenStreetMap. Subsequent runs with the same city will be much faster due to caching.
2

Watch the progress

You’ll see output showing the generation process:
==================================================
City Map Poster Generator
==================================================
Looking up coordinates...
✓ Found: Paris, Île-de-France, France métropolitaine, France
✓ Coordinates: 48.8566, 2.3522
✓ Loaded theme: Terracotta
  Mediterranean warmth - burnt orange and clay tones on cream

Generating map for Paris, France...
Fetching map data |████████████| 3/3
✓ All data retrieved successfully!
Rendering map...
Applying road hierarchy colors...
Saving to posters/paris_terracotta_20260304_143022.png...
✓ Done! Poster saved as posters/paris_terracotta_20260304_143022.png
3

View your poster

Your poster is saved in the posters/ directory with a timestamped filename:
posters/paris_terracotta_20260304_143022.png
The file format is: {city}_{theme}_{YYYYMMDD_HHMMSS}.png

​
Customize Your Poster

Now let’s explore different customization options.

​
Choose a Different Theme

MapToPoster includes 17 built-in themes. List them all: 
uv run ./create_map_poster.py --list-themes
Try a different theme using the -t or --theme flag: 
python create_map_poster.py -c "New York" -C "USA" -t noir

noir

Pure black background with white roads - perfect for minimalist aesthetics

midnight_blue

Navy background with gold roads - elegant and sophisticated

neon_cyberpunk

Dark background with electric pink/cyan - futuristic vibe

japanese_ink

Minimalist ink wash style - zen and artistic

blueprint

Architectural blueprint aesthetic - technical and precise

sunset

Warm oranges and pinks - vibrant and energetic

​
Adjust Map Coverage

Control how much of the city is shown with the -d or --distance parameter (in meters): 
# Small area - focus on city center (4-6km radius)
python create_map_poster.py -c "Venice" -C "Italy" -t blueprint -d 4000

# Medium area - downtown and surroundings (8-12km radius)
python create_map_poster.py -c "Barcelona" -C "Spain" -t warm_beige -d 8000

# Large area - full metropolitan view (15-20km radius)
python create_map_poster.py -c "Tokyo" -C "Japan" -t japanese_ink -d 15000
Distance Guide:
DistanceBest forExample Cities
4000-6000mSmall/dense cities with intricate patternsVenice canals, Amsterdam center
8000-12000mMedium cities, focused downtown areasParis, Barcelona, San Francisco
15000-20000mLarge metros, full city overviewTokyo, Mumbai, New York

​
Custom Dimensions

Change the poster size using -W (width) and -H (height) in inches: 
# Square Instagram post (1080x1080 at 300 DPI)
python create_map_poster.py -c "Paris" -C "France" -W 3.6 -H 3.6

# Mobile wallpaper (1080x1920 at 300 DPI)
python create_map_poster.py -c "Tokyo" -C "Japan" -W 3.6 -H 6.4

# 4K wallpaper (3840x2160 at 300 DPI)
python create_map_poster.py -c "Dubai" -C "UAE" -W 12.8 -H 7.2

# A4 print size
python create_map_poster.py -c "London" -C "UK" -W 8.3 -H 11.7
Resolution Reference (300 DPI):
FormatResolution (px)Dimensions (-W / -H)
Instagram Post1080 x 10803.6 x 3.6
Mobile Wallpaper1080 x 19203.6 x 6.4
HD Wallpaper1920 x 10806.4 x 3.6
4K Wallpaper3840 x 216012.8 x 7.2
A4 Print2480 x 35088.3 x 11.7
Default Poster3600 x 480012 x 16

​
Multilingual Posters

Create posters with city names in their native scripts using Google Fonts.

​
Japanese Example

python create_map_poster.py \
  --city "Tokyo" \
  --country "Japan" \
  --display-city "東京" \
  --display-country "日本" \
  --font-family "Noto Sans JP" \
  --theme japanese_ink

​
Arabic Example

python create_map_poster.py \
  -c "Dubai" \
  -C "UAE" \
  -dc "دبي" \
  -dC "الإمارات" \
  --font-family "Cairo" \
  -t midnight_blue

​
Korean Example

python create_map_poster.py \
  -c "Seoul" \
  -C "South Korea" \
  -dc "서울" \
  -dC "대한민국" \
  --font-family "Noto Sans KR" \
  -t neon_cyberpunk
Fonts are automatically downloaded from Google Fonts and cached locally in fonts/cache/. The tool automatically detects non-Latin scripts and applies appropriate spacing.

​
Real-World Examples

Here are some curated examples showcasing different city patterns:

​
Grid Patterns

Cities with distinctive grid layouts: 
# Famous street grid of New York
python create_map_poster.py -c "New York" -C "USA" -t noir -d 12000

​
Waterfront Cities

Cities with beautiful canal or coastal features: 
# Intricate canal network
python create_map_poster.py -c "Venice" -C "Italy" -t blueprint -d 4000

​
Radial Patterns

Cities with circular or radial layouts: 
# Haussmann boulevards radiating from Arc de Triomphe
python create_map_poster.py -c "Paris" -C "France" -t pastel_dream -d 10000

​
Organic Patterns

Cities with organic, maze-like street layouts: 
# Dense organic street network
python create_map_poster.py -c "Tokyo" -C "Japan" -t japanese_ink -d 15000

​
Advanced Options

​
Override Coordinates

Focus on a specific location instead of the city center: 
# Center on Statue of Liberty
python create_map_poster.py \
  --city "New York" \
  --country "USA" \
  --latitude 40.776676 \
  --longitude -73.971321 \
  --theme noir

​
Generate All Themes

Create posters with every available theme: 
python create_map_poster.py -c "Paris" -C "France" --all-themes
This generates 17 posters, one for each theme.

​
Different Output Formats

Export as PNG (default), SVG, or PDF: 
# Vector format for scaling
python create_map_poster.py -c "Paris" -C "France" --format svg

# PDF for professional printing
python create_map_poster.py -c "London" -C "UK" --format pdf -W 16 -H 20

​
Understanding the Output

Each poster includes:
  1. Map layers (from bottom to top):
    • Background color
    • Water features (rivers, bays, coastlines)
    • Parks and green spaces
    • Road network with hierarchical styling:
      • Motorways: Thickest, darkest lines
      • Primary roads: Thick lines
      • Secondary roads: Medium lines
      • Tertiary roads: Thin lines
      • Residential streets: Thinnest, lightest lines
  2. Gradient fades at top and bottom for visual depth
  3. Typography with:
    • City name (large, spaced letters for Latin scripts)
    • Decorative line separator
    • Country name
    • Coordinates (latitude/longitude)
    • OpenStreetMap attribution (bottom right)

​
Tips for Best Results

Match theme to city character

Use blueprint for Venice canals, japanese_ink for Tokyo, terracotta for Mediterranean cities, or neon_cyberpunk for modern Asian cities.

Adjust distance for city pattern

Dense historic centers look best at 4-6km. Grid cities shine at 8-12km. Large metros need 15-20km to show their full character.

Consider the final use

Use square dimensions (3.6x3.6) for Instagram, portrait (12x16) for wall art, or landscape (12.8x7.2) for desktop wallpapers.

Experiment with themes

Use --all-themes to generate all 17 variations at once, then pick your favorite. Cached data makes this fast!

​
Troubleshooting

If the geocoder finds the wrong city, override with specific coordinates:
python create_map_poster.py \
  --city "Springfield" \
  --country "USA" \
  --latitude 39.7817 \
  --longitude -89.6501
  • Increase the distance: -d 20000
  • Check if you’re in a rural area with fewer roads
  • Try a different city or coordinates
The tool auto-scales for long city names, but you can:
  • Use shorter display names: -dc "NYC"
  • Increase poster width/height
First run downloads map data. Speed up future runs:
  • Data is automatically cached in cache/ directory
  • Same city + distance combination uses cached data
  • Try --all-themes to reuse downloaded data for multiple posters

​
Next Steps

Now that you’ve created your first posters, explore more:

CLI Reference

Complete reference of all command-line options

Themes

Browse all 17 themes and learn to create custom themes

Examples

Gallery of curated city posters with exact commands

Advanced Usage

Coordinate overrides, custom fonts, and more

Build docs developers (and LLMs) love

Get started for freeTalk to us