Skip to content

Home

Jump to bottom
aku1ra.dev edited this page Jan 23, 2026 · 1 revision

Naksakaar – Comprehensive Wiki

Naksakaar is a powerful, modernized fork of the original maptoposter project that transforms any city into stunning, high-resolution map posters using OpenStreetMap data. It introduces a sleek Web UI, performance enhancements, and rich aesthetic customization.

📌 Table of Contents

  1. Overview
  2. Key Features
  3. Architecture
  4. Installation
  5. Usage
  6. Themes & Aesthetics
  7. Customization Options
  8. Performance Optimizations
  9. Troubleshooting
  10. Contributing
  11. License
  12. Acknowledgements

Overview

Naksakaar reimagines the map poster generation workflow by combining geographic data from OpenStreetMap with artistic design principles. Built on Python and Flask, it offers both CLI and Web-based interfaces for generating print-ready or digital posters with full control over layout, detail, and visual style.

Key Features

🎨 Visual Design

  • 9 Unique Themes: From Cyberpunk Neon to Vintage Travel Posters.
  • Dark Mode Web UI: Glassmorphic, borderless interface with deep blacks and sharp edges.
  • Font Customization: Uses the modern Inter font family with variable weights.

🖥️ Web Interface (webui/)

  • Real-time preview with infinite panning and zooming.
  • Preset + custom dimensions (pixels or inches), with automatic DPI conversion.
  • Live progress tracking during poster generation.
  • Built with Flask for seamless integration with the core engine.

⚙️ Core Engine (naksaengine/)

  • Parallel data fetching via ThreadPoolExecutor.
  • Configurable graph simplification tolerance.
  • Robust error handling for headless environments (e.g., servers without GUI).
  • Fixed race conditions in file saving to prevent 404 errors.

🛠️ User Experience

  • “Detail Density” presets: Minimal, Balanced, High, Maximum.
  • Standalone app.py server wraps CLI tools into a user-friendly experience.
  • Relative path support—run from any subdirectory.

Architecture

naksakaar/
├── naksaengine/        # Core rendering engine (Python)
│   ├── naksamain.py    # Main CLI entry point
│   └── requirements.txt
├── webui/              # Flask-based Web UI
│   └── app.py          # Web server + API endpoints
└── README.md
  • Frontend: HTML/CSS/JS served via Flask (no external framework).
  • Backend: Python with osmnx, matplotlib, Pillow, and Flask.
  • Data Source: OpenStreetMap via osmnx.

Installation

Prerequisites

  • Python 3.8+
  • Git

Steps

# Clone the repository
git clone https://github.com/aku1dev/naksakaar.git
cd naksakaar

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate        # Linux/macOS
# OR
.venv\Scripts\activate           # Windows

# Install dependencies
pip install -r naksaengine/requirements.txt

💡 Ensure you're in the root naksakaar directory when running these commands.

Usage

Command-Line Interface (CLI)

Navigate to the engine directory:

cd naksaengine

Basic Example

python naksamain.py --city "Kathmandu" --country "Nepal" --detail high

Advanced Example

python naksamain.py \
  --city "Tokyo" \
  --country "Japan" \
  --theme cyberpunk_neon \
  --width 24 \
  --height 36 \
  --quality 300

CLI Arguments

Flag Description Default
--city City name (required) —
--country Country name (required) —
--theme Theme name (see Themes) salleri_standard
--width Poster width (inches or pixels) 18
--height Poster height (inches or pixels) 24
--quality DPI (dots per inch) 150
--detail Detail level: minimal, balanced, high, maximum balanced

📏 If --width/--height are < 100, interpreted as inches; ≥100 → pixels.

Web User Interface (Web UI)

cd webui
python app.py

Then open your browser to:
👉 http://localhost:8006

Web UI Features

  • Interactive map preview with pan/zoom.
  • Dropdowns for theme, detail level, and size presets (Instagram, A4, etc.).
  • Manual input for custom dimensions.
  • Real-time generation status updates.
  • Auto-download upon completion.

Themes & Aesthetics

Naksakaar includes 9 hand-crafted visual themes:

Theme Description
Salleri Collection Clean, high-contrast palettes optimized for readability and elegance.
Cyberpunk Neon Dreams Futuristic glow with electric blues, magentas, and dark backgrounds.
Vintage Travel Poster 1950s-inspired warm sepia tones, bold outlines, nostalgic feel.
Arctic Explorer Cool ice blues, whites, and grays—ideal for polar or mountainous regions.
Desert Mirage Golden sands, burnt oranges, and soft gradients evoking arid landscapes.
Midnight Jazz Club Deep burgundy, charcoal, and gold—moody and sophisticated.
Tropical Paradise Vibrant corals, turquoise waters, lush greens for coastal cities.
(+2 more in development) Check naksaengine/themes/ for latest list.

Themes are defined as JSON or Python dictionaries controlling:

  • Road colors by type
  • Background color
  • Text/font styling
  • POI visibility

Customization Options

Detail Density Presets

Abstracts complex OSM layer toggles:

  • Minimal: Only major roads & labels.
  • Balanced: Adds neighborhoods and key landmarks.
  • High: Includes minor streets, parks, water bodies.
  • Maximum: Full OSM detail (may slow rendering).

Output Control

  • DPI: Set print quality (72 for web, 300+ for print).
  • Aspect Ratio: Freeform—no fixed ratios enforced.
  • File Format: PNG (default), with plans for PDF/SVG export.

Performance Optimizations

  • ✅ Parallel OSM Data Fetching: Uses concurrent.futures.ThreadPoolExecutor to download graph tiles concurrently.
  • ✅ Path Handling: Fully relative paths—run from any working directory.
  • ✅ Graph Simplification: Adjustable tolerance to balance detail vs. speed.
  • ✅ Headless Safety: Graceful fallbacks for matplotlib backends in Docker/cloud environments.
  • ✅ Race Condition Fixes: Atomic file writes prevent broken image links in Web UI.

Troubleshooting

Common Issues

Issue Solution
ModuleNotFoundError Ensure you activated the virtual env and installed requirements.txt.
Blank/white output Try lowering --detail or --quality; may be memory-limited.
Web UI not loading images Check console for 404s; ensure static/ folder is writable.
Slow generation for large cities Use --detail minimal or increase system RAM.
Font errors The Inter font is embedded; if missing, install via system or use fallback.

Debugging Tips

  • Run CLI version first to isolate Web UI issues.
  • Enable Flask debug mode: FLASK_ENV=development python app.py
  • Monitor memory usage—large maps can exceed 2GB RAM.

Contributing

We welcome contributions! Here’s how:

  1. Fork the repo.
  2. Create a feature branch: git checkout -b feat/my-theme
  3. Commit changes: git commit -am 'Add tropical sunset theme'
  4. Push: git push origin feat/my-theme
  5. Open a Pull Request.

Areas Needing Help

  • Additional themes
  • Multi-language support
  • Vector (SVG/PDF) export
  • Mobile-responsive Web UI
  • Caching for repeated city renders

License

MIT License
Copyright © 2026 aku1ra.dev
Based on original work by Ankur (originalankur/maptoposter)

See LICENSE for details.

Acknowledgements

  • Original Project: maptoposter by Ankur
  • Data Source: OpenStreetMap (ODbL)
  • Libraries: osmnx, matplotlib, Flask, Pillow, networkx
  • Font: Inter by Rasmus Andersson

🌍 Turn any city into art.
Naksakaar — Where geography meets design.

Clone this wiki locally