The studio-grade, open-source cartographic poster design engine & vector GIS platform.
Transform real-world geospatial data and GPX tracks into museum-quality, 4K / 300 DPI print-ready wall art.

Overview • Gallery • Demos • Why Mapfolio? • Features • Shortcuts • Architecture • Tech Stack • Acknowledgements • Quick Start • Deployment • Contributing

---

🧭 Overview

Mapfolio is a modern, high-precision cartographic workstation built from the ground up for designers, runners, cyclists, travelers, architects, and GIS enthusiasts.

Traditional poster creators rely on browser screenshots or lossy DOM rasterizers that produce pixelated typography, blurred line weights, and misaligned coordinates. Mapfolio solves this with a dedicated Direct-to-Canvas 4K Compositor that rasterizes vector map tiles, road geometries, custom fonts, route waypoints, and decorative accents onto a master 300 DPI graphics buffer.

┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                       MAPFOLIO WORKSTATION                                       │
├───────────────────────────────┬──────────────────────────────────┬───────────────────────────────┤
│       VECTOR GIS CORE         │       POSTER COMPOSITOR          │      MASTER EXPORT ENGINE     │
│  • MapLibre GL v3 Engine      │  • 12+ Curated Theme Palettes    │  • 4K Ultra-HD Resolution     │
│  • OpenFreeMap Global Tiles   │  • 18+ Designer Google Fonts     │  • 300 DPI Print Quality      │
│  • OSRM Real-Time Routing     │  • Aspect Ratio Presets (1:1/4:5)│  • Direct-to-Canvas Buffer    │
│  • Strava/Garmin GPX Parser   │  • Dynamic Gradient Vignettes    │  • Lossless PNG, JPEG & WebP  │
│  • Zero-Token Open Source     │  • Custom Vector Markers & Pins  │  • Scale-Proof Pixel Layout   │
└───────────────────────────────┴──────────────────────────────────┴───────────────────────────────┘

---

📸 Gallery & Print Showcase

Explore real 4K / 300 DPI exports rendered directly with Mapfolio's vector engine across global cities (click any image to inspect full-resolution master on Google Drive):

---

🎬 Live Demos & Feature Walkthroughs

Watch Mapfolio's vector rendering engine in action (click to view full screen master):

🎨 Real-Time Palette & Theme Switching	🚴 Road-Snapped Route Builder

🏙️ 3D Building Extrusion & Architectural Pitch Tilt

---

⚡ Why Mapfolio?

Capability	Mapfolio Studio	Generic Screenshot Tools	Paid Commercial SaaS
Output Resolution	🟢 4K UHD (300 DPI Canvas)	🔴 72 DPI (Screen Grab)	🟡 300 DPI (Paid Export)
Tile Infrastructure	🟢 OpenFreeMap (0 Tokens)	🔴 Raster Screenshots	🟡 Mapbox (Paid Token Req.)
GPX & Strava Tracks	🟢 Road-Snapped (OSRM)	🔴 Not Supported	🟡 Basic Overlay
Layer & Paint Control	🟢 Full RGB Hex Overrides	🔴 None	🟡 Limited / Preset Only
Typography Engine	🟢 18+ Paired Google Fonts	🔴 System Defaults	🟡 Fixed Templates
3D Building Extrusions	🟢 Real-time WebGL (60 FPS)	🔴 2D Flat Only	🟡 Static 2.5D
License & Pricing	🟢 100% Free & MIT Licensed	🔴 Closed Source	🔴 Monthly Subscription

---

✨ Feature Matrix

🗺️ Vector Cartographic Canvas

• Global OpenFreeMap Tiles: Full worldwide vector map data powered by OpenMapTiles and OpenFreeMap. Instant loading with zero required API keys.
• Hardware-Accelerated WebGL: Fluid 60 FPS viewport with dynamic pitch, bearing, continuous zoom, and regional overview background viewing.
• Layer Visibility Granularity: Real-time toggling for terrain hillshading, waterways, railway networks, primary/secondary highways, and 3D building extrusions.

🎨 Curated Design Themes & Custom Palette Engine

• Designer Presets:
  • Noir Dark — Deep obsidian contrast for modern interiors.
  • Minimal Slate — Refined architectural grayscale aesthetic.
  • Vintage Sepia — Classic aged parchment and copper hues.
  • Cyberpunk Neon — Electric magenta and cyan glow lines.
  • Terracotta — Warm Mediterranean clay and earth tones.
  • Midnight Ocean — Nautical navy with bright cobalt water accents.
  • Nordic Minimal, Blueprint, Japanese Forest, Warm Sand & more.
• Color Override Engine: Complete individual color control over land, water bodies, waterways, parks, aeroways, buildings, roads (motorways, primary, secondary, paths), and rail tracks.

🚴 Road-Snapped Route Builder & GPX Track Visualizer

• OSRM Intelligent Snapping: Click waypoints on the map to automatically trace accurate road paths for Driving, Cycling, or Walking.
• GPX File Drag-and-Drop: Import athletic activities directly from Strava, Garmin Connect, Komoot, or AllTrails.
• Path Customization: Adjust stroke width (1px to 64px), line color, dashed/dotted/neon-glow casing, and numbered waypoint marker badges.

📍 Custom Map Pins & Landmark Badges

• Icon Catalog: Classic Pin, Dot Marker, Crosshair, Target Scope, Star, Heart, Home, Landmark, Compass, and Custom Image Uploads.
• Dynamic Sizing: Smooth scale presets (SM, MD, LG, XL, 2XL, 3XL) or continuous pixel sizing (16px – 256px).
• Floating Labels: High-contrast, typography-scaled custom text badges attached to any pinpointed coordinate.

🖨️ Pixel-Perfect 4K Master Export Engine

• Direct-to-Canvas Compositing: Eliminates CSS transform scaling distortions and html-to-image top-left alignment bugs by painting directly onto an off-screen high-DPI raster canvas.
• Standard Poster Formats:
  • Classic Portrait (4:5)
  • Modern Portrait (2:3)
  • Gallery Square (1:1)
  • Cinema Wide (16:9)
  • Panoramic Landscape (21:9)
  • ISO Standards (A1, A2, A3, A4)
• Lossless Output Formats: Instant download in PNG, JPEG, and WebP with configurable quality parameters.

---

⌨️ Interactive Controls & Shortcuts

Mapfolio includes an ergonomic floating HUD and keyboard shortcuts for rapid studio workflow:

Key	Tool / Action	Description
1	Theme Studio	Open curated palettes and individual layer paint controls
2	Layout & Frame	Select aspect ratios, dimensions, borders, and margins
3	Typography	Configure titles, subtitles, coordinates, and font families
4	Route Builder	Draw road-snapped paths or drag-and-drop GPX activity files
5	Location Pins	Place and customize landmark markers, icons, and labels
6	Layer Visibility	Toggle terrain, buildings, roads, waterways, and railways
7	Export Dialog	Open master 4K / 300 DPI canvas export settings
Space	Lock Viewport	Lock map movement to prevent accidental panning while designing
R	3D Rotation	Toggle 3D pitch and bearing tilt controls

---

🏗️ Architecture & Engine

                             ┌───────────────────────────────────┐
                             │      React 19 + TypeScript        │
                             │         (Vite 5 Bundler)          │
                             └─────────────────┬─────────────────┘
                                               │
               ┌───────────────────────────────┼───────────────────────────────┐
               ▼                               ▼                               ▼
    ┌──────────────────────┐        ┌──────────────────────┐        ┌──────────────────────┐
    │     Zustand Store    │        │    MapLibre GL v3    │        │     Master Canvas    │
    │  • Coordinates & Zoom│        │  • OpenFreeMap Planet│        │  • 4K Raster Buffer  │
    │  • Color Overrides   │───────►│  • Dynamic Style Spec│───────►│  • Vector Font Metric│
    │  • GPX Waypoints     │        │  • WebGL Render Loop │        │  • Direct PNG Export │
    │  • Active Framing    │        │  • OSRM Road Snapper │        │  • Vignette Overlays │
    └──────────────────────┘        └──────────────────────┘        └──────────────────────┘

Module Overview

• src/components/PosterMap.tsx: High-performance MapLibre GL wrapper utilizing react-map-gl/maplibre with WebGL viewport sync and vector feature snapping.
• src/utils/generateMapStyle.ts: Pure function compiler converting palette state into dynamic MapLibre Style Specification JSON with OpenFreeMap vector layers.
• src/utils/mapExport.ts: Master export compositor rendering map frames, vector paths, SVG badges, and Google typography directly to a 300 DPI HTML5 canvas.
• src/store/useMapStore.ts: High-throughput Zustand store managing viewport parameters, color overrides, markers, and custom themes.

---

🛠️ Tech Stack

Category	Technology	Version	Description
Frontend Framework	React	19.x	Declarative UI library for building interactive interfaces
Language	TypeScript	~6.0	Strongly typed JavaScript superset for safer, scalable code
Build Tool	Vite	5.4	Next-generation frontend build tool with instant HMR
2D Map Engine	MapLibre GL JS	3.6	Open-source WebGL-powered vector map rendering engine
React Map Bindings	react-map-gl	7.1	React wrapper for MapLibre/Mapbox GL map components
3D Globe Engine	CesiumJS	1.144	Open-source 3D geospatial visualization with photorealistic terrain
React Cesium Bindings	Resium	1.25	React component library for CesiumJS
State Management	Zustand	3.7	Lightweight, hook-based state management for React
Styling	Tailwind CSS	4.x	Utility-first CSS framework for rapid UI development
CSS Utilities	tailwind-merge	3.6	Intelligent Tailwind class merging without conflicts
CSS Utilities	clsx	2.1	Tiny utility for conditionally constructing className strings
Icons	Lucide React	0.468	Beautiful, consistent open-source icon library
Typography	Google Fonts	—	20+ curated designer typefaces (Inter, Playfair Display, Bebas Neue, etc.)
Database	Neon Serverless Postgres	1.1	Serverless PostgreSQL for persistent data
ORM	Drizzle ORM	0.45	Lightweight, type-safe TypeScript ORM
Linting	ESLint	10.x	Pluggable JavaScript/TypeScript linter
CSS Processing	PostCSS + Autoprefixer	8.x / 10.x	CSS transforms and automatic vendor prefixing

🌐 Open-Source APIs & Data Services

Service	Provider	Usage	License / Terms
OpenFreeMap	OpenFreeMap	Global vector map tile hosting (zero API tokens)	Open-source
OpenMapTiles	MapTiler / Community	Vector tile schema powering OpenFreeMap layers	BSD-3-Clause
OpenStreetMap	OSM Contributors	Underlying geographic data for all map tiles	ODbL 1.0
OSRM	Project OSRM	Road-snapped routing for driving, cycling, and walking	BSD-2-Clause
openstreetmap.de Routing	FOSSGIS e.V.	Secondary OSRM mirror for routing redundancy	BSD-2-Clause
BRouter	BRouter	3D topographic routing with SRTM elevation profiles	MIT
Nominatim	OSM Foundation	Forward & reverse geocoding for location search	ODbL 1.0 (data)
Google Fonts	Google	20+ curated web fonts for poster typography engine	Apache 2.0 / OFL
Cesium ion	Cesium GS, Inc.	3D world terrain, OSM buildings, and globe imagery	Commercial (free tier)

---

📦 Open-Source Acknowledgements

Mapfolio is built on the shoulders of incredible open-source projects. We are grateful to every contributor and maintainer who makes this ecosystem possible.

Core Libraries

Library	License	Repository
React	MIT	facebook/react
TypeScript	Apache-2.0	microsoft/TypeScript
Vite	MIT	vitejs/vite
MapLibre GL JS	BSD-3-Clause	maplibre/maplibre-gl-js
react-map-gl	MIT	visgl/react-map-gl
CesiumJS	Apache-2.0	CesiumGS/cesium
Resium	MIT	reearth/resium
Zustand	MIT	pmndrs/zustand
Tailwind CSS	MIT	tailwindlabs/tailwindcss
Lucide	ISC	lucide-icons/lucide
Drizzle ORM	Apache-2.0	drizzle-team/drizzle-orm
clsx	MIT	lukeed/clsx
tailwind-merge	MIT	dcastil/tailwind-merge

Dev Tooling

Tool	License	Repository
ESLint	MIT	eslint/eslint
PostCSS	MIT	postcss/postcss
Autoprefixer	MIT	postcss/autoprefixer
@vitejs/plugin-react	MIT	vitejs/vite-plugin-react
tsx	MIT	privatenumber/tsx
dotenv	BSD-2-Clause	motdotla/dotenv

Data & Tile Infrastructure

Source	License	Link
OpenStreetMap Data	ODbL 1.0	openstreetmap.org
OpenFreeMap Tiles	Open-source	openfreemap.org
OpenMapTiles Schema	BSD-3-Clause	openmaptiles.org
OSRM Routing Engine	BSD-2-Clause	project-osrm.org
BRouter Topographic Engine	MIT	brouter.de
Nominatim Geocoder	GPL-2.0 (code) / ODbL (data)	nominatim.org
Google Fonts	Apache-2.0 / OFL	fonts.google.com

Note: All trademarks and project names belong to their respective owners. Mapfolio is an independent open-source project and is not affiliated with or endorsed by any of the above services.

---

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/Anurag-amrev-7557/mapfolio.git
cd mapfolio

2. Configure Environment (Optional)

cp .env.example .env

3. Install Dependencies

npm install

4. Start Development Server

npm run dev

The application will be running locally at http://localhost:5173.

5. Build for Production

npm run build

---

🌐 Deployment

Cloudflare Pages (Recommended)

1. Connect your repository in the Cloudflare Dashboard under Workers & Pages → Create application → Pages.
2. Configure build settings:
   • Framework preset: Vite
   • Build command: npm run build
   • Build output directory: dist
   • Node.js Version: 18 or higher
3. Click Save and Deploy.

One-Command Wrangler CLI Deploy

npm run build
npx wrangler pages deploy dist --project-name=mapfolio

Docker Deployment

# Build Docker image
docker build -f Dockerfile.frontend -t mapfolio .

# Run container on port 80
docker run -d -p 80:80 --name mapfolio-app mapfolio

---

🤝 Community & Contributing

Contributions make the open-source community an incredible place to learn, inspire, and create!

• 📖 Contributing Guide — Workflow, branching, and pull request standards.
• 🛡️ Security Policy — Coordinated vulnerability disclosure guidelines.
• 📜 Code of Conduct — Contributor Covenant 2.1 community standards.
• 🐛 Report a Bug
• ✨ Request a Feature

---

📈 Star History

---

📄 License

Distributed under the MIT License. See LICENSE for complete details.

---

_{Crafted with precision for cartographers, designers, and outdoor athletes worldwide.}

⭐ Star this repository if you find Mapfolio inspiring!