Advanced Examples

Explore advanced techniques for creating specialized map posters, batch processing, and complex workflows.

Coordinate Override

Override the geocoded center point to focus on specific neighborhoods or landmarks.

Basic Override

Use --latitude and --longitude together to specify exact coordinates:

python create_map_poster.py \
  --city "New York" \
  --country "USA" \
  -lat 40.776676 \
  -long -73.971321 \
  -t noir

You must provide both --latitude and --longitude together. Providing only one will be ignored.

Finding Coordinates

Google Maps
OpenStreetMap
Nominatim API

Right-click on the desired location
Click the coordinates (e.g., “40.776676, -73.971321”)
Coordinates are copied to clipboard

Query the geocoding API directly:

curl "https://nominatim.openstreetmap.org/search?q=Central+Park+New+York&format=json&limit=1"

Use Cases

Focus on Specific Neighborhoods

Center on a neighborhood instead of city center:

# Manhattan's Upper West Side
python create_map_poster.py \
  -c "New York" -C "USA" \
  -lat 40.7870 -long -73.9754 \
  -d 3000 -t noir

# Tokyo's Shibuya district
python create_map_poster.py \
  -c "Tokyo" -C "Japan" \
  -lat 35.6595 -long 139.7004 \
  -d 2000 -t neon_cyberpunk

# Paris Marais district
python create_map_poster.py \
  -c "Paris" -C "France" \
  -lat 48.8566 -long 2.3522 \
  -d 2000 -t pastel_dream

Feature Specific Landmarks

Center on iconic locations:

# Eiffel Tower area
python create_map_poster.py \
  -c "Paris" -C "France" \
  -lat 48.8584 -long 2.2945 \
  -d 1500 -t warm_beige

# Central Park
python create_map_poster.py \
  -c "New York" -C "USA" \
  -lat 40.7829 -long -73.9654 \
  -d 2000 -t forest

# Venice Grand Canal
python create_map_poster.py \
  -c "Venice" -C "Italy" \
  -lat 45.4371 -long 12.3326 \
  -d 1000 -t blueprint

Correct Geocoding Errors

Sometimes Nominatim geocodes to the wrong location:

# If "Cambridge" geocodes to UK instead of MA
python create_map_poster.py \
  -c "Cambridge" -C "USA" \
  -lat 42.3736 -long -71.1097 \
  -t monochrome_blue

# If city name is ambiguous
python create_map_poster.py \
  -c "Portland" -C "USA" \
  -lat 45.5152 -long -122.6784 \  # Oregon, not Maine
  -t emerald

Create Neighborhood Series

Generate multiple posters of different neighborhoods:

# Brooklyn neighborhoods
python create_map_poster.py -c "New York" -C "USA" -lat 40.6782 -long -73.9442 -d 2000 -t noir  # Williamsburg
python create_map_poster.py -c "New York" -C "USA" -lat 40.6501 -long -73.9496 -d 2000 -t noir  # Park Slope
python create_map_poster.py -c "New York" -C "USA" -lat 40.7282 -long -73.9571 -d 2000 -t noir  # Greenpoint

Batch Generation

Generate All Themes

Create 17 posters (one per theme) with a single command:

python create_map_poster.py -c "Tokyo" -C "Japan" --all-themes

Output:

posters/tokyo_gradient_roads_20260304_143022.png
posters/tokyo_contrast_zones_20260304_143045.png
posters/tokyo_noir_20260304_143108.png
posters/tokyo_midnight_blue_20260304_143131.png
...

Batch Multiple Cities

Use a shell script for batch processing:

#!/bin/bash

# Define cities
CITIES=(
  "Paris,France"
  "Tokyo,Japan"
  "New York,USA"
  "Barcelona,Spain"
  "Dubai,UAE"
)

# Define theme
THEME="noir"

# Loop through cities
for city_country in "${CITIES[@]}"; do
  IFS=',' read -r city country <<< "$city_country"
  echo "Generating poster for $city, $country..."
  python create_map_poster.py -c "$city" -C "$country" -t "$THEME"
done

echo "All posters generated!"

Batch with Different Themes

Assign specific themes to specific cities:

batch_themed.sh

#!/bin/bash

# City + Country + Theme combinations
python create_map_poster.py -c "Tokyo" -C "Japan" -t japanese_ink -d 15000
python create_map_poster.py -c "Dubai" -C "UAE" -t midnight_blue -d 15000
python create_map_poster.py -c "Venice" -C "Italy" -t blueprint -d 4000
python create_map_poster.py -c "Marrakech" -C "Morocco" -t terracotta -d 5000
python create_map_poster.py -c "San Francisco" -C "USA" -t sunset -d 10000
python create_map_poster.py -c "Singapore" -C "Singapore" -t neon_cyberpunk
python create_map_poster.py -c "Barcelona" -C "Spain" -t warm_beige -d 8000
python create_map_poster.py -c "Seattle" -C "USA" -t emerald -d 12000

echo "Themed collection complete!"

Parallel Processing

Speed up batch generation with GNU Parallel:

# Install GNU Parallel (macOS)
brew install parallel

# Install GNU Parallel (Linux)
sudo apt-get install parallel

# Create cities list
cat > cities.txt << EOF
Paris,France,pastel_dream
Tokyo,Japan,japanese_ink
New York,USA,noir
Barcelona,Spain,warm_beige
Dubai,UAE,midnight_blue
EOF

# Run in parallel (4 jobs at once)
cat cities.txt | parallel --colsep ',' -j 4 \
  'python create_map_poster.py -c {1} -C {2} -t {3}'

Custom Dimensions

Instagram Post
Instagram Story
Twitter Header
Facebook Cover

Square format (1080x1080px)

python create_map_poster.py \
  -c "Paris" -C "France" \
  -W 3.6 -H 3.6 \
  -t pastel_dream

Resolution: 1080x1080px at 300 DPI

Vertical format (1080x1920px)

python create_map_poster.py \
  -c "New York" -C "USA" \
  -W 3.6 -H 6.4 \
  -t noir

Resolution: 1080x1920px at 300 DPI

Wide format (1500x500px)

python create_map_poster.py \
  -c "Tokyo" -C "Japan" \
  -W 5 -H 1.67 \
  -t neon_cyberpunk

Resolution: 1500x500px at 300 DPI

Ultra-wide format (1640x856px)

python create_map_poster.py \
  -c "San Francisco" -C "USA" \
  -W 5.47 -H 2.85 \
  -t sunset

Resolution: 1640x856px at 300 DPI

Desktop Wallpapers

python create_map_poster.py \
  -c "Paris" -C "France" \
  -W 6.4 -H 3.6 \
  -t pastel_dream

Print Formats

A4 (8.3 x 11.7 in)
US Letter (8.5 x 11 in)
A3 (11.7 x 16.5 in)
Poster (18 x 24 in)

python create_map_poster.py \
  -c "Barcelona" -C "Spain" \
  -W 8.3 -H 11.7 \
  -t warm_beige

Resolution: 2490x3510px at 300 DPIUse: Standard document size, home printing

python create_map_poster.py \
  -c "San Francisco" -C "USA" \
  -W 8.5 -H 11 \
  -t sunset

Resolution: 2550x3300px at 300 DPIUse: US standard, home printing

python create_map_poster.py \
  -c "Tokyo" -C "Japan" \
  -W 11.7 -H 16.5 \
  -t japanese_ink

Resolution: 3510x4950px at 300 DPIUse: Large prints, professional displays

python create_map_poster.py \
  -c "New York" -C "USA" \
  -W 18 -H 24 \
  -t noir

Resolution: 5400x7200px at 300 DPIUse: Large wall posters, galleries

Requires significant memory and processing time. Consider using a smaller distance (-d) value.

Complex Workflows

Multilingual Series

Create posters for the same city in multiple languages:

multilingual_series.sh

#!/bin/bash

CITY="Tokyo"
COUNTRY="Japan"
THEME="japanese_ink"

# English
python create_map_poster.py -c "$CITY" -C "$COUNTRY" -t "$THEME"

# Japanese
python create_map_poster.py -c "$CITY" -C "$COUNTRY" \
  -dc "東京" -dC "日本" \
  --font-family "Noto Sans JP" -t "$THEME"

# Korean
python create_map_poster.py -c "$CITY" -C "$COUNTRY" \
  -dc "도쿄" -dC "일본" \
  --font-family "Noto Sans KR" -t "$THEME"

# Chinese
python create_map_poster.py -c "$CITY" -C "$COUNTRY" \
  -dc "东京" -dC "日本" \
  --font-family "Noto Sans SC" -t "$THEME"

Distance Comparison

Compare different zoom levels of the same city:

# Tight zoom - neighborhood detail
python create_map_poster.py -c "Paris" -C "France" -t pastel_dream -d 3000

# Medium zoom - district view
python create_map_poster.py -c "Paris" -C "France" -t pastel_dream -d 8000

# Wide zoom - full city
python create_map_poster.py -c "Paris" -C "France" -t pastel_dream -d 15000

Theme Comparison Grid

Generate comparison images for theme selection:

comparison.sh

#!/bin/bash

CITY="Venice"
COUNTRY="Italy"
DISTANCE=4000

# Light themes
python create_map_poster.py -c "$CITY" -C "$COUNTRY" -d $DISTANCE -t warm_beige
python create_map_poster.py -c "$CITY" -C "$COUNTRY" -d $DISTANCE -t pastel_dream
python create_map_poster.py -c "$CITY" -C "$COUNTRY" -d $DISTANCE -t ocean

# Dark themes
python create_map_poster.py -c "$CITY" -C "$COUNTRY" -d $DISTANCE -t noir
python create_map_poster.py -c "$CITY" -C "$COUNTRY" -d $DISTANCE -t midnight_blue
python create_map_poster.py -c "$CITY" -C "$COUNTRY" -d $DISTANCE -t blueprint

echo "Comparison posters generated! Use image viewer to compare."

City Pattern Guide

Grid Cities

Characteristics: Regular street grids, right angles, predictable layout Best Settings:

Distance: 8000-12000m
Themes: Noir, Contrast Zones, Monochrome Blue

# Manhattan, USA
python create_map_poster.py -c "New York" -C "USA" -t noir -d 12000 -lat 40.7589 -long -73.9851

# Chicago, USA
python create_map_poster.py -c "Chicago" -C "USA" -t contrast_zones -d 10000

# Barcelona, Spain (Eixample district)
python create_map_poster.py -c "Barcelona" -C "Spain" -t warm_beige -d 8000 -lat 41.3874 -long 2.1686

Radial Cities

Characteristics: Concentric rings, radiating boulevards Best Settings:

Distance: 8000-12000m
Themes: Gradient Roads, Pastel Dream

# Paris, France
python create_map_poster.py -c "Paris" -C "France" -t gradient_roads -d 10000

# Moscow, Russia
python create_map_poster.py -c "Moscow" -C "Russia" -t noir -d 12000

Organic Cities

Characteristics: Irregular streets, historical growth, maze-like Best Settings:

Distance: 10000-18000m
Themes: Japanese Ink, Warm Beige, Terracotta

# Tokyo, Japan
python create_map_poster.py -c "Tokyo" -C "Japan" -t japanese_ink -d 15000

# Marrakech, Morocco
python create_map_poster.py -c "Marrakech" -C "Morocco" -t terracotta -d 5000

# Rome, Italy
python create_map_poster.py -c "Rome" -C "Italy" -t warm_beige -d 8000

Waterfront Cities

Characteristics: Canals, rivers, coastline, harbors Best Settings:

Distance: 4000-12000m
Themes: Blueprint, Ocean, Midnight Blue

# Venice, Italy
python create_map_poster.py -c "Venice" -C "Italy" -t blueprint -d 4000

# Amsterdam, Netherlands
python create_map_poster.py -c "Amsterdam" -C "Netherlands" -t ocean -d 6000

# Dubai, UAE
python create_map_poster.py -c "Dubai" -C "UAE" -t midnight_blue -d 15000

# Sydney, Australia
python create_map_poster.py -c "Sydney" -C "Australia" -t ocean -d 12000

Coastal Cities

Characteristics: Peninsula, bay, coastal curve Best Settings:

Distance: 10000-15000m
Themes: Ocean, Sunset, Emerald

# San Francisco, USA
python create_map_poster.py -c "San Francisco" -C "USA" -t sunset -d 10000

# Mumbai, India
python create_map_poster.py -c "Mumbai" -C "India" -t contrast_zones -d 18000

# Miami, USA
python create_map_poster.py -c "Miami" -C "USA" -t ocean -d 12000

Troubleshooting

Memory errors with large dimensions

Reduce dimensions or distance:

# Instead of this (may crash)
python create_map_poster.py -c "Tokyo" -C "Japan" -W 20 -H 20 -d 25000

# Try this
python create_map_poster.py -c "Tokyo" -C "Japan" -W 12 -H 16 -d 15000

Or increase available memory:

# Increase Python memory limit (Linux)
ulimit -v unlimited
python create_map_poster.py ...

Slow generation times

Factors affecting speed:

Distance (larger = slower)
City density (Tokyo slower than rural areas)
Dimensions (larger = slower)

Speed optimization:

# Slower (large dense city, wide area)
python create_map_poster.py -c "Tokyo" -C "Japan" -d 25000  # ~60s

# Faster (smaller area)
python create_map_poster.py -c "Tokyo" -C "Japan" -d 10000  # ~20s

# Faster (small city)
python create_map_poster.py -c "Venice" -C "Italy" -d 4000  # ~10s

Coordinates not working as expected

Ensure you’re using decimal degrees (not DMS):

# ✅ Correct (decimal degrees)
-lat 40.7589 -long -73.9851

# ❌ Incorrect (degrees/minutes/seconds)
-lat "40°45'32\"N" -long "73°59'06\"W"

Convert DMS to decimal: Decimal = Degrees + (Minutes/60) + (Seconds/3600)

Batch script fails on some cities

Add error handling:

#!/bin/bash

CITIES=("Paris,France" "Tokyo,Japan" "NewYork,USA")

for city_country in "${CITIES[@]}"; do
  IFS=',' read -r city country <<< "$city_country"
  echo "Processing $city..."
  
  # Add timeout and error handling
  if timeout 120 python create_map_poster.py -c "$city" -C "$country" -t noir; then
    echo "✓ $city completed"
  else
    echo "✗ $city failed"
  fi
done

Performance Tips

Reduce Distance

Use smaller distance values for faster generation:

Small cities: 4000-8000m
Medium cities: 8000-12000m
Large cities: 12000-18000m

Batch Wisely

Generate multiple themes for one city (cached map data) rather than multiple cities:

# Faster (reuses downloaded data)
python create_map_poster.py -c "Paris" -C "France" --all-themes

# Slower (downloads data each time)
python create_map_poster.py -c "Paris" -C "France" -t noir
python create_map_poster.py -c "Tokyo" -C "Japan" -t noir
python create_map_poster.py -c "NYC" -C "USA" -t noir

Use Parallel Processing

Leverage GNU Parallel for batch jobs:

cat cities.txt | parallel -j 4 'python create_map_poster.py ...'

Preview Mode

Test with smaller dimensions first:

# Quick preview
python create_map_poster.py -c "Paris" -C "France" -W 4 -H 4 -t noir

# Final high-res
python create_map_poster.py -c "Paris" -C "France" -W 12 -H 16 -t noir

Next Steps

Theme Gallery

Explore all 17 built-in themes

Create Custom Themes

Design your own theme color palettes

Multilingual Support

Display city names in any language

Get Started

Usage

Guides

Examples

Coordinate Override

Basic Override

Finding Coordinates

Use Cases

Batch Generation

Generate All Themes

Batch Multiple Cities

Batch with Different Themes

Parallel Processing

Custom Dimensions

Desktop Wallpapers

Print Formats

Complex Workflows

Multilingual Series

Distance Comparison

Theme Comparison Grid

City Pattern Guide

Grid Cities

Radial Cities

Organic Cities

Waterfront Cities

Coastal Cities

Troubleshooting

Performance Tips

Reduce Distance

Batch Wisely

Use Parallel Processing

Preview Mode

Next Steps

Theme Gallery

Create Custom Themes

Multilingual Support

Build docs developers (and LLMs) love

Get Started

Usage

Guides

Examples

Documentation Index

​Coordinate Override

​Basic Override

​Finding Coordinates

​Use Cases

​Batch Generation

​Generate All Themes

​Batch Multiple Cities

​Batch with Different Themes

​Parallel Processing

​Custom Dimensions

​Social Media Formats

​Desktop Wallpapers

​Print Formats

​Complex Workflows

​Multilingual Series

​Distance Comparison

​Theme Comparison Grid

​City Pattern Guide

​Grid Cities

​Radial Cities

​Organic Cities

​Waterfront Cities

​Coastal Cities

​Troubleshooting

​Performance Tips

Reduce Distance

Batch Wisely

Use Parallel Processing

Preview Mode

​Next Steps

Theme Gallery

Create Custom Themes

Multilingual Support

Build docs developers (and LLMs) love

Coordinate Override

Basic Override

Finding Coordinates

Use Cases

Batch Generation

Generate All Themes

Batch Multiple Cities

Batch with Different Themes

Parallel Processing

Custom Dimensions

Social Media Formats

Desktop Wallpapers

Print Formats

Complex Workflows

Multilingual Series

Distance Comparison

Theme Comparison Grid

City Pattern Guide

Grid Cities

Radial Cities

Organic Cities

Waterfront Cities

Coastal Cities

Troubleshooting

Performance Tips

Next Steps