Map Poster Studio

A premium, open-source Map Poster design tool that allows users to generate high-resolution map posters of any location in the world with curated styling themes and custom typography.

Features

• Real-time Map Selection: Interactive Leaflet map with precise location dragging.
• Reverse Geocoding: Automatically fetches City and Country based on map coordinates.
• Custom Typography: Premium Google Fonts integration with live preview.
• Curated Aesthetics: Multiple color themes (Noir, Midnight Blue, Blueprint, etc.) with thumbnail previews.
• High-Resolution Exports: Uses Python, OSMnx, and Matplotlib to generate print-ready .png posters.

Tech Stack

• Frontend: Next.js (App Router), React, TypeScript, Leaflet.js, Framer Motion
• Backend: FastAPI (Python), Uvicorn, OSMnx, Matplotlib, Geopy
• Data: OpenStreetMap (OSM) via Overpass API

---

Local Development Setup

1. Backend Setup

The backend requires Python 3.9+ and handles the heavy lifting of downloading map data and rendering the posters.

# Navigate to the project root
cd Maptoposter

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the FastAPI server
python web/backend/main.py

The backend will be running at http://localhost:8000.

2. Frontend Setup

The frontend is a modern Next.js application.

# Navigate to the frontend directory
cd web/frontend

# Install dependencies
npm install

# Start the development server
npm run dev

The frontend will be running at http://localhost:3000.

---

Deployment Guide

Deploying this application requires hosting the Next.js frontend and the FastAPI backend separately.

1. Deploying the Backend (FastAPI)

Since the backend uses osmnx and matplotlib, it requires a server with enough RAM to process large map grids. A VPS or a service like Render/Railway is recommended.

Using Render (Docker / Web Service)

1. Create a Dockerfile in the root (provided below) or just use the Python environment.
2. Push the repo to GitHub.
3. On Render, create a new "Web Service", connect your repo, and set the Root Directory to /.
4. Build Command: pip install -r requirements.txt
5. Start Command: uvicorn web.backend.main:app --host 0.0.0.0 --port $PORT

2. Deploying the Frontend (Next.js)

The easiest way to deploy a Next.js app is via Vercel.

1. Go to Vercel and import your GitHub repository.
2. Set the Root Directory to web/frontend.
3. Add an Environment Variable for the API URL:
   • NEXT_PUBLIC_API_URL = https://your-backend-url.onrender.com (Note: You will need to update fetch calls in the frontend to use this env variable instead of localhost)
4. Click Deploy.

Architecture Flow

1. User interacts with the UI (Leaflet).
2. Frontend sends lat, lon, distance, theme, and text to /api/generate-map.
3. Backend schedules a background task, downloads OSM data, and plots it with Matplotlib.
4. Frontend polls /api/task-status/{task_id} until completion.
5. Frontend fetches the final image from the generated /api/output/{filename} URL.