map-to-poster README

The project's README from github.com/dimartarmizi/map-to-poster. As one markdown file: README.md.

MapToPoster JS Logo

MapToPoster JS

HTML5 CSS3 JavaScript Tailwind CSS Leaflet MapLibre Vite

MapToPoster JS is a professional-grade, client-side web application designed to help you generate a custom Map To Poster with ease. Whether you're looking to create minimalist city art or a vibrant geographic keepsake, this tool allows you to search for any location in the world and transform it into a stunning Map To Poster piece with fully customizable themes, layouts, and high-fidelity export options. As a versatile Map To Poster generator, the application focuses on high-resolution output suitable for large-format printing, making it the perfect tool for creating unique wall art or personalized gifts.

MapToPoster JS Preview

🚀 Key Features

🎨 Themes

MapToPoster JS offers two distinct ways to style your maps:

Standard Themes (Leaflet)

Based on high-quality raster tiles from established providers:

Artistic Themes (MapLibre GL)

Hand-crafted vector styles with procedural colors:

Customizing Themes

You can easily add your own artistic themes by editing src/core/artistic-themes.js:

  1. Open artistic-themes.js.
  2. Add a new object to the artisticThemes export:
your_theme_key: {
    name: "Your Theme Name",
    description: "Brief description of the style",
    bg: "#HEXCODE",
    text: "#HEXCODE",
    water: "#HEXCODE",
    parks: "#HEXCODE",
    road_motorway: "#HEXCODE",
    road_primary: "#HEXCODE",
    road_secondary: "#HEXCODE",
    road_default: "#HEXCODE"
}

The application will automatically pick up the new theme and display it in the selection menu.

🛠️ Tech Stack

📦 Getting Started

Follow these steps to get a local copy up and running.

Prerequisites

Installation & Setup

  1. Clone the repository

    git clone https://github.com/dimartarmizi/map-to-poster.git
cd map-to-poster

  2. Install dependencies

    npm install

  3. Start development server

    npm run dev

    The app will be available at http://localhost:5173.

  4. Build for production

    npm run build

    Optimized files will be generated in the dist/ folder.

🐳 Deploy with Docker

This project is ready to run as a lightweight Docker container using a multi-stage build:

Build the image

docker build -t map-to-poster .

Run the container

docker run -d -p 8080:80 --name map-to-poster map-to-poster

Then open http://localhost:8080.

Update deployment

After pulling new changes, rebuild and recreate the container:

docker build -t map-to-poster .
docker rm -f map-to-poster
docker run -d -p 8080:80 --name map-to-poster map-to-poster

Included Docker files

📜 Technical Overview

  1. Reactive State Management: Uses an observer-pattern based store (src/core/state.js) to synchronize changes across the UI, Leaflet, and MapLibre engines. All user preferences are persisted via localStorage.
  2. Hybrid Mapping Engine: Implements bidirectional viewport synchronization between Leaflet (raster tiles) and MapLibre GL (vector themes), ensuring seamless layout consistency regardless of the active rendering mode.
  3. Draggable Overlay System: Leverages real-time bounding box calculations to clamp label positions, ensuring a symmetric 8px minimum safety gap from the poster edges.
  4. Dynamic Asset Integration: Manages custom GeoJSON routing and multi-marker instances with interactive drag-and-drop support across both map engines.
  5. Mat Framing Layer: Implements a virtual "Mat/Passepartout" interface with customizable inset spacing and inner borders for a gallery-style finish.
  6. High-Fidelity Rendering Pipeline: Captured exports utilize a multi-stage process in src/core/export.js to generate high-resolution map snapshots using html2canvas and the onclone callback.

🤝 Credits

📧 Contact

If you have any questions, suggestions, or just want to reach out, feel free to contact me at [email protected].

⚖️ License

This project is open-source and available under the MIT License.

map-to-poster (dimartarmizi/map-to-poster)

Searching Database…

1.1K ·GitHub
Map-to-poster
What is this?MapToPoster JS is a client-side web app that turns any location into a customizable, high-resolution map poster you can export as a PNG for printing.
Is this a hosted service or does it run entirely in my browser?It's a web app built with vanilla JavaScript and Vite that runs fully client-side; all rendering happens in the browser and nothing is sent to a server.
How do I get it running locally?Clone the repo, install dependencies with npm, then run the Vite dev server; for production it can also be built into static files or run via the included multi-stage Docker setup with Nginx.
What do I need installed to run it?You need Node.js 18.0.0 or higher and npm (bundled with Node) to install dependencies and run the Vite build.
Does it rely on any external services for search or routing?Yes, location search uses the Nominatim API and route plotting uses OSRM, so those features need an internet connection even though rendering itself is local.
Does any of my map data leave my computer?No, the app persists your settings in LocalStorage and renders entirely client-side, so your poster data stays in your browser.
What's the difference between the standard and artistic themes?Standard themes (Minimal White, Midnight Dark, Classic Street, Modern Voyager, Satellite View) use raster map tiles via Leaflet, while artistic themes like Arctic Frost or Cyber Glitch are hand-crafted procedural vector styles rendered with MapLibre GL.
How high-resolution can an exported poster be?You can export custom PNG resolutions up to 50,000px for large-format printing.
Can I add my own custom theme?Yes, you can add new artistic themes by editing a single object in src/core/artistic-themes.js and it will automatically appear in the theme selection menu.
Is this an original project or based on something else?It's inspired by originalankur/maptoposter but is an independent implementation with a different stack and architecture (Vanilla JS, Vite, Tailwind CSS).
What are similar projects?terraink, Leaflet, mapcn, bible-strong-avatar-lab, maplibre-gl-js, wavedigger, kepler.gl, GeoLibre
Which topics is it in?maplibre, poster, gis, maps, nginx, tailwindcss, vite, design, customization, local-first, web-app, privacy
Creator
dimartarmizi
Size
0.6 MB
Stars
1.1K
Updated
CommitJun 06
Age
7mo
Commits · 90 Days