Contributing Guidelines

Welcome Contributors

Thank you for your interest in contributing to MapToPoster! This guide will help you set up your development environment and understand the contribution workflow.

MapToPoster is a CLI-focused project. We welcome bug fixes and feature enhancements that align with the project’s minimalist design philosophy.

Contribution Philosophy

Before starting work, please review these guidelines:

✅ We Welcome

Bug fixes for rendering issues, crashes, or incorrect output
Performance improvements for data fetching or rendering speed
New themes with well-designed color palettes
Documentation improvements for clarity and completeness
New map layers (railways, buildings, etc.) that enhance poster quality
Internationalization improvements for better font/script support
Test coverage additions and improvements

❌ Please Don’t Submit

User interfaces (web apps, desktop GUIs, mobile apps)
- MapToPoster is intentionally CLI-only to maintain simplicity
Dockerization for now
- May be considered in the future, but not a current priority
Major architectural rewrites without prior discussion
- Please open an issue or discussion first

Before working on large features, please ask in GitHub Discussions or open an issue to confirm it will be merged. This saves everyone’s time!

Development Setup

Prerequisites

Python 3.11 or higher (required since v0.3.0)
Git for version control
Text editor or IDE (VS Code, PyCharm, etc.)

Installation Methods

Option 1: Using uv (Recommended)

uv is the recommended package manager for MapToPoster. It provides faster dependency resolution and automatic virtual environment management.Install uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Clone and setup:

git clone https://github.com/originalankur/maptoposter.git
cd maptoposter

# Sync dependencies (creates .venv automatically)
uv sync --locked

# Run the script
uv run ./create_map_poster.py --city Paris --country France

The --locked flag ensures you get exact dependency versions from uv.lock for reproducible builds.

Option 2: Using pip + venv

Traditional Python virtual environment setup:

git clone https://github.com/originalankur/maptoposter.git
cd maptoposter

# Create virtual environment
python -m venv .venv

# Activate environment
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Run the script
python create_map_poster.py --city Paris --country France

Verify Installation

Test that everything is working:

# List available themes
python create_map_poster.py --list-themes

# Generate a test poster
python create_map_poster.py -c "Venice" -C "Italy" -t blueprint -d 4000

You should see:

Progress bars for data fetching
Theme loading confirmation
A new PNG file in posters/ directory

Project Structure

Understanding the codebase layout:

maptoposter/
├── create_map_poster.py    # Main CLI script and rendering logic
├── font_management.py      # Font loading and Google Fonts integration
├── themes/                 # Theme JSON files (17 built-in themes)
│   ├── terracotta.json
│   ├── noir.json
│   ├── japanese_ink.json
│   └── ...
├── fonts/                  # Font files
│   ├── Roboto-Bold.ttf
│   ├── Roboto-Regular.ttf
│   ├── Roboto-Light.ttf
│   └── cache/              # Downloaded Google Fonts (auto-generated)
├── posters/                # Generated output (git-ignored)
├── cache/                  # OSM data cache (git-ignored)
├── pyproject.toml          # Project metadata and dependencies
├── uv.lock                 # Locked dependency versions
├── requirements.txt        # pip-compatible dependencies
├── README.md               # User documentation
└── CHANGELOG.md            # Version history

Key Files to Know

File	Lines	Purpose
`create_map_poster.py`	~1052	Main entry point, CLI parsing, rendering pipeline
`font_management.py`	~171	Font loading, Google Fonts API integration
`themes/*.json`	~15 each	Color palette definitions
`pyproject.toml`	~30	Python 3.11+ requirement, dependency list

Making Changes

Development Workflow

Create a feature branch

git checkout -b fix/road-rendering-bug
# or
git checkout -b feature/add-railways

Use clear branch names: fix/, feature/, docs/, test/

Make your changes

Edit the relevant files. See Architecture Overview for code structure.For bug fixes:

Identify the problematic function(s)
Add print statements or use a debugger to trace the issue
Fix the root cause, not just the symptom

For new features:

Follow existing code patterns (see Extension Points)
Add necessary theme properties to ALL theme JSON files
Update fallback values in load_theme() function

Test your changes

CRITICAL: Test before and after versions!

# Generate test poster BEFORE your changes
git stash
python create_map_poster.py -c "Tokyo" -C "Japan" -t noir -d 15000
mv posters/tokyo_noir_*.png before.png
git stash pop

# Generate test poster AFTER your changes
python create_map_poster.py -c "Tokyo" -C "Japan" -t noir -d 15000
mv posters/tokyo_noir_*.png after.png

# Compare visually
open before.png after.png  # macOS

Test multiple scenarios:

Different cities (grid vs organic layouts)
Different themes (light vs dark backgrounds)
Different distances (small 4000m vs large 18000m)
Edge cases (coastal cities, islands, etc.)

Commit your changes

git add create_map_poster.py
git commit -m "fix: correct road layer z-order to render above water"

Use Conventional Commits format:

fix: for bug fixes
feat: for new features
docs: for documentation changes
test: for test additions
refactor: for code refactoring

Push and create PR

git push origin fix/road-rendering-bug

Then open a Pull Request on GitHub with:

Clear description of the problem/feature
Before/after screenshots for visual changes
Testing steps you performed
Any breaking changes or migration notes

Testing Guidelines

Manual Testing Checklist

Before submitting a PR, test these scenarios:

Core Functionality

Basic poster generation works
Geocoding resolves city/country correctly
Cache is created and reused on second run
Theme loading works for all built-in themes
Error handling doesn’t crash the script

Visual Quality

Roads render above water and parks (z-order bug fixed in PR #42)
Text is readable and properly positioned
Gradients blend smoothly at top/bottom
Aspect ratio is maintained (no distortion)
Line weights are consistent across zoom levels

Edge Cases

Long city names don’t get cut off
Non-Latin scripts render correctly (test with Japanese/Arabic)
Custom coordinates override works
Invalid city/country shows helpful error
Network failures are handled gracefully

Cross-Platform

If possible, test on multiple platforms:

macOS
Linux
Windows

Focus on file path handling and font loading.

Test Coverage Areas

We don’t have formal unit tests yet (contributions welcome!), but manual testing should cover:

Data Fetching: Verify OSMnx queries return expected data
Rendering: Check layer composition and z-order
Typography: Test Latin and non-Latin scripts
Themes: Load all 17 themes successfully
Caching: Confirm cache files are created and reused
CLI Arguments: Test all flag combinations

Code Style Guidelines

Python Conventions

Formatting: Follow PEP 8 style guide
Line length: Max 120 characters (existing code uses ~100)
Docstrings: Use triple-quoted strings with clear descriptions
Type hints: Use when possible (see fetch_graph() return type at line 409)
Naming:
- Functions: snake_case (e.g., get_edge_colors_by_type)
- Classes: PascalCase (e.g., CacheError)
- Constants: UPPER_CASE (e.g., FONTS_DIR, THEME)

Example Function

def fetch_features(point, dist, tags, name) -> GeoDataFrame | None:
    """
    Fetch geographic features from OpenStreetMap.
    
    Uses caching to avoid redundant downloads. Fetches features matching
    the specified OSM tags within distance from center point.
    
    Args:
        point: (latitude, longitude) tuple for center point
        dist: Distance in meters from center point
        tags: Dictionary of OSM tags to filter features
        name: Name for this feature type (for caching and logging)
    
    Returns:
        GeoDataFrame of features, or None if fetch fails
    """
    # Implementation...

Comments

Use comments to explain why, not what
Complex algorithms should have explanatory comments

Reference issue numbers when fixing bugs:

# Fix z-order bug (issue #39) - roads should render above water
water_polys.plot(ax=ax, facecolor=THEME['water'], zorder=0.5)

Adding New Themes

Themes are the easiest way to contribute!

Creating a Theme

Design your color palette

Choose colors that work well together. Use tools like:

Coolors.co for palette generation
Adobe Color for harmony rules
Paletton for color relationships

Consider:

Background should contrast with roads
Water should be distinguishable from background
Road hierarchy should be visible (motorway darkest/lightest)
Text must be readable against background

Create JSON file

themes/my_theme.json

{
  "name": "My Awesome Theme",
  "description": "Brief description of the aesthetic",
  "bg": "#FFFFFF",
  "text": "#000000",
  "gradient_color": "#FFFFFF",
  "water": "#A8D5E2",
  "parks": "#C8E6C9",
  "road_motorway": "#1A1A1A",
  "road_primary": "#2A2A2A",
  "road_secondary": "#3A3A3A",
  "road_tertiary": "#4A4A4A",
  "road_residential": "#5A5A5A",
  "road_default": "#4A4A4A"
}

All fields are required. The theme won’t load if any are missing.

Test the theme

python create_map_poster.py -c "Barcelona" -C "Spain" -t my_theme -d 8000
python create_map_poster.py -c "Venice" -C "Italy" -t my_theme -d 4000
python create_map_poster.py -c "Tokyo" -C "Japan" -t my_theme -d 15000

Test on cities with different characteristics:

Grid layouts (Barcelona, New York) - tests road hierarchy
Water-heavy (Venice, Amsterdam) - tests water/road contrast
Organic streets (Tokyo, Marrakech) - tests density rendering

Submit PR with examples

Include sample posters in your PR description:

## New Theme: My Awesome Theme

A vibrant theme inspired by [inspiration source].

**Sample Posters:**
- Barcelona (grid test): [attach image]
- Venice (water test): [attach image]
- Tokyo (density test): [attach image]

Theme Design Tips

Road hierarchy matters! The difference between motorway and residential should be visually clear but not jarring. Aim for 15-20% brightness difference between adjacent levels.

Common mistakes to avoid:

Background and gradient color mismatch (causes visible seam)
Insufficient text contrast (hard to read city name)
Water too similar to background (loses definition)
All roads same color (loses street hierarchy)

Bug Fixes

Reporting Bugs

Before fixing a bug, check if it’s already reported in GitHub Issues. Good bug reports include:

MapToPoster version (check recent commits or tags)
Python version (python --version)
Operating system (macOS, Linux, Windows)
Full command you ran
Expected vs actual behavior
Error messages or stack traces
Sample poster showing the issue (if visual)

Example Bug Fix PR

See PR #42 for the road z-order fix: Problem: Roads were rendering below water/parks (issue #39) Solution: Adjusted z-order values:

# Before
water_polys.plot(..., zorder=1)
parks_polys.plot(..., zorder=2)
# Roads at default zorder=2 (matplotlib)

# After  
water_polys.plot(..., zorder=0.5)
parks_polys.plot(..., zorder=0.8)
# Roads remain at zorder=2 (now above other layers)

Testing: Generated before/after posters for Venice (water-heavy) and Barcelona (road-heavy)

Common Development Tasks

Adding a New Map Layer

Example: Adding railway lines to posters

create_map_poster.py (after line 558)

# 4. Fetch Railways
pbar.set_description("Downloading railway network")
railways = fetch_features(
    point,
    compensated_dist,
    tags={"railway": "rail"},
    name="railways",
)
pbar.update(1)  # Increment progress bar

Then render it (before roads, around line 594):

if railways is not None and not railways.empty:
    railways_lines = railways[railways.geometry.type.isin(["LineString", "MultiLineString"])]
    if not railways_lines.empty:
        railways_lines = railways_lines.to_crs(g_proj.graph['crs'])
        railways_lines.plot(ax=ax, color=THEME['railway'], linewidth=0.6, zorder=1.5)

Don’t forget:

Add "railway": "#...", to ALL theme JSON files (17 files)
Update load_theme() fallback dict at line 186
Update total in tqdm (line 526): total=4 instead of total=3
Test with cities that have railways (Tokyo, Paris, London)

Modifying Road Styling

To change how roads are colored/sized:

Color changes: Edit get_edge_colors_by_type() at line 255
Width changes: Edit get_edge_widths_by_type() at line 289
New road types: Add cases to both functions

Example - make motorways thicker:

def get_edge_widths_by_type(g):
    # ...
    if highway in ["motorway", "motorway_link"]:
        width = 1.5  # Changed from 1.2

Adjusting Typography

Text positioning uses normalized coordinates (0-1 range):

# City name at 14% from bottom
ax.text(0.5, 0.14, city_name, ...)

# Country at 10% from bottom  
ax.text(0.5, 0.10, country_name, ...)

# Coordinates at 7% from bottom
ax.text(0.5, 0.07, coords, ...)

To move labels higher/lower, adjust the y values (second argument). Font sizes scale with poster dimensions (see create_map_poster.py:618-681):

scale_factor = min(height, width) / 12.0
base_main = 60
adjusted_size = base_main * scale_factor

To make text bigger, increase base_main, base_sub, etc.

Performance Optimization

If you’re working on performance improvements:

Profiling

import cProfile
import pstats

# Add to create_poster() function:
def create_poster(...):
    profiler = cProfile.Profile()
    profiler.enable()
    
    # ... existing code ...
    
    profiler.disable()
    stats = pstats.Stats(profiler)
    stats.sort_stats('cumtime')
    stats.print_stats(20)  # Top 20 slowest functions

Common Bottlenecks

OSM data fetching: Already cached, but initial fetch is slow
- Solution: No way around this, OSM API is the bottleneck
- Use smallest effective distance
Graph projection: ox.project_graph() can be slow for large graphs
- Solution: Already optimized, but could cache projected graphs
Matplotlib rendering: plt.savefig() at high DPI
- Solution: Use lower DPI for previews, 300 DPI for final

Memory Usage

For very large cities (dist > 25km), memory usage can spike:

import tracemalloc

# At start of create_poster()
tracemalloc.start()

# At end
current, peak = tracemalloc.get_traced_memory()
print(f"Current: {current / 10**6:.1f}MB, Peak: {peak / 10**6:.1f}MB")
tracemalloc.stop()

Getting Help

Stuck on something? Here’s where to ask:

GitHub Discussions: Best for questions about contributing, architecture, or design decisions
GitHub Issues: For bugs you’ve found (check existing issues first)
Code Comments: Read inline comments in create_map_poster.py - they explain complex logic
This Documentation: Architecture Overview has detailed technical info

Changelog & Version History

When your PR is merged, it will be added to CHANGELOG.md. See Keep a Changelog format. Recent significant changes:

v0.3.0 (2026-01-27): Custom coordinates, emerald theme, default theme changed to terracotta
v0.2.1 (2026-01-18): SVG/PDF export, variable dimensions, caching improvements
v0.1.0 (2026-01-17): Initial release with 17 themes

Community contributions (unreleased):

uv package manager support (PR #20)
Z-order bug fix (PR #42, fixes #39)
Text scaling for landscape orientations (#112)

See full history in CHANGELOG.md.

License & Attribution

MapToPoster uses data from OpenStreetMap contributors. All posters must include the OSM attribution (automatically added at bottom-right):

© OpenStreetMap contributors

When contributing code, you agree to license it under the same terms as the project.

Thank You!

Every contribution - whether it’s a bug fix, new theme, documentation improvement, or feature enhancement - helps make MapToPoster better for everyone. Next Steps:

Set up your development environment
Browse open issues for ideas
Join discussions to share ideas
Read the Architecture Overview for deep technical details

Happy mapping! 🗺️

​Welcome Contributors

​Contribution Philosophy

​✅ We Welcome

​❌ Please Don’t Submit

​Development Setup

​Prerequisites

​Installation Methods

​Verify Installation

​Project Structure

​Key Files to Know

​Making Changes

​Development Workflow

​Testing Guidelines

​Manual Testing Checklist

​Test Coverage Areas

​Code Style Guidelines

​Python Conventions

​Example Function

​Comments

​Adding New Themes

​Creating a Theme

​Theme Design Tips

​Bug Fixes

​Reporting Bugs

​Example Bug Fix PR

​Common Development Tasks

​Adding a New Map Layer

​Modifying Road Styling

​Adjusting Typography

​Performance Optimization

​Profiling

​Common Bottlenecks

​Memory Usage

​Getting Help

​Changelog & Version History

​License & Attribution

​Thank You!

Welcome Contributors

Contribution Philosophy

✅ We Welcome

❌ Please Don’t Submit

Development Setup

Prerequisites

Installation Methods

Verify Installation

Project Structure

Key Files to Know

Making Changes

Development Workflow

Testing Guidelines

Manual Testing Checklist

Test Coverage Areas

Code Style Guidelines

Python Conventions

Example Function

Comments

Adding New Themes

Creating a Theme

Theme Design Tips

Bug Fixes

Reporting Bugs

Example Bug Fix PR

Common Development Tasks

Adding a New Map Layer

Modifying Road Styling

Adjusting Typography

Performance Optimization

Profiling

Common Bottlenecks

Memory Usage

Getting Help

Changelog & Version History

License & Attribution

Thank You!