🗺️ CARTIVA

Turn cities into art.

Transform any place on Earth into stunning, customizable map artwork & gallery-grade city posters.

Key Features • System Architecture • Style Presets • Getting Started • Roadmap • Author

---

🌟 Why CARTIVA?

Traditional mapping platforms are engineered strictly for navigation or GIS analysis, while existing artistic tools like City Roads or Pretty Maps are either limited to road lines only or require complex Python scripting environments without real-time interactive previews.

CARTIVA is a modern, high-performance browser-based creative instrument that bridges geographic data fidelity with professional poster design:

• 🏙️ Rich Multi-Layer Geography: Independently style and filter highways, primary avenues, residential streets, pedestrian walkways, waterways, water bodies, coastlines, urban parks, forests, and building footprints.
• 🎨 30+ Curated Theme Presets: From sleek minimalist line art and high-contrast monochrome to neon cyberpunk, synthwave, vintage parchment, and architectural blueprints.
• ✨ AI & Semantic Styling: Generate tailored visual themes from natural language prompts ("Cyberpunk Tokyo 2080 with cyan roads and dark navy background") or extract custom harmonic palettes directly from uploaded screenshots and city photography.
• 📐 Print-Ready High-DPI Export: Export gallery-quality raster images (PNG, WebP, JPEG) at 300 DPI, vector SVG documents for plotters and design tools, or direct physical PDF posters (A4, A3, 50×70cm).
• 💾 Local-First & Offline Resilient: Zero server dependencies, private IndexedDB project storage, and instant fallback geometry generation when external networks are congested.

---

🏗️ System Architecture

graph TD
    User([User / Browser]) -->|Search / Pan / Prompt| App[Cartiva Web App]

    subgraph Presentation & State
        App --> ViewRouter[View Router]
        ViewRouter --> Landing[Landing Showcase]
        ViewRouter --> Search[Geocoding & Discovery]
        ViewRouter --> Editor[Studio Workspace]
        
        Editor --> Zustand[Zustand Reactive State]
        Zustand --> MapStore[Map Layer Store]
        Zustand --> StyleStore[Style & Theme Store]
        Zustand --> AppStore[App & UI Store]
    end

    subgraph Geospatial Pipeline
        Search --> Geocoding[Nominatim Geocoding API]
        Editor --> Overpass[Unified Overpass API Engine]
        Overpass --> FallbackEngine[Synthetic Fallback Engine]
        Geocoding --> NominatimCache[LRU Geocoding Cache]
    end

    subgraph AI & Creative Engine
        Editor --> AIParser[Natural Language Style Parser]
        Editor --> VisionQuantizer[Image & Screenshot Palette Extractor]
        Editor --> AutoComposer[Smart Layout Composer]
    end

    subgraph High-Performance Rendering & Export
        Editor --> CanvasEngine[Batched Canvas 2D / WebGL Renderer]
        CanvasEngine --> DisplayCanvas[Interactive Viewport Canvas]
        CanvasEngine --> OffscreenCanvas[300 DPI Offscreen Canvas]
        
        OffscreenCanvas --> PNGExport[PNG / WebP / JPEG Exporter]
        OffscreenCanvas --> PDFEngine[jsPDF Print Generator]
        CanvasEngine --> SVGExport[Vector SVG Serializer]
    end

    subgraph Persistence Layer
        Editor --> DexieDB[(IndexedDB / Dexie)]
        DexieDB --> LocalProjects[Local Projects Store]
        LocalProjects --> JSONExporter[Cartiva JSON Importer/Exporter]
    end

Loading

Architectural Highlights

1. Batched Geometry Rendering (Sub-5ms Frame Times):

   • High-density urban maps with 20,000+ line segments are batched into continuous Path2D passes rather than executing per-feature draw calls.
   • Multi-pass shader simulation delivers glowing neon roads without CPU filter stalls.

2. Resilient 4-Tier Geospatial Pipeline:

   • Tier 1: Debounced, rate-limited Nominatim geocoding with in-memory LRU caching.
   • Tier 2: Single unified Overpass QL query combining highways, primary roads, water bodies, waterways, parks, and forests into 1 parallel network request.
   • Tier 3: Automatic Mercator coordinate transformation and viewport clipping.
   • Tier 4: Instant offline synthetic geometry generation ensuring zero UI blocking during network latency.

3. Client-Side AI & Vision Intelligence:

   • Natural language aesthetic tokenizer converts descriptive color keywords, hex codes, and mood archetypes into structured MapStyle objects.
   • Offscreen Canvas color quantization extracts 6-pole dominant harmonic palettes from uploaded screenshots and photography without server roundtrips.

---

📁 Repository Structure

cartiva/
├── .github/
│   └── workflows/ci.yml       # Automated GitHub Actions CI pipeline
├── public/
│   ├── favicon.svg            # Vector brand mark
│   ├── manifest.json          # PWA Web App manifest
│   └── sw.js                  # Service Worker offline shell cache
├── src/
│   ├── features/
│   │   ├── ai/                # Natural language style synthesizer & image palette extractor
│   │   ├── editor/            # Interactive studio workspace & properties controls
│   │   ├── landing/           # Landing page showcase & style gallery
│   │   ├── renderer/          # Batched Canvas 2D engine, PDF & SVG export pipeline
│   │   ├── search/            # Location geocoding & discovery view
│   │   └── styles/            # 30+ curated theme presets
│   ├── infrastructure/        # Nominatim geocoder, Overpass client, Dexie DB
│   ├── stores/                # Atomic Zustand state stores
│   ├── tests/                 # Vitest automated unit & integration test suites
│   ├── types/                 # Strict TypeScript domain definitions
│   ├── App.tsx                # View router & global toast provider
│   ├── index.css              # Design system tokens & CSS variables
│   └── main.tsx               # Application entry point
├── package.json
├── tsconfig.json
└── vite.config.ts

---

🚀 Key Features

1. Multi-Layer Geographic Engine

• Road Network Hierarchy: Motorways, Primary, Secondary, Tertiary, Residential, Pedestrian, and Cycleways with individual stroke widths, opacities, and glow shaders.
• Natural Hydrography: Lakes, reservoirs, rivers, streams, and coastlines with custom fill textures and line strokes.
• Urban Greenery: Parks, nature reserves, gardens, and dense forests with adjustable opacity and soft fills.
• Structural Urban Fabric: Building footprints and administrative boundaries.

2. Interactive Studio Editor

• Direct Canvas Manipulation: Click and drag map framing (pan), 360° map rotation, and typography elements directly on the canvas.
• Framing & Poster Masks: Full Canvas, Circular Vignette Mask, and architectural Inset Frame borders (Single line, Double line, Corner Crosshairs).
• Map Orientation & Rotation: Continuous 0°–360° rotation slider with 1-click cardinal orientation presets (0° North, 90° East, 180° South, 270° West).
• Analog & Cinematic Shaders: Radial vignette shading, film grain noise simulation, and ultra-fast multi-pass glow.
• Typography Studio: Dynamic title, subtitle, and latitude/longitude coordinate labels with customizable fonts (Space Grotesk, Inter, JetBrains Mono, Cinzel, Playfair Display), letter spacing, text alignment, decorative divider rules, and casing.
• Aspect Ratio & Frame Presets: Square (1:1), Portrait (4:5), Poster (2:3), Landscape (16:9), Instagram Story (9:16), A4, and A3 prints with adjustable frame margins.
• 1-Click Palette Modifiers: Invert Day/Night palette, master road recolor, and universal text color sync.

3. AI & Vision Capabilities

• Natural Language Style Synthesizer: Converts descriptive text into structured color, width, and lighting parameters.
• Image & Screenshot Palette Extractor: Uses client-side color quantization to sample dominant tones from reference photos and apply them as a new map style.
• Smart Composition Assistant: Auto-calculates optimal typography sizing and spacing based on city name length and mood.

---

🎨 Curated Style Presets

Category	Presets
Dark & Minimal	Midnight (Default), Minimal Light, Florence, Nordic Mist, Monochrome, Noir, High Contrast, Night Drive
Futuristic & Glow	Solar Flare, Neon, Cyberpunk, Synthwave, Matrix, Terminal, Electric, Cosmic
Nature & Earth	Ocean, Forest, Sunset, Aurora, Arctic, Emerald & Gold, Terracotta
Vintage & Heritage	Florence Cream, Japanese Ink (Sumi-e), Vintage Copper, Heritage Cartography, Sepia
Artistic & Modern	Blueprint, Brutalist Concrete, Gold Luxury, Silver Metallic, Vaporwave

---

🔮 Roadmap & Future Horizons

CARTIVA is continuously evolving towards the frontier of creative cartography and generative art:

• 🏙️ City Posters: Automated gallery-grade poster framing with print bleed margins and metadata stamping.
• 🌐 Generative Cartography: Algorithmic road flow particle animations and vector stroke variations.
• ✨ AI-Generated Map Styles: Multimodal vision-to-cartography style transfer models.
• 🎨 Geographic Art: Abstract geometric morphing and Voronoi urban fabric parceling.
• 🧭 Interactive City Visualizations: Time-series transit overlays and animated flow networks.
• 🧊 3D City Art: Extruded 2.5D building heightmaps with dynamic sun ray casting and ambient occlusion.
• 📊 Data-Driven Artwork: Urban density heatmaps, elevation contours, and open demographic layers.

---

🛠️ Getting Started

Prerequisites

• Node.js 18+ (Node 20 recommended)
• npm 9+

Installation & Local Setup

# 1. Clone the repository
git clone https://github.com/fragompul/cartiva.git
cd cartiva

# 2. Install dependencies
npm install

# 3. Start the development server
npm run dev

# 4. Open in browser
# Navigate to http://localhost:5173

Development Scripts

Command	Description
npm run dev	Launch Vite local development server with HMR
npm run build	Compile TypeScript and produce production build
npm test	Run automated Vitest test suite
npm run type-check	Run strict TypeScript compiler verification
npm run preview	Preview production build locally

---

⚖️ Legal & Attribution

• Geographic data is sourced from OpenStreetMap under the Open Database License (ODbL).
• All exported artworks automatically include the required attribution: © OpenStreetMap contributors.

---

Author

Francisco Javier Gómez Pulido
AI Lead @ AAPEX | Double Degree in Mathematics & Computer Science | Master's in Artificial Intelligence

📫 Let's connect:

• LinkedIn: linkedin.com/in/frangomezpulido
• GitHub: github.com/fragompul
• Email: frangomezpulido2002@gmail.com

---

📄 License

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

---

⭐ Support & Community

If you like CARTIVA, please consider leaving a Star ⭐ on GitHub — it helps support continuous development and makes the project more visible to creators worldwide!