How originalankur/maptoposter works
1. What this repo is
- A single-purpose Python command-line tool that generates static city map posters as PNGs.
- The repository is centered around one main executable script, not a server or library API.
2. Primary execution path
- The user invokes create_map_poster.py with city/country and optional styling parameters.
- The script resolves the city to coordinates, fetches map data, renders a poster, and writes the image into posters/.
3. Input boundary: CLI + configuration
- The CLI accepts geography inputs, optional coordinate overrides, poster size, map radius, theme selection, and multilingual display names.
- These inputs determine both the map extent and the final typography/styling, so they are the main control surface of the system.
4. Geocoding subsystem
- City and country names are converted to latitude/longitude using Nominatim.
- This is the first external dependency in the pipeline and establishes the map center unless manually overridden.
5. Map data acquisition subsystem
- The project uses OSMnx to pull OpenStreetMap graph and feature data around the chosen point.
- The fetched data includes roads and other geographic layers such as water and parks, which become separate visual layers in the final poster.
6. Rendering subsystem
- Matplotlib is the rendering engine and is responsible for composing the poster image.
- The visual stack is layered: background, water, parks, roads, gradient fades, then text and attribution on top.
- Road styling is derived from OpenStreetMap highway classes, with width and color mapped by road importance.
7. Theme system
- Theme files in themes/*.json define color palettes and visual behavior.
- Themes control the poster’s look-and-feel without changing rendering code, making them a clean configuration boundary.
- The --all-themes and --list-themes options indicate themes are treated as first-class runtime inputs.
8. Font and multilingual support
- font_management.py handles font loading and Google Fonts integration.
- Default fonts live in fonts/, while downloaded Google Fonts are cached locally in fonts/cache/.
- Script detection changes typography behavior: Latin scripts get spaced letter treatment, while non-Latin scripts retain natural spacing.
9. Output boundary
- Rendered posters are saved as timestamped PNG files in posters/.
- The output is a generated artifact, not a persistent application state; the repo also includes example poster images for documentation and regression reference.
10. Project layout and responsibilities
- create_map_poster.py: end-to-end orchestration of CLI, geocoding, fetching, styling, rendering, and file output.
- font_management.py: font discovery, caching, and Google Fonts handling.
- themes/: visual configuration data.
- fonts/: bundled font assets and cache.
- posters/: generated results and sample outputs.
11. Tooling and delivery
- The repo supports both uv and pip + venv workflows, with locked dependency management via uv.lock.
- pyproject.toml, requirements.txt, and .flake8 suggest linting and reproducible Python packaging are important, but the project remains a script-first tool.
- GitHub Actions workflows are present for PR checks and conflict automation, indicating basic CI around code quality rather than runtime infrastructure.
12. Testing and contributor workflow
- test/all_variations.sh implies manual or scripted generation checks across themes/variations.
- The README frames validation around visually inspecting before/after poster outputs, which makes output rendering quality a key correctness criterion.
Main entry points: create_map_poster.py Map Poster CLI · autumn.json Theme Config · font_management.py Font Manager · pyproject.toml Python Setup
Components 19
Runtime Pipeline
Main poster generation flow from inputs to PNG output.
- Map Poster CLI · End-to-end command-line entry point that coordinates the full poster build.
create_map_poster.py - Geocoding · Resolves city and country names into coordinates used as the map center.
create_map_poster.py - Map Fetching · Pulls OpenStreetMap graph and feature layers around the chosen location.
create_map_poster.py - Poster Rendering · Composes the layered poster image, including roads, land features, fades, text, and attribution.
create_map_poster.py - Road Styling · Maps OpenStreetMap highway classes to line width and color for visual hierarchy.
create_map_poster.py - Map Layers · Background, water, parks, roads, and gradient overlays that build the final scene.
create_map_poster.py - Typography · Handles titles, multilingual names, spacing behavior, and placement of labels.
create_map_poster.py - Font Manager · Discovers bundled fonts, loads Google Fonts, and manages local font cache.
font_management.py
Assets & Config
Bundled visual resources that shape poster appearance.
- Theme Config · Defines palettes and visual behavior that control poster styling without code changes.
themes/autumn.json - Fonts · Repository font files used as defaults and cache targets for downloaded fonts.
fonts - Poster Output · Timestamped poster images written to disk, plus sample outputs in the repo.
posters - Themes · Collection of poster style presets such as contrast, monochrome, and neon variants.
themes
Tooling & Delivery
Dependency management, CI, and validation workflows.
- CI Checks · Pull request validation and repository automation workflows.
.github/workflows/pr-checks.yml - Conflict Bot · GitHub workflow for conflict management and related maintenance automation.
.github/workflows/conflicts.yml - Python Setup · Dependency and environment definitions for uv, pip, and linting workflows.
pyproject.toml - Lockfile · Pinned dependency resolution for reproducible installs with uv.
uv.lock - Requirements · Alternate dependency manifest for pip-based environments.
requirements.txt - Variations Test · Scripted poster generation checks across theme and styling variations.
test/all_variations.sh - Project Docs · Human-facing description of usage, workflow, and release history.
README.md
Connections 20
- Map Poster CLI → Geocoding: resolve location · CLI inputs are converted into map-center coordinates.
- Map Poster CLI → Theme Config: select theme · Runtime theme selection changes the poster palette and styling.
- Map Poster CLI → Font Manager: load fonts · The script requests fonts for title and label rendering.
- Geocoding → Map Fetching: center map · Resolved coordinates determine where map data is fetched.
- Map Fetching → Road Styling: road graph · Road network data is classified into visual importance levels.
- Map Fetching → Map Layers: feature layers · Water, parks, and other geographic features become poster layers.
- Road Styling → Poster Rendering: style roads · Road widths and colors feed the rendering stack.
- Map Layers → Poster Rendering: compose scene · The rendering engine draws the layered map composition.
- Theme Config → Poster Rendering: colors and behavior · Theme values drive palette choices and visual effects.
- Font Manager → Typography: provide typefaces · Loaded fonts are used to render titles and multilingual names.
- Typography → Poster Rendering: overlay text · Typography is placed on top of the rendered map layers.
- Poster Rendering → Poster Output: write PNG · The final poster is saved as a generated image artifact.
- Fonts → Font Manager: bundled fonts · Local font assets are discovered and loaded by the font manager.
- Themes → Theme Config: theme files · JSON presets define poster appearance options.
- Python Setup → Lockfile: pin deps · Project packaging and dependency resolution are kept reproducible.
- Python Setup → Requirements: alternate install · Pip-based installation is supported alongside uv.
- CI Checks → Map Poster CLI: validate code · CI runs repository checks against the main poster script.
- Variations Test → Map Poster CLI: exercise outputs · The variation script generates posters to inspect visual correctness.
- Project Docs → Map Poster CLI: describe usage · Documentation explains invocation, options, and workflow.
- Project Docs → Theme Config: list presets · README and changelog help surface available themes and behavior.