Quick Start - MapToPoster

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.

Basic command

Run the following command to generate a Paris poster:

uv run ./create_map_poster.py --city "Paris" --country "France"

python 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.

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

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

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

Distance	Best for	Example Cities
4000-6000m	Small/dense cities with intricate patterns	Venice canals, Amsterdam center
8000-12000m	Medium cities, focused downtown areas	Paris, Barcelona, San Francisco
15000-20000m	Large metros, full city overview	Tokyo, 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):

Format	Resolution (px)	Dimensions (-W / -H)
Instagram Post	1080 x 1080	3.6 x 3.6
Mobile Wallpaper	1080 x 1920	3.6 x 6.4
HD Wallpaper	1920 x 1080	6.4 x 3.6
4K Wallpaper	3840 x 2160	12.8 x 7.2
A4 Print	2480 x 3508	8.3 x 11.7
Default Poster	3600 x 4800	12 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

# Eixample district's perfect grid
python create_map_poster.py -c "Barcelona" -C "Spain" -t warm_beige -d 8000

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

# Concentric canal rings
python create_map_poster.py -c "Amsterdam" -C "Netherlands" -t ocean -d 6000

# Palm Island and coastline
python create_map_poster.py -c "Dubai" -C "UAE" -t midnight_blue -d 15000

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

# Concentric ring roads
python create_map_poster.py -c "Moscow" -C "Russia" -t noir -d 12000

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

# Medina's labyrinthine streets
python create_map_poster.py -c "Marrakech" -C "Morocco" -t terracotta -d 5000

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:

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
Gradient fades at top and bottom for visual depth
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

Geocoding returns wrong location

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

Map looks empty or sparse

Increase the distance: -d 20000
Check if you’re in a rural area with fewer roads
Try a different city or coordinates

Text is too large or truncated

The tool auto-scales for long city names, but you can:

Use shorter display names: -dc "NYC"
Increase poster width/height

Slow generation

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

​Your First Poster

​Customize Your Poster

​Choose a Different Theme

noir

midnight_blue

neon_cyberpunk

japanese_ink

blueprint

sunset

​Adjust Map Coverage

​Custom Dimensions

​Multilingual Posters

​Japanese Example

​Arabic Example

​Korean Example

​Real-World Examples

​Grid Patterns

​Waterfront Cities

​Radial Patterns

​Organic Patterns

​Advanced Options

​Override Coordinates

​Generate All Themes

​Different Output Formats

​Understanding the Output

​Tips for Best Results

Match theme to city character

Adjust distance for city pattern

Consider the final use

Experiment with themes

​Troubleshooting

​Next Steps

CLI Reference

Themes

Examples

Advanced Usage

Your First Poster

Customize Your Poster

Choose a Different Theme

Adjust Map Coverage

Custom Dimensions

Multilingual Posters

Japanese Example

Arabic Example

Korean Example

Real-World Examples

Grid Patterns

Waterfront Cities

Radial Patterns

Organic Patterns

Advanced Options

Override Coordinates

Generate All Themes

Different Output Formats

Understanding the Output

Tips for Best Results

Troubleshooting

Next Steps